Provided by: libbio-perl-perl_1.7.2-2_all bug

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:

         https://github.com/bioperl/bioperl-live/issues

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