Bio/Map/LinkageMap.pm

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