Bio::Map::Mappable(3)

NAME
Bio::Map::Mappable - An object representing a generic map element that can have multiple locations in several maps.

SYNOPSIS
  # a map element in two different positions on the same map
  $map1 = Bio::Map::SimpleMap->new();
  $position1 = Bio::Map::Position->new(-map => $map1, -value => 100);
  $position2 = Bio::Map::Position->new(-map => $map1, -value => 200);
  $mappable = Bio::Map::Mappable->new(-positions => [$position1, $position2] );

  # add another position on a different map
  $map2 = Bio::Map::SimpleMap->new();
  $position3 = Bio::Map::Position->new(-map => $map2, $value => 50);
  $mappable->add_position($position3);

  # get all the places our map element is found, on a particular map of interest
  foreach $pos ($mappable->get_positions($map1)) {
     print $pos->value, "\n";
  }

DESCRIPTION
This object handles the notion of a generic map element. Mappables are entities with one or more positions on one or more maps.

This object is a pure perl implementation of Bio::Map::MappableI. That interface implements some of its own methods so check the docs there for those.

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/wiki/Mailing_lists  - About the mailing lists

  Support
Please direct usage questions or support issues to the mailing list:

bioperl-l@bioperl.org

rather than to the module maintainer directly. Many experienced and reponsive experts will be able look at the problem and quickly address it. Please include a thorough description of the problem with code and data examples if at all possible.

  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 the web:

  http://bugzilla.open-bio.org/

AUTHOR - Sendu Bala
Email bix@sendu.me.uk

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

  new
 Title   : new
 Usage   : my $mappable = Bio::Map::Mappable->new();
 Function: Builds a new Bio::Map::Mappable object
 Returns : Bio::Map::Mappable
 Args    : -name => string : name of the mappable element
           -id   => string : id of the mappable element

  name
 Title   : name
 Usage   : $mappable->name($new_name);
               my $name = $mappable->name();
 Function: Get/Set the name for this Mappable
 Returns : A scalar representing the current name of this Mappable
 Args    : none to get
           string to set

  id
 Title   : id
 Usage   : my $id = $mappable->id();
           $mappable->id($new_id);
 Function: Get/Set the id for this Mappable.
 Returns : A scalar representing the current id of this Mappable
 Args    : none to get
           string to set

  in_map
 Title   : in_map
 Usage   : if ($mappable->in_map($map)) {...}
 Function: Tests if this mappable is found on a specific map
 Returns : boolean
 Args    : L<Bio::Map::MapI>

  Comparison methods

  equals
 Title   : equals
 Usage   : if ($mappable->equals($other_mappable)) {...}
           my @equal_positions = $mappable->equals($other_mappable);
 Function: Finds the positions in this mappable that are equal to any
           comparison positions.
 Returns : array of L<Bio::Map::PositionI> objects
 Args    : arg #1 = L<Bio::Map::MappableI> OR L<Bio::Map::PositionI> to compare
                    this one to (mandatory)
           arg #2 = optionally, one or more of the key => value pairs below
                   -map => MapI           : a Bio::Map::MapI to only consider positions
                                            on the given map
                   -relative => RelativeI : a Bio::Map::RelativeI to calculate in terms
                                    of each Position's relative position to the
                                    thing described by that Relative

  less_than
 Title   : less_than
 Usage   : if ($mappable->less_than($other_mappable)) {...}
           my @lesser_positions = $mappable->less_than($other_mappable);
 Function: Finds the positions in this mappable that are less than all
           comparison positions.
 Returns : array of L<Bio::Map::PositionI> objects
 Args    : arg #1 = L<Bio::Map::MappableI> OR L<Bio::Map::PositionI> to compare
                    this one to (mandatory)
           arg #2 = optionally, one or more of the key => value pairs below
                   -map => MapI           : a Bio::Map::MapI to only consider positions
                                            on the given map
                   -relative => RelativeI : a Bio::Map::RelativeI to calculate in terms
                                    of each Position's relative position to the
                                    thing described by that Relative

  greater_than
 Title   : greater_than
 Usage   : if ($mappable->greater_than($other_mappable)) {...}
           my @greater_positions = $mappable->greater_than($other_mappable);
 Function: Finds the positions in this mappable that are greater than all
           comparison positions.
 Returns : array of L<Bio::Map::PositionI> objects
 Args    : arg #1 = L<Bio::Map::MappableI> OR L<Bio::Map::PositionI> to compare
                    this one to (mandatory)
           arg #2 = optionally, one or more of the key => value pairs below
                   -map => MapI           : a Bio::Map::MapI to only consider positions
                                            on the given map
                   -relative => RelativeI : a Bio::Map::RelativeI to calculate in terms
                                    of each Position's relative position to the
                                    thing described by that Relative

  overlaps
 Title   : overlaps
 Usage   : if ($mappable->overlaps($other_mappable)) {...}
           my @overlapping_positions = $mappable->overlaps($other_mappable);
 Function: Finds the positions in this mappable that overlap with any
           comparison positions.
 Returns : array of L<Bio::Map::PositionI> objects
 Args    : arg #1 = L<Bio::Map::MappableI> OR L<Bio::Map::PositionI> to compare
                    this one to (mandatory)
           arg #2 = optionally, one or more of the key => value pairs below
                   -map => MapI           : a Bio::Map::MapI to only consider positions
                                            on the given map
                   -relative => RelativeI : a Bio::Map::RelativeI to calculate in terms
                                    of each Position's relative position to the
                                    thing described by that Relative

  contains
 Title   : contains
 Usage   : if ($mappable->contains($other_mappable)) {...}
           my @container_positions = $mappable->contains($other_mappable);
 Function: Finds the positions in this mappable that contain any comparison
           positions.
 Returns : array of L<Bio::Map::PositionI> objects
 Args    : arg #1 = L<Bio::Map::MappableI> OR L<Bio::Map::PositionI> to compare
                    this one to (mandatory)
           arg #2 = optionally, one or more of the key => value pairs below
                   -map => MapI           : a Bio::Map::MapI to only consider positions
                                            on the given map
                   -relative => RelativeI : a Bio::Map::RelativeI to calculate in terms
                                    of each Position's relative position to the
                                    thing described by that Relative

  overlapping_groups
 Title   : overlapping_groups
 Usage   : my @groups = $mappable->overlapping_groups($other_mappable);
           my @groups = Bio::Map::Mappable->overlapping_groups(\@mappables);
 Function: Look at all the positions of all the supplied mappables and group
           them according to overlap.
 Returns : array of array refs, each ref containing the Bio::Map::PositionI
           objects that overlap with each other
 Args    : arg #1 = L<Bio::Map::MappableI> OR L<Bio::Map::PositionI> to  compare
                    this one to, or an array ref of such objects (mandatory)
           arg #2 = optionally, one or more of the key => value pairs below
                   -map => MapI           : a Bio::Map::MapI to only consider positions
                                            on the given map
                   -relative => RelativeI : a Bio::Map::RelativeI to calculate in terms
                                    of each Position's relative position to the
                                    thing described by that Relative
           -min_pos_num => int    : the minimum number of positions that must
                                    be in a group before it will be returned
                                    [default is 1]
           -min_mappables_num => int        : the minimum number of different
                                              mappables represented by the
                                              positions in a group before it
                                              will be returned [default is 1]
           -min_mappables_percent => number : as above, but the minimum
                                              percentage of input mappables
                                              [default is 0]
           -min_map_num => int              : the minimum number of different
                                              maps represented by the positions
                                              in a group before it will be
                                              returned [default is 1]
           -min_map_percent => number       : as above, but the minimum
                                              percentage of maps known by the
                                              input mappables [default is 0]
           -require_self => 1|0             : require that at least one of the
                                              calling object's positions be in
                                              each group [default is 1, has no
                                              effect when the second usage form
                                              is used]
           -required => \@mappables         : require that at least one position
                                              for each mappable supplied in this
                                              array ref be in each group

  disconnected_intersections
 Title   : disconnected_intersections
 Usage   : @positions = $mappable->disconnected_intersections($other_mappable);
           @positions = Bio::Map::Mappable->disconnected_intersections(\@mappables);
 Function: Make the positions that are at the intersection of each group of
           overlapping positions, considering all the positions of the supplied
           mappables.
 Returns : new Bio::Map::Mappable who's positions on maps are the calculated
           disconnected unions
 Args    : arg #1 = L<Bio::Map::MappableI> OR L<Bio::Map::PositionI> to  compare
                    this one to, or an array ref of such objects (mandatory)
           arg #2 = optionally, one or more of the key => value pairs below
                   -map => MapI           : a Bio::Map::MapI to only consider positions
                                            on the given map
                   -relative => RelativeI : a Bio::Map::RelativeI to calculate in terms
                                    of each Position's relative position to the
                                    thing described by that Relative
           -min_pos_num => int    : the minimum number of positions that must
                                    be in a group before the intersection will
                                    be calculated and returned [default is 1]
           -min_mappables_num => int        : the minimum number of different
                                              mappables represented by the
                                              positions in a group before the
                                              intersection will be calculated
                                              and returned [default is 1]
           -min_mappables_percent => number : as above, but the minimum
                                              percentage of input mappables
                                              [default is 0]
           -min_map_num => int              : the minimum number of different
                                              maps represented by the positions
                                              in a group before the intersection
                                              will be calculated and returned
                                              [default is 1]
           -min_map_percent => number       : as above, but the minimum
                                              percentage of maps known by the
                                              input mappables [default is 0]
           -require_self => 1|0             : require that at least one of the
                                              calling object's positions be in
                                              each group [default is 1, has no
                                              effect when the second usage form
                                              is used]
           -required => \@mappables         : require that at least one position
                                              for each mappable supplied in this
                                              array ref be in each group

  disconnected_unions
 Title   : disconnected_unions
 Usage   : my @positions = $mappable->disconnected_unions($other_mappable);
           my @positions = Bio::Map::Mappable->disconnected_unions(\@mappables);
 Function: Make the positions that are the union of each group of overlapping
           positions, considering all the positions of the supplied mappables.
 Returns : new Bio::Map::Mappable who's positions on maps are the calculated
           disconnected unions
 Args    : arg #1 = L<Bio::Map::MappableI> OR L<Bio::Map::PositionI> to  compare
                    this one to, or an array ref of such objects (mandatory)
           arg #2 = optionally, one or more of the key => value pairs below
                   -map => MapI           : a Bio::Map::MapI to only consider positions
                                            on the given map
                   -relative => RelativeI : a Bio::Map::RelativeI to calculate in terms
                                    of each Position's relative position to the
                                    thing described by that Relative
           -min_pos_num => int    : the minimum number of positions that must
                                    be in a group before the union will be
                                    calculated and returned [default is 1]
           -min_mappables_num => int        : the minimum number of different
                                              mappables represented by the
                                              positions in a group before the
                                              union will be calculated and
                                              returned [default is 1]
           -min_mappables_percent => number : as above, but the minimum
                                              percentage of input mappables
                                              [default is 0]
           -min_map_num => int              : the minimum number of different
                                              maps represented by the positions
                                              in a group before the union will
                                              be calculated and returned
                                              [default is 1]
           -min_map_percent => number       : as above, but the minimum
                                              percentage of maps known by the
                                              input mappables [default is 0]
           -require_self => 1|0             : require that at least one of the
                                              calling object's positions be in
                                              each group [default is 1, has no
                                              effect when the second usage form
                                              is used]
           -required => \@mappables         : require that at least one position
                                              for each mappable supplied in this
                                              array ref be in each group

  tuple
 Title   : tuple
 Usage   : Do Not Use!
 Function: tuple was supposed to be a private method; this method no longer
           does anything
 Returns : warning
 Args    : none
 Status  : deprecated, will be removed in next version

  annotation
 Title   : annotation
 Usage   : $mappable->annotation($an_col);
           my $an_col = $mappable->annotation();
 Function: Get the annotation collection (see Bio::AnnotationCollectionI)
           for this annotatable object.
 Returns : a Bio::AnnotationCollectionI implementing object, or undef
 Args    : none to get, OR
           a Bio::AnnotationCollectionI implementing object to set