Provided by: libbio-coordinate-perl_1.7.1-2_all bug

NAME

       Bio::Coordinate::GeneMapper - Transformations between gene related coordinate systems.

VERSION

       version 1.007001

SYNOPSIS

         use Bio::Coordinate::GeneMapper;

         # get a Bio::RangeI representing the start, end and strand of the CDS
         # in chromosomal (or entry) coordinates
         my $cds;

         # get a Bio::Location::Split or an array of Bio::LocationI objects
         # holding the start, end and strand of all the exons in chromosomal
         # (or entry) coordinates
         my $exons;

         # create a gene mapper and set it to map from chromosomal to cds coordinates
         my $gene = Bio::Coordinate::GeneMapper->new(-in   =>'chr',
                                                     -out  =>'cds',
                                                     -cds  =>$cds,
                                                     -exons=>$exons
                                                    );

         # get a a Bio::Location or sequence feature in input (chr) coordinates
         my $loc;

         # map the location into output coordinates and get a new location object
         $newloc = $gene->map($loc);

DESCRIPTION

       Bio::Coordinate::GeneMapper is a module for simplifying the mappings of coodinate
       locations between various gene related locations in human genetics. It also adds a special
       human genetics twist to coordinate systems by making it possible to disable the use of
       zero (0). Locations before position one start from -1. See method nozero.

       It understands by name the following coordinate systems and mapping between them:

                                 peptide (peptide length)
                                    ^
                                    | -peptide_offset
                                    |
                           frame  propeptide (propeptide length)
                               ^    ^
                                \   |
                    translate    \  |
                                  \ |
                                   cds  (transcript start and end)
                                    ^
             negative_intron        | \
                     ^              |  \  transcribe
                      \             |   \
                     intron        exon  \
                      ^   ^         ^     /
             splice    \   \      / |    /
                        \   \    /  |   /
                         \   inex   |  /
                          \    ^    | /
                           \    \   |/
                            ----- gene (gene_length)
                                    ^
                                    | - gene_offset
                                    |
                                   chr (or entry)

       This structure is kept in the global variable $DAG which is a representation of a Directed
       Acyclic Graph. The path calculations traversing this graph are done in a helper class. See
       Bio::Coordinate::Graph.

       Of these, two operations are special cases, translate and splice.  Translating and reverse
       translating are implemented as internal methods that do the simple 1<->3 conversion.
       Splicing needs additional information that is provided by method exons which takes in an
       array of Bio::LocationI objects.

       Most of the coordinate system names should be selfexplanatory to anyone familiar with
       genes. Negative intron coordinate system is starts counting backwards from -1 as the last
       nucleotide in the intron. This used when only exon and a few flanking intron nucleotides
       are known.

       This class models coordinates within one transcript of a gene, so to tackle multiple
       transcripts you need several instances of the class. It is therefore valid to argue that
       the name of the class should be TranscriptMapper. GeneMapper is a catchier name, so it
       stuck.

ATTRIBUTES

   nozero
        Title   : nozero
        Usage   : $obj->nozero(1);
        Function: Flag to disable the use of zero in the input,
                  output or both coordinate systems. Use of coordinate
                  systems without zero is a peculiarity  common in
                  human genetics community.
        Example :
        Returns : 0 (default), or 'in', 'out', 'in&out'
        Args    : 0 (default), or 'in', 'out', 'in&out'

METHODS

   new
   in
        Title   : in
        Usage   : $obj->in('peptide');
        Function: Set and read the input coordinate system.
        Example :
        Returns : value of input system
        Args    : new value (optional)

   out
        Title   : out
        Usage   : $obj->out('peptide');
        Function: Set and read the output coordinate system.
        Example :
        Returns : value of output system
        Args    : new value (optional)

   strict
        Title   : strict
        Usage   : $obj->strict('peptide');
        Function: Set and read whether strict boundaried of coordinate
                  systems are enforced.
                  When strict is on, the end of the coordinate range must be defined.
        Example :
        Returns : boolean
        Args    : boolean (optional)

   graph
        Title   : graph
        Usage   : $obj->graph($new_graph);
        Function: Set and read the graph object representing relationships
                  between coordinate systems
        Example :
        Returns : Bio::Coordinate::Graph object
        Args    : new Bio::Coordinate::Graph object (optional)

   peptide
        Title   : peptide
        Usage   : $obj->peptide_offset($peptide_coord);
        Function: Read and write the offset of peptide from the start of propeptide
                  and peptide length
        Returns : a Bio::Location::Simple object
        Args    : a Bio::LocationI object

   peptide_offset
        Title   : peptide_offset
        Usage   : $obj->peptide_offset(20);
        Function: Set and read the offset of peptide from the start of propeptide
        Returns : set value or 0
        Args    : new value (optional)

   peptide_length
        Title   : peptide_length
        Usage   : $obj->peptide_length(20);
        Function: Set and read the offset of peptide from the start of propeptide
        Returns : set value or 0
        Args    : new value (optional)

   exons
        Title   : exons
        Usage   : $obj->exons(@exons);
        Function: Set and read the offset of CDS from the start of transcript
                  You do not have to sort the exons before calling this method as
                  they will be sorted automatically.
                  If you have not defined the CDS, is will be set to span all
                  exons here.
        Returns : array of Bio::LocationI exons in genome coordinates or 0
        Args    : array of Bio::LocationI exons in genome (or entry) coordinates

   cds
        Title   : cds
        Usage   : $obj->cds(20);
        Function: Set and read the offset of CDS from the start of transcipt

                  Simple input can be an integer which gives the start of the
                  coding region in genomic coordinate. If you want to provide
                  the end of the coding region or indicate the use of the
                  opposite strand, you have to pass a Bio::RangeI
                  (e.g. Bio::Location::Simple or Bio::SegFeature::Generic)
                  object to this method.

        Returns : set value or 0
        Args    : new value (optional)

   map
        Title   : map
        Usage   : $newpos = $obj->map(5);
        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 coordiante system
        Args    : a Bio::Location::Simple

   direction
        Title   : direction
        Usage   : $obj->direction('peptide');
        Function: Read-only method for the direction of mapping deduced from
                  predefined input and output coordinate names.
        Example :
        Returns : 1 or -1, mapping direction
        Args    : new value (optional)

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

   to_string
        Title   : to_string
        Usage   : $newpos = $obj->to_string(5);
        Function: Dump the internal mapper values into a human readable format
        Example :
        Returns : string
        Args    :

INTERNAL METHODS

   _clone_loc
        Title   : _clone_loc
        Usage   : $copy_of_loc = $obj->_clone_loc($loc);
        Function: Make a deep copy of a simple location
        Returns : a Bio::Location::Simple object
        Args    : a Bio::Location::Simple object to be cloned

   _mapper_code2string
   _mapper_string2code
   _create_pair
        Title   : _create_pair
        Usage   : $mapper = $obj->_create_pair('chr', 'gene', 0, 2555, 10000, -1);
        Function: Internal helper method to create a mapper between
                  two coordinate systems
        Returns : a Bio::Coordinate::Pair object
        Args    : string, input coordinate system name,
                  string, output coordinate system name,
                  boolean, strict mapping
                  positive integer, offset
                  positive integer, length
                  1 || -1 , strand

   _translate
        Title   : _translate
        Usage   : $newpos = $obj->_translate($loc);
        Function: Translate the location from the CDS coordinate system
                  to a new value in the propeptide coordinate system.
        Example :
        Returns : new location
        Args    : a Bio::Location::Simple or Bio::Location::SplitLocationI

   _frame
   _reverse_translate
        Title   : _reverse_translate
        Usage   : $newpos = $obj->_reverse_translate(5);
        Function: Reverse translate the location from the propeptide
                  coordinate system to a new value in the CSD.
                  Note that a single peptide location expands to cover
                  the codon triplet
        Example :
        Returns : new location in the CDS coordinate system
        Args    : a Bio::Location::Simple or Bio::Location::SplitLocationI

   _check_direction
        Title   : _check_direction
        Usage   : $obj->_check_direction();
        Function: Check and swap when needed the direction the location
                  mapping Pairs based on input and output values
        Example :
        Returns : new location
        Args    : a Bio::Location::Simple

   _get_path
        Title   : _get_path
        Usage   : $obj->_get_path('peptide');
        Function: internal method for finding that shortest path between
                  input and output coordinate systems.
                  Calculations and caching are handled by the graph class.
                  See L<Bio::Coordinate::Graph>.
        Example :
        Returns : array of the mappers
        Args    : none

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/%%7Bdist%7D

AUTHOR

       Heikki Lehvaslaiho <heikki@bioperl.org>

COPYRIGHT

       This software is copyright (c) by Heikki Lehvaslaiho.

       This software is available under the same terms as the perl 5 programming language system
       itself.