.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Bio::Coordinate::GeneMapper 3pm"
.TH Bio::Coordinate::GeneMapper 3pm "2014-07-13" "perl v5.18.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  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   =>\*(Aqchr\*(Aq,
\&                                              \-out  =>\*(Aqcds\*(Aq,
\&                                              \-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);
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
It understands by name the following coordinate systems and mapping
between them:
.PP
.Vb 10
\&                          peptide (peptide length)
\&                             ^
\&                             | \-peptide_offset
\&                             |
\&                    frame  propeptide (propeptide length)
\&                        ^    ^
\&                         \e   |
\&             translate    \e  |
\&                           \e |
\&                            cds  (transcript start and end)
\&                             ^
\&      negative_intron        | \e
\&              ^              |  \e  transcribe
\&               \e             |   \e
\&              intron        exon  \e
\&               ^   ^         ^     /
\&      splice    \e   \e      / |    /
\&                 \e   \e    /  |   /
\&                  \e   inex   |  /
\&                   \e    ^    | /
\&                    \e    \e   |/
\&                     \-\-\-\-\- gene (gene_length)
\&                             ^
\&                             | \- gene_offset
\&                             |
\&                            chr (or entry)
.Ve
.PP
This structure is kept in the global variable \f(CW$DAG\fR 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.
.PP
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.
.PP
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.
.PP
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.
.SS "new"
.IX Subsection "new"
.SS "in"
.IX Subsection "in"
.Vb 6
\& Title   : in
\& Usage   : $obj\->in(\*(Aqpeptide\*(Aq);
\& Function: Set and read the input coordinate system.
\& Example :
\& Returns : value of input system
\& Args    : new value (optional)
.Ve
.SS "out"
.IX Subsection "out"
.Vb 6
\& Title   : out
\& Usage   : $obj\->out(\*(Aqpeptide\*(Aq);
\& Function: Set and read the output coordinate system.
\& Example :
\& Returns : value of output system
\& Args    : new value (optional)
.Ve
.SS "strict"
.IX Subsection "strict"
.Vb 8
\& Title   : strict
\& Usage   : $obj\->strict(\*(Aqpeptide\*(Aq);
\& 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)
.Ve
.SS "nozero"
.IX Subsection "nozero"
.Vb 9
\& 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 \*(Aqin\*(Aq, \*(Aqout\*(Aq, \*(Aqin&out\*(Aq
\& Args    : 0 (default), or \*(Aqin\*(Aq, \*(Aqout\*(Aq, \*(Aqin&out\*(Aq
.Ve
.SS "graph"
.IX Subsection "graph"
.Vb 7
\& 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)
.Ve
.SS "peptide"
.IX Subsection "peptide"
.Vb 6
\& 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
.Ve
.SS "peptide_offset"
.IX Subsection "peptide_offset"
.Vb 5
\& 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)
.Ve
.SS "peptide_length"
.IX Subsection "peptide_length"
.Vb 5
\& 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)
.Ve
.SS "exons"
.IX Subsection "exons"
.Vb 9
\& 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
.Ve
.SS "_clone_loc"
.IX Subsection "_clone_loc"
.Vb 5
\& 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
.Ve
.SS "cds"
.IX Subsection "cds"
.Vb 3
\& 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)
.Ve
.SS "map"
.IX Subsection "map"
.Vb 7
\& 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
.Ve
.SS "direction"
.IX Subsection "direction"
.Vb 7
\& Title   : direction
\& Usage   : $obj\->direction(\*(Aqpeptide\*(Aq);
\& 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)
.Ve
.SS "swap"
.IX Subsection "swap"
.Vb 7
\& Title   : swap
\& Usage   : $obj\->swap;
\& Function: Swap the direction of transformation
\&           (input <\-> output)
\& Example :
\& Returns : 1
\& Args    :
.Ve
.SS "to_string"
.IX Subsection "to_string"
.Vb 6
\& Title   : to_string
\& Usage   : $newpos = $obj\->to_string(5);
\& Function: Dump the internal mapper values into a human readable format
\& Example :
\& Returns : string
\& Args    :
.Ve
.SS "_mapper_code2string"
.IX Subsection "_mapper_code2string"
.SS "_mapper_string2code"
.IX Subsection "_mapper_string2code"
.SS "_create_pair"
.IX Subsection "_create_pair"
.Vb 11
\& Title   : _create_pair
\& Usage   : $mapper = $obj\->_create_pair(\*(Aqchr\*(Aq, \*(Aqgene\*(Aq, 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
.Ve
.SS "_translate"
.IX Subsection "_translate"
.Vb 7
\& 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
.Ve
.SS "_frame"
.IX Subsection "_frame"
.SS "_reverse_translate"
.IX Subsection "_reverse_translate"
.Vb 9
\& 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
.Ve
.SS "_check_direction"
.IX Subsection "_check_direction"
.Vb 7
\& 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
.Ve
.SS "_get_path"
.IX Subsection "_get_path"
.Vb 9
\& Title   : _get_path
\& Usage   : $obj\->_get_path(\*(Aqpeptide\*(Aq);
\& 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
.Ve