Bio::Coordinate::GeneMapper.3pm

Langue: en

Version: 2010-05-19 (ubuntu - 24/10/10)

Section: 3 (Bibliothèques de fonctions)

NAME

Bio::Coordinate::GeneMapper - transformations between gene related coordinate systems

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.

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:
   http://bugzilla.open-bio.org/
 
 

AUTHOR - Heikki Lehvaslaiho

Email: heikki-at-bioperl-dot-org

APPENDIX

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

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)
 
 

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'
 
 

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
 
 

_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
 
 

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    :
 
 

_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
 
 

_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