Bio/Map/Microsatellite.pm

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