Bio/Map/Microsatellite.pm

   1 # BioPerl module for Bio::Map::Microsatellite
   2 #
   3 # Cared for by Sendu Bala <bix@sendu.me.uk>
   4 #
   5 # Copyright Chad Matsalla
   6 #
   7 # You may distribute this module under the same terms as perl itself
   8
   9 # POD documentation - main docs before the code
  10
  11 =head1 NAME
  12
  13 Bio::Map::Microsatellite - An object representing a Microsatellite marker.
  14
  15 =head1 SYNOPSIS
  16
  17   $o_usat = Bio::Map::Microsatellite->new
  18       (-name=>'Chad Super Marker 2',
  19        -sequence => 'gctgactgatcatatatatatatatatatatatatatatatcgcgatcgtga',
  20        -motif => 'at',
  21        -repeats => 15,
  22        -repeat_start_position => 11
  23        );
  24
  25   $sequence_before_usat = $o_usat->get_leading_flank();
  26   $sequence_after_usat = $o_usat->get_trailing_flank();
  27
  28
  29 =head1 DESCRIPTION
  30
  31 This object handles the notion of an Microsatellite. This microsatellite can
  32 be placed on a (linear) Map or used on its own.  If this Microsatellites
  33 will be used in a mapping context (it doesn't have to, you know) it can have
  34 multiple positions in a map. For information about a Microsatellite's position
  35 in a map one must query the associate PositionI object which is accessible
  36 through the position() method.
  37
  38 =head1 FEEDBACK
  39
  40 =head2 Mailing Lists
  41
  42 User feedback is an integral part of the evolution of this and other
  43 Bioperl modules. Send your comments and suggestions preferably to
  44 the Bioperl mailing list.  Your participation is much appreciated.
  45
  46   bioperl-l@bioperl.org                  - General discussion
  47   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  48
  49 =head2 Reporting Bugs
  50
  51 Report bugs to the Bioperl bug tracking system to help us keep track
  52 of the bugs and their resolution. Bug reports can be submitted via the
  53 web:
  54
  55   http://bugzilla.open-bio.org/
  56
  57 =head1 AUTHOR - Chad Matsalla
  58
  59 Email bioinformatics1@dieselwurks.com
  60
  61 =head1 CONTRIBUTORS
  62
  63 Heikki Lehvaslaiho heikki-at-bioperl-dot-org
  64 Lincoln Stein      lstein@cshl.org
  65 Jason Stajich      jason@bioperl.org
  66 Sendu Bala         bix@sendu.me.uk
  67
  68 =head1 APPENDIX
  69
  70 The rest of the documentation details each of the object methods.
  71 Internal methods are usually preceded with a _
  72
  73 =cut
  74
  75 # Let the code begin...
  76
  77 package Bio::Map::Microsatellite;
  78 use strict;
  79
  80 use base qw(Bio::Map::Marker);
  81
  82 =head2 new
  83
  84  Title   : new
  85  Usage   : $o_usat =
  86  Function: Builds a new Bio::Map::Microsatellite object
  87  Returns : Bio::Map::Microsatellite
  88  Args    :
  89         -name    => name of this microsatellite (optional, string,
  90                 default 'Unknown microsatellite')
  91         -positions => position(s) for this marker in maps[optional],
  92                 An array reference of tuples (array refs themselves)
  93                 Each tuple conatins a Bio::Map::MapI-inherited object and a
  94                 Bio::Map::PositionI-inherited obj, no default)
  95         -sequence => the sequence of this microsatellite (optional,
  96                  scalar, no default)
  97         -motif => the repeat motif of this microsatellite (optional,
  98                  scalar, no default)
  99         -repeats => the number of motif repeats for this microsatellite
 100                 (optional, scalar, no default)
 101         -repeat_start_position => the starting position of the
 102                 microsatellite in this sequence. The first base of the
 103                 sequence is position "1". (optional, scalar, no default)
 104
 105  Note    : Creating a Bio::Map::Microsatellite object with no position
 106         might be useful for microsatellite people wanting to embrace
 107         and extend this module. <raising hand> Me! Me! Me!
 108         - using repeat_start_position will trigger a mechinism to
 109         calculate a value for repeat_end_position.
 110
 111
 112 =cut
 113
 114 sub new {
 115     my ($class,@args) = @_;
 116     my $self = $class->SUPER::new(@args);
 117     my ($map, $position, $sequence, $motif, $repeats, $start) =
 118         $self->_rearrange([qw(MAP
 119                               POSITION
 120                               SEQUENCE
 121                               MOTIF
 122                               REPEATS
 123                               REPEAT_START_POSITION
 124                               )], @args);
 125     if( ! $self->name ) {
 126         $self->name('Unnamed microsatellite');
 127     }
 128     $map && $self->map($map);
 129     $position && $self->position($position);
 130     $sequence && $self->sequence($sequence);
 131     $self->motif(defined $motif ? $motif : 'Unknown motif');
 132     $repeats && $self->repeats($repeats);
 133     $start && $self->repeat_start_position($start);
 134     return $self;
 135 }
 136
 137 =head2 motif
 138
 139  Title   : motif
 140  Usage   : $o_usat->motif($new_motif);
 141                my $motif = $o_usat->motif();
 142  Function: Get/Set the repeat motif for this Microsatellite.
 143  Returns : A scalar representing the current repeat motif of this
 144                Microsatellite.
 145  Args    : none to get, OR string to set
 146
 147 =cut
 148
 149 sub motif {
 150         my ($self,$motif) = @_;
 151         if ($motif) {
 152                 $self->{'_motif'} = $motif;
 153         }
 154         return $self->{'_motif'};
 155 }
 156
 157 =head2 sequence
 158
 159  Title   : sequence
 160  Usage   : $o_usat->sequence($new_sequence);
 161                my $sequence = $o_usat->sequence();
 162  Function: Get/Set the sequence for this Microsatellite.
 163  Returns : A scalar representing the current sequence of this
 164                Microsatellite.
 165  Args    : none to get, OR string to set
 166
 167 =cut
 168
 169 sub sequence {
 170         my ($self,$sequence) = @_;
 171         if ($sequence) {
 172                 $self->{'_sequence'} = $sequence;
 173         }
 174         return $self->{'_sequence'};
 175 }
 176
 177 =head2 repeats
 178
 179  Title   : repeats
 180  Usage   : $o_usat->repeats($new_repeats);
 181                my $repeats = $o_usat->repeats()
 182  Function: Get/Set the repeat repeats for this Microsatellite.
 183  Returns : A scalar representing the current number of repeats of this
 184                Microsatellite.
 185  Args    : none to get, OR int to set
 186
 187 =cut
 188
 189 sub repeats {
 190         my ($self,$repeats) = @_;
 191         if ($repeats) {
 192                 $self->{'_repeats'} = $repeats;
 193         }
 194         return $self->{'_repeats'};
 195 }
 196
 197 =head2 repeat_start_position
 198
 199  Title   : repeat_start_position
 200  Usage   : $o_usat->repeat_start_position($new_repeat_start_position);
 201                my $repeat_start_position = $o_usat->repeat_start_position();
 202  Function: Get/Set the repeat repeat_start_position for this
 203                Microsatellite
 204  Returns : A scalar representing the repeat start position for this
 205                Microsatellite.
 206  Args    : none to get, OR string to set
 207                This method will also try to set the repeat end position. This
 208                depends on having information for the motif and the number of
 209                repeats. If you want to use methods like get_trailing_flank or
 210                get_leading flank, be careful to include the right information.
 211
 212 =cut
 213
 214 sub repeat_start_position {
 215         my ($self,$repeat_start_position) = @_;
 216         if ($repeat_start_position) {
 217                 $self->{'_repeat_start_position'} = $repeat_start_position;
 218                 $self->repeat_end_position("set");
 219         }
 220         return $self->{'_repeat_start_position'};
 221 }
 222
 223 =head2 repeat_end_position
 224
 225  Title   : repeat_end_position
 226  Usage   : $o_usat->repeat_end_position("set");
 227                $o_usat->repeat_end_position($value);
 228                $current_repeat_end_position = $o_usat->repeat_end_position();
 229  Function: Get/set the end position of the repeat in this sequence.
 230  Returns : A scalar representing the base index of the end of the
 231                repeat in this Microsatellite. The first base in the sequence
 232                is base 1.
 233  Args    : A scalar representing a value, the string "set", or no
 234                argument (see Notes).
 235  Notes   : If you do not provide an argument to this method, the current
 236            end position of the repeat in this Microsatellite will be
 237            returned (a scalar).
 238            If you provide the string "set" to this method it will set the
 239            end position based on the start position, the length of the
 240            motif, and the number of repeats.
 241            If you specify a value the current end position of the repeat
 242            will be set to that value. This is a really bad idea. Don't do
 243            it.
 244
 245 =cut
 246
 247 sub repeat_end_position {
 248     my ($self,$caller) = @_;
 249     if( defined $caller ) {
 250         if ($caller eq "set") {
 251             $self->{'_repeat_end_position'} =
 252                 $self->{'_repeat_start_position'} +
 253                     (length($self->motif()) * $self->repeats());
 254         }
 255         elsif ($caller) {
 256             $self->{'_repeat_end_position'} = $caller;
 257         }
 258     }
 259     return $self->{'_repeat_end_position'};
 260 }
 261
 262 =head2 equals
 263
 264  Title   : equals
 265  Usage   : if ($mappable->equals($mapable2)) {...}
 266  Function: Test if a position is equal to another position
 267  Returns : boolean
 268  Args    : Bio::Map::MappableI
 269
 270 =cut
 271
 272 sub equals {
 273         my ($self,@args) = @_;
 274         $self->throw_not_implemented();
 275 }
 276
 277 =head2 less_than
 278
 279  Title   : less_than
 280  Usage   : if ($mappable->less_than($m2)) {...}
 281  Function: Tests if a position is less than another position
 282  Returns : boolean
 283  Args    : Bio::Map::MappableI
 284
 285 =cut
 286
 287 sub less_than {
 288         my ($self,@args) = @_;
 289         $self->throw_not_implemented();
 290 }
 291
 292 =head2 greater_than
 293
 294  Title   : greater_than
 295  Usage   : if ($mappable->greater_than($m2)) {...}
 296  Function: Tests if position is greater than another position
 297  Returns : boolean
 298  Args    : Bio::Map::MappableI
 299
 300 =cut
 301
 302 sub greater_than {
 303         my ($self,@args) = @_;
 304         $self->throw_not_implemented();
 305 }
 306
 307 =head2 get_leading_flank
 308
 309  Title   : get_leading_flank
 310  Usage   : $leading_sequence = $o_usat->get_leading_flank();
 311  Returns : A scalar representing the sequence before the repeats in this
 312                Microsatellite.
 313  Args    : none
 314
 315 =cut
 316
 317 sub get_leading_flank {
 318         my $self = shift;
 319         return substr $self->sequence(),0,$self->repeat_start_position-1;
 320 }
 321
 322 =head2 get_trailing_flank
 323
 324  Title   : get_trailing_flank
 325  Usage   : $trailing_flank = $o_usat->get_trailing_flank();
 326  Returns : A scalar representing the sequence after the repeats in this
 327                Microsatellite.
 328  Args    : none
 329
 330 =cut
 331
 332 sub get_trailing_flank {
 333         my $self = shift;
 334         return substr $self->sequence(),$self->repeat_end_position()-1;
 335 }
 336
 337 1;