branch-1-6/Bio/Map/OrderedPosition.pm

   1 # BioPerl module for Bio::Map::OrderedPosition
   2 #
   3 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   4 #
   5 # Cared for by Sendu Bala <bix@sendu.me.uk>
   6 #
   7 # Copyright Chad Matsalla
   8 #
   9 # You may distribute this module under the same terms as perl itself
  10
  11 # POD documentation - main docs before the code
  12
  13 =head1 NAME
  14
  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.
  18
  19 =head1 SYNOPSIS
  20
  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]] );
  32
  33 =head1 DESCRIPTION
  34
  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.
  42
  43 No units are assumed here - units are handled by context of which Map
  44 a position is placed in.
  45
  46 Se Bio::Map::Position for additional information.
  47
  48 =head1 FEEDBACK
  49
  50 =head2 Mailing Lists
  51
  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.
  55
  56   bioperl-l@bioperl.org                  - General discussion
  57   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  58
  59 =head2 Support
  60
  61 Please direct usage questions or support issues to the mailing list:
  62
  63 I<bioperl-l@bioperl.org>
  64
  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.
  69
  70 =head2 Reporting Bugs
  71
  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:
  75
  76   http://bugzilla.open-bio.org/
  77
  78 =head1 AUTHOR - Chad Matsalla
  79
  80 Email bioinformatics1@dieselwurks.com
  81
  82 =head1 CONTRIBUTORS
  83
  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
  88
  89 =head1 APPENDIX
  90
  91 The rest of the documentation details each of the object methods.
  92 Internal methods are usually preceded with a _
  93
  94 =cut
  95
  96 # Let the code begin...
  97
  98 package Bio::Map::OrderedPosition;
  99 use strict;
 100
 101
 102 use base qw(Bio::Map::Position);
 103
 104 =head2 new
 105
 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
 111
 112 =cut
 113
 114 sub new {
 115     my($class,@args) = @_;
 116     my $self = $class->SUPER::new(@args);
 117
 118     my ($order) = $self->_rearrange([qw(ORDER)], @args);
 119     $order && $self->order($order);
 120
 121     return $self;
 122 }
 123
 124 =head2 order
 125
 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
 132
 133 =cut
 134
 135 sub order {
 136     my ($self, $order) = @_;
 137     if ($order) {
 138         $self->{'_order'} = $order;
 139     }
 140     return $self->{'_order'} || return;
 141 }
 142
 143 =head2 sortable
 144
 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
 153
 154 =cut
 155
 156 sub sortable {
 157     my $self = shift;
 158     return $self->order;
 159 }
 160
 161 =head2 equals
 162
 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
 168
 169 =cut
 170
 171 sub equals {
 172    my ($self,$compare) = @_;
 173    return 0 if (! defined $compare || ! $compare->isa('Bio::Map::OrderedPosition'));
 174    return ($compare->order == $self->order);
 175 }
 176
 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 comparisions and require these to be implemented
 180 # by objects closer to the specific type of data
 181
 182 =head2 less_than
 183
 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
 190
 191 =cut
 192
 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);
 197 }
 198
 199 =head2 greater_than
 200
 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
 207
 208 =cut
 209
 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);
 214 }
 215
 216 1;