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.
new¶
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 :
_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