taxa module

taxa module API:

• Taxon
• Taxa
• Hierarchy
• Hierarchies

Example usage:

# make a taxon
from pytaxa import constructors as cs
name = cs.taxon_name("Poa")
rank = cs.taxon_rank("genus", "ncbi")
db = cs.taxon_database("ncbi",
    "http://www.ncbi.nlm.nih.gov/taxonomy",
    "NCBI Taxonomy Database",
    "*")
id = cs.taxon_id(12345, db)
tx = cs.taxon(name, rank, id, "L.")

# combine many taxon's into taxa
from pytaxa import Taxa
Taxa(tx)
bb = Taxa(tx, tx)

taxa API

class pytaxa.Taxon(name: Union[str, dict] = {}, rank: Union[str, dict] = {}, id: Union[str, dict] = {}, authority: str = '')

Taxon class

Create a taxon object

Parameters:

• name – A dict resulting from a call to taxon_name() with name and database keys, or a name as a str
• rank – A dict resulting from a call to taxon_rank() with name and database keys, or a name as a str
• id – A dict resulting from a call to taxon_id() with id and database keys, or an identifier as an int
• authority – An authority name as a str

Usage:

from pytaxa import constructors as cs
from pytaxa import Taxon
name = cs.taxon_name("Poa")
rank = cs.taxon_rank("genus", "ncbi")
db = cs.taxon_database("ncbi", 
    "http://www.ncbi.nlm.nih.gov/taxonomy",
    "NCBI Taxonomy Database", 
    "*")
id = cs.taxon_id(12345, db)
x = Taxon(name, rank, id, "L.")
x.is_empty()

# null taxon's
x = Taxon(None)
x
x.is_empty()
Taxon({})
Taxon(None, None, None)
Taxon(None, None, id)
Taxon(None, None, None, "L.")

class pytaxa.Taxa(*taxa)

Taxa class

Stores one or more taxon objects. Prints first 10 taxa for brevity sake.

Parameters:taxa – Any number of objects of type Taxon resulting from a call to Taxon()

Usage:

# make a taxon
from pytaxa import constructors as cs
name = cs.taxon_name("Poa")
rank = cs.taxon_rank("genus", "ncbi")
db = cs.taxon_database("ncbi", 
    "http://www.ncbi.nlm.nih.gov/taxonomy",
    "NCBI Taxonomy Database", 
    "*")
id = cs.taxon_id(12345, db)

from pytaxa import Taxon
tx = Taxon(name, rank, id, "L.")

# combine many taxon's into taxa
from pytaxa import Taxa
Taxa(tx)
bb = Taxa(tx, tx)
bb

# handles empty taxon objects
Taxa(tx, Taxon(None), tx)

# various accessors: len
bb = Taxa(tx, tx)
len(bb)

class pytaxa.Hierarchy(*taxa)

Hierarchy class

Stores one or more taxon objects. Prints first 10 taxa for brevity sake.

We make a deep copy of the input to Hierarchy so that pop/pick/etc operations don’t change the inputs to Hierarchy. The deep copy is made at initialization, so if you don’t re-initialize changes made to the hierarchy by pop/pick/etc persist.

Parameters:taxa – Any number of objects of type Taxon resulting from a call to Taxon() Returns:object of class Hierarchy

see also Hierarchy functions

Usage:

from pytaxa import constructors as cs
from pytaxa import Taxon

# database to use for many taxon's
db = cs.taxon_database("ncbi", 
    "http://www.ncbi.nlm.nih.gov/taxonomy",
    "NCBI Taxonomy Database", 
    "*")

# make some taxon's
tx1 = Taxon(cs.taxon_name("Poaceae"), 
  cs.taxon_rank("family", "ncbi"), cs.taxon_id(4479, db))
tx2 = Taxon(cs.taxon_name("Poa"), 
  cs.taxon_rank("genus", "ncbi"), cs.taxon_id(12345, db))
tx3 = Taxon(cs.taxon_name("Poa annua"), 
  cs.taxon_rank("species", "ncbi"), cs.taxon_id(93036, db))

# single taxon
from pytaxa import Hierarchy
Hierarchy(tx1)

# many taxon's
z = Hierarchy(tx3, tx1, tx2)
z
z.taxa
z.ranklist

# various accessors
## length - i.e., number of taxa
z.xlen
len(z)

# empty Hierarchies
Hierarchy(Taxon({}))

# pop, pick, span
## example Hierarchy objects
from pytaxa import examples
examples.eg_hierarchy("poa")
examples.eg_hierarchy("puma")
examples.eg_hierarchy("salmo")

## pop
ex = examples.eg_hierarchy("salmo")
ex.pop(ranks = "family")
ex = examples.eg_hierarchy("salmo")
ex.pop(names = "Salmo")
ex = examples.eg_hierarchy("salmo")
ex.pop(ids = 331030)

## pick
ex = examples.eg_hierarchy("salmo")
ex
ex.pick(ranks = "family")
ex = examples.eg_hierarchy("salmo")
ex.pick(names = ["Salmo", "Chordata", "Teleostei"])
ex = examples.eg_hierarchy("salmo")
ex.pick(ids = 331030)

class pytaxa.Hierarchies(*hir)

Hierarchies class

Stores one or more Hierarchy objects. Prints first 10 Hierarchy’s for brevity.

We make a deep copy of the input to Hierarchies so that pop/pick/etc operations don’t change the inputs to Hierarchies. The deep copy is made at initialization, so if you don’t re-initialize changes made to the hierarchies by pop/pick/etc persist.

Parameters:hir – Any number of objects of type Hierarchy resulting from a call to Hierarchy() Returns:object of class Hierarchy

Usage:

## example Hierarchy objects
from pytaxa import examples
ex1 = examples.eg_hierarchy("poa")
ex2 = examples.eg_hierarchy("puma")
ex3 = examples.eg_hierarchy("salmo")

# make Hierarchies object
from pytaxa import Hierarchies
x = Hierarchies(ex1, ex2, ex3)
x

# use pop/pick/span across all Hierarchy's
from pytaxa import Hierarchies
x = Hierarchies(ex1, ex2, ex3)
x
x.pop(ranks = "family")
x.pop(ranks = "genus")
x.pick(ranks = ["genus", "species"])
x.pick(ranks = ["family", "species"])

Hierarchy functions

Hierarchy.all_empty()

Check if all taxa are empty

Returns:bool

Hierarchy.pop(ranks=[], names=[], ids=[])

Pop out certain taxa by ranks, names, or ids

Parameters:

• ranks – rank names as str
• names – taxonomic names as str
• ids – taxonomic identifiers as str or int

Returns:

self, object of class Hierarchy

Usage:

from pytaxa import examples
ex = examples.eg_hierarchy("salmo")
ex.pop(ranks = "family")

Hierarchy.pick(ranks=None, names=None, ids=None)

Pick certain taxa by ranks, names, or ids

Parameters:

• ranks – rank names as str
• names – taxonomic names as str
• ids – taxonomic identifiers as str or int

Returns:

self, object of class Hierarchy

Usage:

from pytaxa import examples
ex = examples.eg_hierarchy("salmo")
ex.pick(names = ["Salmo", "Chordata", "Teleostei"])