Bio::Taxon(3pm)

📦
version 1.7.8 · 3 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

Bio::Taxon(3pm) — a node in a represented taxonomy 💖

okay bestie, welcome to Bio::Taxon(3pm), straight out of the User Contributed Perl Documentation corner of the Bioperl universe. This is the module that lets you be a whole node in a taxonomy — not just a lil species leaf, but every ancestor along the way. iconic behaviour honestly. 🌸

✨ NAME ✨

Bio::Taxon — A node in a represented taxonomy. it's giving family tree but make it science 🧬🦋

✨ SYNOPSIS ✨

okay so here's the whole vibe, code and all, untouched, no cap:

use Bio::Taxon;

# Typically you will get a Taxon from a Bio::DB::Taxonomy object
# but here is how you initialize one
my $taxon = Bio::Taxon->new(-name      => $name,
                            -id        => $id,
                            -rank      => $rank,
                            -division  => $div);

# Get one from a database
my $dbh = Bio::DB::Taxonomy->new(-source   => 'flatfile',
                                 -directory=> '/tmp',
                                 -nodesfile=> '/path/to/nodes.dmp',
                                 -namesfile=> '/path/to/names.dmp');
my $human = $dbh->get_taxon(-name => 'Homo sapiens');
$human = $dbh->get_taxon(-taxonid => '9606');

print "id is ", $human->id, "\n"; # 9606
print "rank is ", $human->rank, "\n"; # species
print "scientific name is ", $human->scientific_name, "\n"; # Homo sapiens
print "division is ", $human->division, "\n"; # Primates

my $mouse = $dbh->get_taxon(-name => 'Mus musculus');

# You can quickly make your own lineages with the list database
my @ranks = qw(superkingdom class genus species);
my @h_lineage = ('Eukaryota', 'Mammalia', 'Homo', 'Homo sapiens');
my $list_dbh = Bio::DB::Taxonomy->new(-source => 'list', -names => \@h_lineage,
                                                          -ranks => \@ranks);
$human = $list_dbh->get_taxon(-name => 'Homo sapiens');
my @names = $human->common_names; # @names is empty
$human->common_names('woman');
@names = $human->common_names; # @names contains woman

# You can switch to another database when you need more information
my $entrez_dbh = Bio::DB::Taxonomy->new(-source => 'entrez');
$human->db_handle($entrez_dbh);
@names = $human->common_names; # @names contains woman, human, man

# Since Bio::Taxon implements Bio::Tree::NodeI, we have access to those
# methods (and can manually create our own taxa and taxonomy without the use
# of any database)
my $homo = $human->ancestor;

# Though be careful with each_Descendent - unless you add_Descendent()
# yourself, you won't get an answer because unlike for ancestor(), Bio::Taxon
# does not ask the database for the answer. You can ask the database yourself
# using the same method:
($human) = $homo->db_handle->each_Descendent($homo);

# We can also take advantage of Bio::Tree::Tree* methods:
# a) some methods are available with just an empty tree object
use Bio::Tree::Tree;
my $tree_functions = Bio::Tree::Tree->new();
my @lineage = $tree_functions->get_lineage_nodes($human);
my $lineage = $tree_functions->get_lineage_string($human);
my $lca = $tree_functions->get_lca($human, $mouse);

# b) for other methods, create a tree using your Taxon object
my $tree = Bio::Tree::Tree->new(-node => $human);
my @taxa = $tree->get_nodes;
$homo = $tree->find_node(-rank => 'genus');

# Normally you can't get the lca of a list-database derived Taxon and an
# entrez or flatfile-derived one because the two different databases might
# have different roots and different numbers of ranks between the root and the
# taxa of interest. To solve this, make a tree of the Taxon with the more
# detailed lineage and splice out all the taxa that won't be in the lineage of
# your other Taxon:
my $entrez_mouse = $entrez_dbh->get_taxon(-name => 'Mus musculus');
my $list_human = $list_dbh->get_taxon(-name => 'Homo sapiens');
my $mouse_tree = Bio::Tree::Tree->new(-node => $entrez_mouse);
$mouse_tree->splice(-keep_rank => \@ranks);
$lca = $mouse_tree->get_lca($entrez_mouse, $list_human);

✨ DESCRIPTION ✨

so this is the next generation (for Bioperl, bestie, don't get it twisted) of representing Taxonomy information. 💅

back in the day, all the info was managed by one single object called Bio::Species. this new implementation lets you represent the intermediate nodes, not just the species nodes, and it can relate their connections. glow up fr fr. 🦋

✨ FEEDBACK ✨

Mailing Lists

user feedback is literally 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. there are so many experienced and reponsive experts who'll 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 so we can keep track of the bugs and their resolution. bug reports can be submitted via the web:

https://github.com/bioperl/bioperl-live/issues

✨ AUTHOR - Sendu Bala ✨

Email bix@sendu.me.uk 📧

✨ CONTRIBUTORS ✨

  • Jason Stajich, jason-at-bioperl-dot-org (original Bio::Taxonomy::Node) 👑
  • Juguang Xiao, juguang@tll.org.sg
  • Gabriel Valiente, valiente@lsi.upc.edu

✨ APPENDIX ✨

the rest of the documentation details each of the object methods. internal methods are usually preceded with a _ (iykyk, that underscore means stay out unless you know what you're doing 👀).

new

Title   : new
Usage   : my $obj = Bio::Taxonomy::Node->new();
Function: Builds a new Bio::Taxonomy::Node object
Returns : an instance of Bio::Taxonomy::Node
Args    : -dbh               => a reference to a Bio::DB::Taxonomy object
                                [no default]
          -name              => a string representing the taxon name
                                (scientific name)
          -id                => human readable id - typically NCBI taxid
          -ncbi_taxid        => same as -id, but explicitly say that it is an
                                NCBI taxid
          -rank              => node rank (one of 'species', 'genus', etc)
          -common_names      => array ref of all common names
          -division          => 'Primates', 'Rodents', etc
          -genetic_code      => genetic code table number
          -mito_genetic_code => mitochondrial genetic code table number
          -create_date       => date created in database
          -update_date       => date last updated in database
          -pub_date          => date published in database

same thing but in bullet form so your eyes don't cry:

  • -dbh — a reference to a Bio::DB::Taxonomy object. there is no default, so like, you gotta bring your own.
  • -name — a string representing the taxon name (the scientific name).
  • -id — human readable id, typically an NCBI taxid.
  • -ncbi_taxid — same as -id, but you're explicitly saying it's an NCBI taxid.
  • -rank — node rank (one of 'species', 'genus', etc).
  • -common_names — array ref of all common names.
  • -division — 'Primates', 'Rodents', etc.
  • -genetic_code — genetic code table number.
  • -mito_genetic_code — mitochondrial genetic code table number.
  • -create_date — date created in database.
  • -update_date — date last updated in database.
  • -pub_date — date published in database.

✨ Bio::IdentifiableI interface ✨

Also see Bio::IdentifiableI 👀 (go read that one too bestie, it's the whole identity vibe)

version

Title   : version
Usage   : $taxon->version($newval)
Returns : value of version (a scalar)
Args    : on set, new value (a scalar or undef, optional)

authority

Title   : authority
Usage   : $taxon->authority($newval)
Returns : value of authority (a scalar)
Args    : on set, new value (a scalar or undef, optional)

namespace

Title   : namespace
Usage   : $taxon->namespace($newval)
Returns : value of namespace (a scalar)
Args    : on set, new value (a scalar or undef, optional)

okay that's the first half, and there's more coming — so don't go anywhere, we're not done yet 💖✨

🧬 Bio::Taxonomy::Node implementation 🧬

okay so this is the part where we get into the actual methods, bestie. every single one. no skipping, no "you get the vibe". let's go 💅

db_handle

  • Title: db_handle
  • Usage: $taxon->db_handle($newval)
  • Function: get/set the Bio::DB::Taxonomy handle
  • Returns: the value of db_handle (a scalar) — a Bio::DB::Taxonomy object
  • Args: on set, the new value (a scalar, optional) — a Bio::DB::Taxonomy object

Also see Bio::DB::Taxonomy 💖

rank

  • Title: rank
  • Usage: $taxon->rank($newval)
  • Function: get/set the rank of this Taxon — like 'species', 'genus', 'order', etc...
  • Returns: the value of rank (a scalar)
  • Args: on set, the new value (a scalar or undef, optional)

id

  • Title: id
  • Usage: $taxon->id($newval)
  • Function: get/set the id (the NCBI Taxonomy ID in most cases); object_id() and ncbi_taxid() are synonyms of this method
  • Returns: the id (a scalar)
  • Args: nothing to get, OR a scalar to set

ncbi_taxid

  • Title: ncbi_taxid
  • Usage: $taxon->ncbi_taxid($newval)
  • Function: get/set the NCBI Taxonomy ID. lowkey sneaky: this actually sets the id(), but it only hands you back an id when ncbi_taxid has been explicitly set with this method
  • Returns: the id (a scalar)
  • Args: nothing to get, OR a scalar to set

parent_id

  • Title: parent_id
  • Usage: $taxon->parent_id()
  • Function: get the parent ID (NCBI Taxonomy ID in most cases); parent_taxon_id() is a synonym of this method
  • Returns: the value of parent_id (a scalar)
  • Args: none

trusted_parent_id

  • Title: trusted_parent_id
  • Usage: $taxon->trusted_parent_id()
  • Function: if the parent_id is explicitly set, trust it
  • Returns: a simple boolean value (whether or not it has been set)
  • Args: none
  • Notes: okay so back in the day, parent_id was supposed to get deprecated in favor of using ancestor(). but bestie, that throws away one key optimization point — namely when an implementation has direct access to the taxon's parent ID while it's retrieving the info for the taxon ID. so this method exists so implementations can choose to (1) check whether the parent_id is set and (2) trust that the implementation (whether it's self or another implementation) set the parent_id correctly 🫶

genetic_code

  • Title: genetic_code
  • Usage: $taxon->genetic_code($newval)
  • Function: get/set the genetic code table
  • Returns: the value of genetic_code (a scalar)
  • Args: on set, the new value (a scalar or undef, optional)

mitochondrial_genetic_code

  • Title: mitochondrial_genetic_code
  • Usage: $taxon->mitochondrial_genetic_code($newval)
  • Function: get/set the mitochondrial genetic code table
  • Returns: the value of mitochondrial_genetic_code (a scalar)
  • Args: on set, the new value (a scalar or undef, optional)

create_date

  • Title: create_date
  • Usage: $taxon->create_date($newval)
  • Function: get/set the date this node was created (in the database)
  • Returns: the value of create_date (a scalar)
  • Args: on set, the new value (a scalar or undef, optional)

update_date

  • Title: update_date
  • Usage: $taxon->update_date($newval)
  • Function: get/set the date this node was updated (in the database)
  • Returns: the value of update_date (a scalar)
  • Args: on set, the new value (a scalar or undef, optional)

pub_date

  • Title: pub_date
  • Usage: $taxon->pub_date($newval)
  • Function: get/set the date this node was published (in the database)
  • Returns: the value of pub_date (a scalar)
  • Args: on set, the new value (a scalar or undef, optional)

ancestor

  • Title: ancestor
  • Usage: my $ancestor_taxon = $taxon->ancestor()
  • Function: retrieve the ancestor taxon. normally the database is asked what the ancestor is.

but listen — if you manually set the ancestor (or you make a Bio::Tree::Tree with this object as an argument to new()), the database (if any) will not be used for the purposes of this method.

to restore normal database behaviour, call ancestor(undef) (which would remove this object from the tree), or request this taxon again as a new Taxon object from the database.

  • Returns: Bio::Taxon
  • Args: none

get_Parent_Node

  • Title: get_Parent_Node
  • Function: synonym of ancestor()
  • Status: deprecated
bestie it's deprecated, so like… it still exists, but it's giving "old money that's been phased out". use ancestor() ✨

each_Descendent

  • Title: each_Descendent
  • Usage: my @taxa = $taxon->each_Descendent();
  • Function: get all the descendents for this Taxon (but not their descendents — ie. not a recursive fetchall). get_Children_Nodes() is a synonym of this method.

heads up: this method never asks the database for the descendents. it will only return objects you've manually set with add_Descendent(), or where that was done for you by making a Bio::Tree::Tree with this object as an argument to new().

to get the database descendents use $taxon->db_handle->each_Descendent($taxon).

  • Returns: an array of Bio::Taxon objects
  • Args: optionally, when you've set your own descendents, the string "height", "creation", "alpha", "revalpha", or a coderef to be used to sort the order of children nodes

get_Children_Nodes

  • Title: get_Children_Nodes
  • Function: synonym of each_Descendent()
  • Status: deprecated
another deprecated icon 💀 still here, still works, but the main character is each_Descendent().

name

  • Title: name
  • Usage:
$taxon->name('scientific', 'Homo sapiens');
$taxon->name('common', 'human', 'man');
my @names = @{$taxon->name('common')};
  • Function: get/set the names. node_name(), scientific_name() and common_names() are shorthands to name('scientific'), name('scientific') and name('common') respectively.
  • Returns: names (an array reference)
  • Args:
    • Arg1 => the name_class. you can assign any text, but the words 'scientific' and 'common' have the special meaning of scientific name and common name, respectively. 'scientific' and 'division' are treated specially, allowing only the first value in the Arg2 list to be set.
    • Arg2 ... => list of names
not me noticing the original lists 'scientific' twice in that shorthand sentence… we are keeping it exactly as written, no cap, not touching it 💅

node_name

  • Title: node_name
  • Usage: $taxon->node_name($newval)
  • Function: get/set the name of this taxon (node), typically the scientific name of the taxon, eg. 'Primate' or 'Homo'; scientific_name() is a synonym of this method
  • Returns: the value of node_name (a scalar)
  • Args: on set, the new value (a scalar or undef, optional)

common_names

  • Title: common_names
  • Usage: $taxon->common_names($newval)
  • Function: get/add the other names of this taxon — typically the genbank common name and others, eg. 'Human' and 'man'. common_name() is a synonym of this method
  • Returns: an array of names in list context, one of those names in scalar context
  • Args: on add, a new list of names (scalars, optional)

division

  • Title: division
  • Usage: $taxon->division($newval)
  • Function: get/set the division this taxon belongs to, eg. 'Primates' or 'Bacteria'
  • Returns: the value of division (a scalar)
  • Args: on set, the new value (a scalar or undef, optional)

remove_Descendent

  • Title: remove_Descendent
  • Usage:
$node->remove_Descedent($node_foo);
  • Function: removes a specific node from being a Descendent of this node
  • Returns: nothing
  • Args: an array of Bio::Node::NodeI objects which have been previously passed to the add_Descendent call of this object
yes bestie, the usage line says remove_Descedent and we are preserving that spelling exactly, character for character, because that's what's in the page 🙈✨

and that's the whole page, fr fr 💖 it's Bio::Taxon(3pm) from perl v5.32.1, dated 2021-08-15. go classify something, you absolute taxonomy icon 👑🦋 periodt.

📦 where this page comes from