Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Bio::Taxon(3)	      User Contributed Perl Documentation	 Bio::Taxon(3)

       Bio::Taxon - A node in a	represented taxonomy

	 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
	 @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');
	 @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);

       This is the next	generation (for	Bioperl) of representing Taxonomy
       information. Previously all information was managed by a	single object
       called Bio::Species. This new implementation allows representation of
       the intermediate	nodes not just the species nodes and can relate	their

   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 list.  Your participation is much appreciated.			- General discussion	- About	the mailing lists

       Please direct usage questions or	support	issues to the mailing list:

       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 of
       the bugs	and their resolution. Bug reports can be submitted via the

AUTHOR - Sendu Bala

       Jason Stajich,	 jason-at-bioperl-dot-org (original
       Bio::Taxonomy::Node) Juguang Xiao, Gabriel

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

	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

Bio::IdentifiableI interface
       Also see	Bio::IdentifiableI

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

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

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

Bio::Taxonomy::Node implementation
	Title	: db_handle
	Usage	: $taxon->db_handle($newval)
	Function: Get/Set Bio::DB::Taxonomy Handle
	Returns	: value	of db_handle (a	scalar)	(Bio::DB::Taxonomy object)
	Args	: on set, new value (a scalar, optional) Bio::DB::Taxonomy object

       Also see	Bio::DB::Taxonomy

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

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

	Title	: ncbi_taxid
	Usage	: $taxon->ncbi_taxid($newval)
	Function: Get/Set the NCBI Taxonomy ID;	This actually sets the id() but	only
		  returns an id	when ncbi_taxid	has been explictely set	with this
	Returns	: id (a	scalar)
	Args	: none to get, OR scalar to set

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

	Title	: trusted_parent_id
	Usage	: $taxon->trusted_parent_id()
	Function: If the parent_id is explicitly set, trust it
	Returns	: simple boolean value (whether	or not it has been set)
	Args	: none
	Notes	: Previously, the parent_id method was to be deprecated	in favor of
		  using	ancestor(). However this removes one key optimization point,
		  namely when an implementation	has direct access to the taxon's
		  parent ID when retrieving the	information for	the taxon ID.  This
		  method is in place so	implementations	can choose to (1) check	whether
		  the parent_id	is set and (2) trust that the implementation (whether
		  it is	self or	another	implementation)	set the	parent_id correctly.

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

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

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

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

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

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

		  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

	Title	: get_Parent_Node
	Function: Synonym of ancestor()
	Status	: deprecated

	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.

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

		  To get the database descendents use

	Returns	: Array	of Bio::Taxon objects
	Args	: optionally, when you have set	your own descendents, the string
		  "height", "creation",	"alpha", "revalpha", or	coderef	to be used to
		  sort the order of children nodes.

	Title	: get_Children_Nodes
	Function: Synonym of each_Descendent()
	Status	: deprecated

	 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 (a array reference)
	 Args:	   Arg1	=> the name_class. You can assign any text, but	the words
		       'scientific' and	'common' have the special meaning, as
		       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

	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	: value	of node_name (a	scalar)
	Args	: on set, new value (a scalar or undef,	optional)

	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	: array	of names in list context, one of those names in	scalar context
	Args	: on add, new list of names (scalars, optional)

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

	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.

perl v5.32.0			  2019-12-07			 Bio::Taxon(3)

NAME | SYNOPSIS | DESCRIPTION | FEEDBACK | AUTHOR - Sendu Bala | CONTRIBUTORS | APPENDIX | Bio::IdentifiableI interface | Bio::Taxonomy::Node implementation

Want to link to this manual page? Use this URL:

home | help