Bio/Map/LinkageMap.pm

   1 # BioPerl module for Bio::Map::LinkageMap
   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::LinkageMap - A representation of a genetic linkage map.
  14
  15 =head1 SYNOPSIS
  16
  17     use Bio::Map::LinkageMap;
  18         # create a new map
  19     my $map = Bio::Map::LinkageMap->new(-name => 'Chads Superterriffic Map',
  20                                       -type => 'Linkage',
  21                                       -units=> 'cM');
  22         # create the location of a marker for that map
  23     my $position = Bio::Map::LinkagePosition->new( -positions => 1,
  24                 -distance => "22.3");
  25         # create a marker and place it at that position
  26     my $marker = Bio::Map::Marker::Microsatellite->new(
  27                         -name => 'SuuuperMarker',
  28                         -position => $position);
  29         # place that marker on that map
  30     $map->add_element($marker);
  31
  32         # done!
  33
  34 =head1 DESCRIPTION
  35
  36 This object describes the basic functionality of a genetic linkage map in
  37 Bioperl. Each 'position' can have one or more markers that map some number of
  38 units from the markers at the previous position.
  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 Reporting Bugs
  52
  53 Report bugs to the Bioperl bug tracking system to help us keep track
  54 of the bugs and their resolution. Bug reports can be submitted via the
  55 web:
  56
  57   http://bugzilla.open-bio.org/
  58
  59 =head1 AUTHOR - Chad Matsalla
  60
  61 Email bioinformatics1@dieselwurks.com
  62
  63 =head1 CONTRIBUTORS
  64
  65 Lincoln Stein       lstein@cshl.org
  66 Heikki Lehvaslaiho  heikki-at-bioperl-dot-org
  67 Jason Stajich       jason@bioperl.org
  68 Sendu Bala          bix@sendu.me.uk
  69
  70 =head1 APPENDIX
  71
  72 The rest of the documentation details each of the object methods.
  73 Internal methods are usually preceded with a _
  74
  75 =cut
  76
  77 # Let the code begin...
  78
  79 package Bio::Map::LinkageMap;
  80 use strict;
  81
  82 use base qw(Bio::Map::SimpleMap);
  83
  84 =head2 new
  85
  86  Title   : new
  87  Usage   : my $linkage_map = Bio::Map::LinkageMap->new();
  88  Function: Builds a new Bio::Map::LinkageMap object
  89  Returns : Bio::Map::LinkageMap
  90  Args    : -name    => the name of the map (string) [optional]
  91                -type    => the type of this map (string, defaults to Linkage) [optional]
  92            -species => species for this map (Bio::Species) [optional]
  93            -units   => the map units (string, defaults to cM) [optional]
  94            -elements=> elements to initialize with
  95                        (arrayref of Bio::Map::MappableI objects) [optional]
  96            -uid      => Unique ID of this map
  97
  98 =cut
  99
 100 =head2 length
 101
 102  Title   : length
 103  Usage   : my $length = $map->length();
 104  Function: Retrieves the length of the map. In the case of a LinkageMap, the
 105                length is the sum of all marker distances.
 106  Returns : An integer representing the length of this LinkageMap. Will return
 107                0 if length is not calculateable
 108  Args    : None.
 109
 110
 111 =cut
 112
 113 sub length {
 114     my ($self) = @_;
 115     $self->throw("Not yet implemented correctly");
 116
 117     my $total_distance;
 118     foreach my $element (@{$self->get_elements}) {
 119         #*** there is no such method ->each_position_value!
 120         $total_distance += ($element->position->each_position_value($self))[0];
 121     }
 122     return $total_distance;
 123 }
 124
 125 =head2 add_element($marker)
 126
 127  Title   : add_element($marker)
 128  Usage   : $map->add_element($marker)
 129  Function: Add a Bio::Map::MappableI object to the Map
 130  Returns : none
 131  Args    : Bio::Map::MappableI object
 132  Notes   : It is strongly recommended that you use a
 133            Bio::Map::LinkagePosition as the position in any
 134            Bio::Map::Mappable that you create to place on this
 135            map. Using some other Bio::Map::Position might work but might
 136            be unpredictable.
 137            N.B. I've added Bio::Map::OrderedPosition which should achieve
 138                 similar things from LinkagePosition and will work for
 139                 RH markers too.
 140 =cut
 141
 142 #*** what is this? what calls it? note that it seems to be private
 143 sub _add_element_will_be_deleted {
 144     my ($self,$marker) = @_;
 145
 146     my $o_position = $marker->position();
 147
 148     $self->debug( "marker position is ". $marker->position());
 149 #     print("add_element: \$o_position is $o_position\n");
 150 #     print("add_element: \$marker is $marker\n");
 151
 152     my $position;
 153     unless ( $o_position->isa('Bio::Map::LinkagePosition') ||
 154              $o_position->isa('Bio::Map::OrderedPosition')
 155              ) {
 156         $self->warn("You really should use a Linkage Position for this object. This insures that there is only one position. Trying anyway...");
 157         my @p = ( $o_position->each_position_value($self));
 158         $position = shift @p;
 159         if( ! defined $position ) {
 160             $self->throw("This marker ($marker) does not have a position in this map ($self)");
 161         }
 162     } else {
 163         $position = $o_position->order;
 164     }
 165
 166     if ($self->{'_elements'}[$position]) {
 167         $self->warn("Replacing the marker in position $position because in a linkage map the position is a key.");
 168     }
 169     $self->{'_elements'}[$position] = $marker;
 170 }
 171
 172 1;