NAME

       Bio::Coordinate::Collection - Noncontinuous match between two coordinate sets

SYNOPSIS

         # create Bio::Coordinate::Pairs or other Bio::Coordinate::MapperIs somehow
         $pair1; $pair2;

         # add them into a Collection
         $collection = Bio::Coordinate::Collection->new;
         $collection->add_mapper($pair1);
         $collection->add_mapper($pair2);

         # create a position and map it
         $pos = Bio::Location::Simple->new (-start => 5, -end => 9 );
         $res = $collection->map($pos);
         $res->match->start == 1;
         $res->match->end == 5;

         # if mapping is many to one (*>1) or many-to-many (*>*)
         # you have to give seq_id not get unrelevant entries
         $pos = Bio::Location::Simple->new
             (-start => 5, -end => 9 -seq_id=>'clone1');

DESCRIPTION

       Generic, context neutral mapper to provide coordinate transforms between two disjoint
       coordinate systems. It brings into Bioperl the functionality from Ewan Birney's
       Bio::EnsEMBL::Mapper ported into current bioperl.

       This class is aimed for representing mapping between whole chromosomes and contigs, or
       between contigs and clones, or between sequencing reads and assembly. The submaps are
       automatically sorted, so they can be added in any order.

       To map coordinates to the other direction, you have to swap() the collection. Keeping
       track of the direction and ID restrictions are left to the calling code.

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 lists  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 the bugs and their
       resolution.  Bug reports can be submitted via the web:

         https://redmine.open-bio.org/projects/bioperl/

AUTHOR - Heikki Lehvaslaiho

       Email:  heikki-at-bioperl-dot-org

CONTRIBUTORS

       Ewan Birney, birney@ebi.ac.uk

APPENDIX

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

   add_mapper
        Title   : add_mapper
        Usage   : $obj->add_mapper($mapper)
        Function: Pushes one Bio::Coordinate::MapperI into the list of mappers.
                  Sets _is_sorted() to false.
        Example :
        Returns : 1 when succeeds, 0 for failure.
        Args    : mapper object

   mappers
        Title   : mappers
        Usage   : $obj->mappers();
        Function: Returns or sets a list of mappers.
        Example :
        Returns : array of mappers
        Args    : array of mappers

   each_mapper
        Title   : each_mapper
        Usage   : $obj->each_mapper();
        Function: Returns a list of mappers.
        Example :
        Returns : list of mappers
        Args    : none

   mapper_count
        Title   : mapper_count
        Usage   : my $count = $collection->mapper_count;
        Function: Get the count of the number of mappers stored
                  in this collection
        Example :
        Returns : integer
        Args    : none

   swap
        Title   : swap
        Usage   : $obj->swap;
        Function: Swap the direction of mapping;input <-> output
        Example :
        Returns : 1
        Args    :

   test
        Title   : test
        Usage   : $obj->test;
        Function: test that both components of all pairs are of the same length.
                  Ran automatically.
        Example :
        Returns : boolean
        Args    :

   map
        Title   : map
        Usage   : $newpos = $obj->map($pos);
        Function: Map the location from the input coordinate system
                  to a new value in the output coordinate system.
        Example :
        Returns : new value in the output coordinate system
        Args    : integer

   _map
        Title   : _map
        Usage   : $newpos = $obj->_map($simpleloc);
        Function: Internal method that does the actual mapping. Called multiple times
                  by map() if the location  to be mapped is a split location

        Example :
        Returns : new location in the output coordinate system or undef
        Args    : Bio::Location::Simple

   sort
        Title   : sort
        Usage   : $obj->sort;
        Function: Sort function so that all mappings are sorted by
                  input coordinate start
        Example :
        Returns : 1
        Args    :

   _is_sorted
        Title   : _is_sorted
        Usage   : $newpos = $obj->_is_sorted;
        Function: toggle for whether the (internal) coodinate mapper data are sorted
        Example :
        Returns : boolean
        Args    : boolean