/ 
bioperl-1.4
/ Bio::Map::Marker

NAME

Bio::Map::Marker - An central map object representing a generic marker that can have multiple location in several maps.

SYNOPSIS

  # get map objects somehow

  # a marker with complex localisation
  $o_usat = new Bio::Map::Marker (-name=>'Chad Super Marker 2',
				  -positions => [ [$map1, $position1], 
                                                  [$map1, $position2] 
						] );

  # The markers deal with Bio::Map::Position objects which can also
  # be explicitely created and passed on to markers as an array ref:
  $o_usat2 = new Bio::Map::Marker (-name=>'Chad Super Marker 3',
				  -positions => [ $pos1, 
                                                  $pos2 
						] );

  # a marker with unique position in a map
  $marker1 = new Bio::Map::Marker (-name=>'hypervariable1',
				   -map => $map1,
				   -position => 100
				   );

  # an other way of creating a marker with unique position in a map:
  $marker2 = new Bio::Map::Marker (-name=>'hypervariable2');
  $map1->add_marker($marker2);
  $marker2->position(100);

  # position method is a short cut for get/set'ing  unigue positions
  # which overwrites previous values
  # to place a marker to other maps or to have multiple positions 
  # for a map within the same map use add_position()

  $marker2->add_position(200);	# new position in the same map
  $marker2->add_position($map2,200); # new map

  # setting a map() in a marker or adding a marker into a map are
  # identical mathods. Both set the bidirectional connection which is
  # used by the marker to remember its latest, default map.

  # Regardes of how marker positions are created, they are stored and
  # returned as Bio::Map::PositionI objects:

  # unique position
  print $marker1->position->value, "\n";
  # several positions
  foreach $pos ($marker2->each_position($map1)) {
     print $pos->value, "\n";
  }

See Bio::Map::Position and Bio::Map::PositionI for more information.

DESCRIPTION

This object handles the notion of a generic marker. This marker will have a name and a position in a map.

This object is intended to be used by a marker parser like Mapmaker.pm and then blessed into the proper type of marker (ie Microsatellite) by the calling script.

Design principles

A Marker is a central object in Bio::Map name space. A Map is a holder class for objects. A Marker has a Position in a Map. A Marker can be compared to an other Markers using boolean methods. Positions can have non-numeric values or other methods to store the locations, so they have a method numeric() which does the conversion.

A Marker has a convinience method position() which is able to create Positions of required class from scalars by calling method get_position_object().

For more complex situations, a Marker can have multiple positions in multiple Maps. It is therefore possible to extract Positions (all or belonging to certain Map) and compare Markers to them. It is up to the programmer to make sure position values and Maps they belong to can be sensibly compared.

FEEDBACK

Mailing Lists

User feedback is an integral part of the evolution of this and other Bioperl modules. Send your comments and suggestions preferably to the Bioperl mailing list. Your participation is much appreciated.

bioperl-l@bioperl.org              - General discussion
http://bioperl.org/MailList.shtml  - About the mailing lists

Reporting Bugs

Report bugs to the Bioperl bug tracking system to help us keep track of the bugs and their resolution. Bug reports can be submitted via email or the web:

bioperl-bugs@bioperl.org
http://bugzilla.bioperl.org/

AUTHOR - Chad Matsalla

Email bioinformatics1@dieselwurks.com

CONTRIBUTORS

Heikki Lehvaslaiho heikki@ebi.ac.uk Lincoln Stein lstein@cshl.org Jason Stajich jason@bioperl.org

APPENDIX

The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _

new

 Title   : new
 Usage   : $o_marker = new Bio::Map::Marker( -name => 'Whizzy marker',
	                                     -position => $position);
 Function: Builds a new Bio::Map::Marker object
 Returns : Bio::Map::Marker
 Args    :
           -name    => name of this microsatellite 
                       [optional], string,default 'Unknown'

           -positions => map position for this marker, [optional]
                Bio::Map::PositionI-inherited obj, no default)

name

 Title   : name
 Usage   : $o_usat->name($new_name) _or_
	   my $name = $o_usat->name()
 Function: Get/Set the name for this Microsatellite
 Returns : A scalar representing the current name of this marker
 Args    : If provided, the current name of this marker
	   will be set to $new_name.

map

Title   : map
Usage   : my $mymap = $marker->map();
Function: Get/Set the default map for the marker.
          This is set by L<Bio::Map::CytoMap::add_element> method
Returns : L<Bio::Map::MapI>
Args    : [optional] new L<Bio::Map::MapI>

get_position_object

Title   : get_position_class
Usage   : my $pos = $marker->get_position_object();
Function: To get an object of the default Position class
          for this Marker. Subclasses should redefine this method.
          The Position needs to be Bio::Map::PositionI.
Returns : Bio::Map::Position
Args    : none

See Bio::Map::Position and Bio::Map::PositionI for more information.

position

Title   : position
Usage   : $position = $mappable->position($map); OR
          $mappable->position($position); # $position can be  Bio::Map::PositionI
          $mappable->position(100); # or scalar if the marker has a default map
          $mappable->position($map, 100); # if not give explicit $map
Function: Get/Set the Bio::Map::PositionI for a mappable element
          in a specific Map
          Adds the marker to a map automatically if Map is given. 
          Altenaitvely, you can add the merker to the map first 
          (L<Bio::Map::Map::add_element>) to set the default map
Returns : Bio::Map::PositionI
Args    : $position - Bio::Map::PositionI # Position we want to set
           OR
          $map  - Bio::Map::MapI AND
          scalar
           OR
          scalar, but only if the marker has been added to a map

add_position

Title   : add_position
Usage   : $position->add_position($position)
Function: Add the Position to the Marker container.
          If you are using this method, you need to 
          add the Marker to the Map yourself
Returns : none
Args    : Position - Reference to Bio::Map::PositionI

positions

Title   : positions
Usage   : $mappable->positions([$pos1, $pos2, $pos3]); 
Function: Add multiple Bio::Map::PositionI for a mappable element
          in a Map.
Returns : boolean
Args    : array ref of $map/value tuples or array ref of Positions

each_position

Title   : each_position
Usage   : my @positions = $position->each_position('mapname');
Function: Retrieve a list of Positions 
Returns : Array of L<Bio::Map::PositionI>
Args    : none

purge_positions

Title   : purge_positions
Usage   : $marker->purge_positions
Function: Remove all the position values stored for a Marker
Returns : none
Args    : [optional] only purge values for a given map

known_maps

Title   : known_maps
Usage   : my @maps = $marker->known_maps
Function: Returns the list of maps that this position has values for
Returns : list of Bio::Map::MapI unique ids
Args    : none

in_map

Title   : in_map
Usage   : if ( $position->in_map($map) ) {}
Function: Tests if a position has values in a specific map
Returns : boolean
Args    : a map unique id OR Bio::Map::MapI

Comparison methods

tuple

Title   : tuple
Usage   : ($me, $you) = $self->_tuple($compare)
Function: Utility ethod to extract numbers and test for missing values.
Returns : tuple values
Args    : Bio::Map::MappableI or Bio::Map::PositionI

equals

Title   : equals
Usage   : if( $mappable->equals($mapable2)) ...
Function: Test if a position is equal to another position
Returns : boolean
Args    : Bio::Map::MappableI or Bio::Map::PositionI

less_than

Title   : less_than
Usage   : if( $mappable->less_than($m2) ) ...
Function: Tests if a position is less than another position
Returns : boolean
Args    : Bio::Map::MappableI  or Bio::Map::PositionI

greater_than

Title   : greater_than
Usage   : if( $mappable->greater_than($m2) ) ...
Function: Tests if position is greater than another position
Returns : boolean
Args    : Bio::Map::MappableI or Bio::Map::PositionI