Bio::C...eMapper(3pm)

💖 Bio::C...eMapper(3pm) 💖

okay so bestie, this page comes from the User Contributed Perl Documentation, and its name is Bio::C...eMapper(3pm). Pull up a chair, grab a strawberry 🍓, we're doing gene coordinate systems today and it's gonna be a whole thing.

---

✨ 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 the module that makes mapping coordinate locations between all the various gene-related locations in human genetics so much less of a headache. It also gives coordinate systems a little human-genetics twist: you can straight up disable the use of zero (0). Locations that come before position one start from -1. See method nozero. 💀

It knows the following coordinate systems by name, and it knows how to map 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 lives in the global variable $DAG, which is a representation of a Directed Acyclic Graph. The path calculations that traverse 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 extra information, and that information comes from method exons, which takes in an array of Bio::LocationI objects.

Most of the coordinate system names should be self-explanatory to anyone who's familiar with genes. The negative intron coordinate system starts counting backwards from -1 as the last nucleotide in the intron. This gets used when only the exon and a few flanking intron nucleotides are known.

This class models coordinates within one transcript of a gene, so if you want to tackle multiple transcripts you need several instances of the class. So yeah, it is legit valid to argue that the class should really be called TranscriptMapper. But GeneMapper is catchier, so it stuck. periodt. 💅

---

🌸 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 the human genetics community.
• Example: (empty)
• Returns: 0 (default), or 'in', 'out', 'in&out'
• Args: 0 (default), or 'in', 'out', 'in&out'

---

🫶 METHODS 🫶

💜 new

(no extra fields here, it's just new, iconic and minimal)

💜 in

• Title: in
• Usage: $obj->in('peptide');
• Function: Set and read the input coordinate system.
• Example: (empty)
• 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: (empty)
• Returns: value of output system
• Args: new value (optional)

💜 strict

• Title: strict
• Usage: $obj->strict('peptide');
• Function: Set and read whether strict boundaries of coordinate systems are enforced. When strict is on, the end of the coordinate range must be defined.
• Example: (empty)
• 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: (empty)
• 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: (empty)
• 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: (empty)
• 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: (empty)
• Returns: 1
• Args: (none)

💜 to_string

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

---

🔥 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

(no extra fields in the original, it just vibes there)

🦋 _mapper_string2code

(same deal, no extra fields)

🦋 _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: (empty)
• Returns: new location
• Args: a Bio::Location::Simple or Bio::Location::SplitLocationI

🦋 _frame

(no extra fields in the original)

🦋 _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: (empty)
• 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: (empty)
• 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 Bio::Coordinate::Graph.
• Example: (empty)
• Returns: array of the mappers
• Args: none

💌 FEEDBACK 💌

okay bestie, this module literally grows because of y'all 🫶 user feedback is an integral part of the evolution of this and other Bioperl modules — like, the whole thing levels up when people speak up. so pls send your comments and suggestions, preferably to the Bioperl mailing list. your participation is much appreciated, no cap 💖

  bioperl-l@bioperl.org                  - General discussion
  http://bioperl.org/wiki/Mailing_lists  - About the mailing lists

📬 Support

hii so if you need help, direct usage questions and support issues to the mailing list:

bioperl-l@bioperl.org

...rather than to the module maintainer directly 🙈 like, not to be shady, it's just that so many experienced and responsive experts will be able to look at the problem and quickly address it. slay teamwork. and pls pls pls include a thorough description of the problem with code and data examples if at all possible — that's the difference between "bestie I got u" and "bestie I'm guessing" 😭

🐛 Reporting bugs

report bugs to the Bioperl bug tracking system so we can 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. iconic behavior honestly 💅

---

and that's the whole page, bestie!! this one's from perl v5.32.0, dated 2020-11-24, and it lives under the name Bio::C...eMapper(3pm) 🌸 go forth and map those things, u absolute legend 👑✨