t/AlignIO/AlignIO.t: fix number of tests in plan (fixup c523e6bed866)
[bioperl-live.git] / Bio / Map / OrderedPosition.pm
blob1f54dd1e9b097f6b3ffe1c50b46d22d1ac439cc1
1 # BioPerl module for Bio::Map::OrderedPosition
3 # Please direct questions and support issues to <bioperl-l@bioperl.org>
5 # Cared for by Sendu Bala <bix@sendu.me.uk>
7 # Copyright Chad Matsalla
9 # You may distribute this module under the same terms as perl itself
11 # POD documentation - main docs before the code
13 =head1 NAME
15 Bio::Map::OrderedPosition - Abstracts the notion of a member
16 of an ordered list of markers. Each marker is a certain distance
17 from the one in the ordered list before it.
19 =head1 SYNOPSIS
21 use Bio::Map::OrderedPosition;
22 # the first marker in the sequence
23 my $position = Bio::Map::OrderedPosition->new(-order => 1,
24 -positions => [ [ $map, 22.3] ] );
25 # the second marker in the sequence, 15.6 units from the fist one
26 my $position2 = Bio::Map::OrderedPosition->new(-order => 2,
27 -positions => [ [ $map, 37.9] ] );
28 # the third marker in the sequence, coincidental with the second
29 # marker
30 my $position3 = Bio::Map::OrderedPosition->new(-order => 3,
31 -posititions => [ [ $map, 37.9]] );
33 =head1 DESCRIPTION
35 This object is an implementation of the PositionI interface and the
36 Position object handles the specific values of a position.
37 OrderedPosition is intended to be slightly more specific then Position
38 but only specific enough for a parser from the MarkerIO subsystem to
39 create and then pass to a client application to bless into the proper
40 type. For an example of how this is intended to work, see the
41 Mapmaker.pm.
43 No units are assumed here - units are handled by context of which Map
44 a position is placed in.
46 Se Bio::Map::Position for additional information.
48 =head1 FEEDBACK
50 =head2 Mailing Lists
52 User feedback is an integral part of the evolution of this and other
53 Bioperl modules. Send your comments and suggestions preferably to
54 the Bioperl mailing list. Your participation is much appreciated.
56 bioperl-l@bioperl.org - General discussion
57 http://bioperl.org/wiki/Mailing_lists - About the mailing lists
59 =head2 Support
61 Please direct usage questions or support issues to the mailing list:
63 I<bioperl-l@bioperl.org>
65 rather than to the module maintainer directly. Many experienced and
66 reponsive experts will be able look at the problem and quickly
67 address it. Please include a thorough description of the problem
68 with code and data examples if at all possible.
70 =head2 Reporting Bugs
72 Report bugs to the Bioperl bug tracking system to help us keep track
73 of the bugs and their resolution. Bug reports can be submitted via the
74 web:
76 https://github.com/bioperl/bioperl-live/issues
78 =head1 AUTHOR - Chad Matsalla
80 Email bioinformatics1@dieselwurks.com
82 =head1 CONTRIBUTORS
84 Lincoln Stein, lstein@cshl.org
85 Heikki Lehvaslaiho, heikki-at-bioperl-dot-org
86 Jason Stajich, jason@bioperl.org
87 Sendu Bala, bix@sendu.me.uk
89 =head1 APPENDIX
91 The rest of the documentation details each of the object methods.
92 Internal methods are usually preceded with a _
94 =cut
96 # Let the code begin...
98 package Bio::Map::OrderedPosition;
99 use strict;
102 use base qw(Bio::Map::Position);
104 =head2 new
106 Title : new
107 Usage : my $obj = Bio::Map::OrderedPosition->new();
108 Function: Builds a new Bio::Map::OrderedPosition object
109 Returns : Bio::Map::OrderedPosition
110 Args : -order : The order of this position
112 =cut
114 sub new {
115 my($class,@args) = @_;
116 my $self = $class->SUPER::new(@args);
118 my ($order) = $self->_rearrange([qw(ORDER)], @args);
119 $order && $self->order($order);
121 return $self;
124 =head2 order
126 Title : order
127 Usage : $o_position->order($new_order);
128 my $order = $o_position->order();
129 Function: Get/set the order position of this position in a map.
130 Returns : int, the order of this position
131 Args : none to get, OR int to set
133 =cut
135 sub order {
136 my ($self, $order) = @_;
137 if ($order) {
138 $self->{'_order'} = $order;
140 return $self->{'_order'} || return;
143 =head2 sortable
145 Title : sortable
146 Usage : my $num = $position->sortable();
147 Function: Read-only method that is guaranteed to return a value suitable
148 for correctly sorting this kind of position amongst other positions
149 of the same kind on the same map. Note that sorting different kinds
150 of position together is unlikely to give sane results.
151 Returns : numeric
152 Args : none
154 =cut
156 sub sortable {
157 my $self = shift;
158 return $self->order;
161 =head2 equals
163 Title : equals
164 Usage : if ($mappable->equals($mapable2)) {...}
165 Function: Test if a position is equal to another position.
166 Returns : boolean
167 Args : Bio::Map::PositionI
169 =cut
171 sub equals {
172 my ($self,$compare) = @_;
173 return 0 if (! defined $compare || ! $compare->isa('Bio::Map::OrderedPosition'));
174 return ($compare->order == $self->order);
177 # admittedly these aren't really the best comparisons in the world
178 # but it is a first pass we'll need to refine the algorithm or not
179 # provide general comparisons and require these to be implemented
180 # by objects closer to the specific type of data
182 =head2 less_than
184 Title : less_than
185 Usage : if ($mappable->less_than($m2)) {...}
186 Function: Tests if a position is less than another position
187 It is assumed that 2 positions are in the same map.
188 Returns : boolean
189 Args : Bio::Map::PositionI
191 =cut
193 sub less_than {
194 my ($self,$compare) = @_;
195 return 0 if (! defined $compare || ! $compare->isa('Bio::Map::OrderedPosition'));
196 return ($compare->order < $self->order);
199 =head2 greater_than
201 Title : greater_than
202 Usage : if ($mappable->greater_than($m2)) {...}
203 Function: Tests if position is greater than another position.
204 It is assumed that 2 positions are in the same map.
205 Returns : boolean
206 Args : Bio::Map::PositionI
208 =cut
210 sub greater_than {
211 my ($self,$compare) = @_;
212 return 0 if (! defined $compare || ! $compare->isa('Bio::Map::OrderedPosition'));
213 return ($compare->order > $self->order);