`dendropy.datamodel.taxonmodel`: Taxonomic Namespace Reference and Management¶

The `TaxonNamespace` Class¶

class dendropy.datamodel.taxonmodel.TaxonNamespace(*args, **kwargs)[source]¶

A collection of Taxon objects representing a self-contained and complete domain of distinct operational taxonomic unit definitions. Provides the common semantic context in which operational taxonomic units referenced by various phylogenetic data objects (e.g., trees or alignments) can be related.

Parameters:

*args (positional arguments, optional) – Accepts a single iterable as an optional positional argument. If a TaxonNamespace object is passed as the positional argument, then clones or deep-copies of its member Taxon objects will be added to this one. If any other iterable is passed as the positional argument, then each string in the iterable will result in a new Taxon object being constructed and added to the namespace with the string as its label (name), while each Taxon object in the iterable will be added to the namespace directly.
**kwargs (keyword arguments) –

labelstring
The label or name for this namespace.

is_mutableboolean, optional (default = True)
If True (default), then Taxon objects can be added to this namespace. If False, then adding Taxon objects will result in an error.

is_case_sensitiveboolean, optional (default = False)
Whether or not taxon names are considered case sensitive or insensitive.

Notes

An empty TaxonNamespace can be created (with optional) label and Taxon objects added later:

>>> tns = dendropy.TaxonNamespace(label="taxa")
>>> t1 = Taxon("a")
>>> tns.add_taxon(t1)
>>> t2 = Taxon("b")
>>> tns.add_taxon(t2)
>>> tns.add_taxon("c")
>>> tns
<TaxonNamespace 0x106509090 'taxa': [<Taxon 0x10661f050 'a'>, <Taxon 0x10651c590 'b'>, <Taxon 0x106642a90 'c'>]>

Alternatively, an iterable can be passed in as an initializer, and all Taxon objects will be added directly while, for each string, a new Taxon object will be created and added. So, the below are all equivalent to the above:

>>> tns = dendropy.TaxonNamespace(["a", "b", "c"], label="taxa")

>>> taxa = [Taxon(n) for n in ["a", "b", "c"]]
>>> tns = dendropy.taxonnamespace(taxa, label="taxa")

>>> t1 = Taxon("a")
>>> t2 = Taxon("b")
>>> taxa = [t1, t2, "c"]
>>> tns = dendropy.TaxonNamespace(taxa, label="taxa")

If a TaxonNamespace object is passed as the initializer argument, a shallow copy of the object is constructed:

>>> tns1 = dendropy.TaxonNamespace(["a", "b", "c"], label="taxa1")
>>> tns1
<TaxonNamespace 0x1097275d0 'taxa1': [<Taxon 0x109727610 'a'>, <Taxon 0x109727e10 'b'>, <Taxon 0x109727e90 'c'>]>
>>> tns2 = dendropy.TaxonNamespace(tns1, label="2")
>>> tns2
<TaxonNamespace 0x109727d50 'taxa1': [<Taxon 0x109727610 'a'>, <Taxon 0x109727e10 'b'>, <Taxon 0x109727e90 'c'>]>

Thus, while “tns1” and “tns2” are independent collections, and addition/deletion of Taxon instances to one will not effect the other, the label of a Taxon instance that is an element in one will of course effect the same instance if it is in the other:

>>> print(tns1[0].label)
>>> a
>>> print(tns2[0].label)
>>> a
>>> tns1[0].label = "Z"
>>> print(tns1[0].label)
>>> Z
>>> print(tns2[0].label)
>>> Z

In contrast to actual data (i.e., the Taxon objects), alll metadata associated with “tns2” (i.e., the AnnotationSet object, in the TaxonNamespace.annotations attribute), will be a full, independent deep-copy.

If what is needed is a true deep-copy of the data of a particular TaxonNamespace object, including copies of the member Taxon instances, then this can be achieved using copy.deepcopy.

>>> import copy
>>> tns1 = dendropy.TaxonNamespace(["a", "b", "c"], label="taxa1")
>>> tns2 = copy.deepcopy(tns1)

__contains__(taxon)[source]¶: Returns True if Taxon object taxon is in self.

__getitem__(key)[source]¶: Returns Taxon object with index or slice given by key.

__len__()[source]¶: Returns number of Taxon objects in this TaxonNamespace.

accession_index(taxon)[source]¶

Returns the accession index of taxon. Note that this may not be the same as the list index of the taxon if taxa have been deleted from the namespace.

Parameters:: taxon (Taxon) – Taxon object for which to return the accession index.
Returns:: h (integer) – The accession index.

add_taxa(taxa)[source]¶

Adds multiple Taxon objects to self.

Each Taxon object in taxa that is not already in the collection of Taxon objects in this namespace is added to it. If any of the Taxon objects are already in the collection, then nothing happens. If the namespace is immutable, then TypeError is raised when trying to add Taxon objects.

Parameters:: taxa (collections.Iterable [Taxon]) – A list of Taxon objects to be accessioned or registered in this collection.
Raises:: TypeError – If this namespace is immutable (i.e. TaxonNamespace.is_mutable is False).

add_taxon(taxon)[source]¶

Adds a new Taxon object to self.

If taxon is not already in the collection of Taxon objects in this namespace, and this namespace is mutable, it is added to the collection. If it is already in the collection, then nothing happens. If it is not already in the collection, but the namespace is not mutable, then TypeError is raised.

Parameters:: taxon (Taxon) – The Taxon object to be accessioned or registered in this collection.
Raises:: TypeError – If this namespace is immutable (i.e. TaxonNamespace.is_mutable is False).

all_taxa_bitmask()[source]¶

Returns mask of all taxa.

Returns:: h (integer) – Bitmask spanning all Taxon objects in self.

append(taxon)[source]¶: LEGACY. Use ‘add_taxon()’ instead.

bitmask_as_newick_string(bitmask, preserve_spaces=False, quote_underscores=True)[source]¶

Represents a split as a newick string.

Parameters:

bitmask (integer) – Split hash bitmask value.
preserve_spaces (boolean, optional) – If False (default), then spaces in taxon labels will be replaced by underscores. If True, then taxon labels with spaces will be wrapped in quotes.
quote_underscores (boolean, optional) – If True (default), then taxon labels with underscores will be wrapped in quotes. If False, then the labels will not be wrapped in quotes.

Returns:

s (string) – NEWICK representation of split specified by bitmask.

bitmask_taxa_list(bitmask, index=0)[source]¶

Returns list of Taxon objects represented by split bitmask.

Parameters:

bitmask (integer) – Split hash bitmask value.
index (integer, optional) – Start from this Taxon object instead of the first Taxon object in the collection.

Returns:

taxa (list [Taxon]) – List of Taxon objects specified or spanned by bitmask.

clear()[source]¶: Removes all Taxon objects from this namespace.

description(depth=1, indent=0, itemize='', output=None, **kwargs)[source]¶: Returns description of object, up to level depth.

discard_taxon_label(label, is_case_sensitive=None, first_match_only=False)[source]¶

Removes all Taxon objects with label matching label from the collection in this namespace.

Parameters:

label (string or string-like) – The value of the Taxon object label to remove.
is_case_sensitive (None or bool) – By default, label lookup will use the is_case_sensitive attribute of self to decide whether or not to respect case when trying to match labels to operational taxonomic unit names represented by Taxon instances. This can be over-ridden by specifying is_case_sensitive to True (forcing case-sensitivity) or False (forcing case-insensitivity).
first_match_only (bool) – If False, then the entire namespace will be searched and all Taxon objects with the matching labels will be remove. If True then only the first Taxon object with a matching label will be removed (i.e., the entire namespace is not searched). Setting this argument to True will be more efficient and should be preferred if there are no redundant or duplicate labels.

The `Taxon` Class¶

class dendropy.datamodel.taxonmodel.Taxon(label=None)[source]¶

A taxon associated with a sequence or a node on a tree.

Parameters:: label (string or Taxon object) – Label or name of this operational taxonomic unit concept. If a string, then the label attribute of self is set to this value. If a Taxon object, then the label attribute of self is set to the same value as the label attribute the other Taxon object and all annotations/metadata are copied.

__str__()[source]¶: String representation of self = taxon name.

description(depth=1, indent=0, itemize='', output=None, **kwargs)[source]¶: Returns description of object, up to level depth.

taxon_namespace_scoped_copy(memo=None)[source]¶: Cloning level: 1. Taxon-namespace-scoped copy: All member objects are full independent instances, except for TaxonNamespace and Taxon objects: these are preserved as references.

The `TaxonNamespaceAssociated` Class¶

class dendropy.datamodel.taxonmodel.TaxonNamespaceAssociated(taxon_namespace=None)[source]¶

Provides infrastructure for the maintenance of references to taxa.

migrate_taxon_namespace(taxon_namespace, unify_taxa_by_label=True, taxon_mapping_memo=None)[source]¶

Move this object and all members to a new operational taxonomic unit concept namespace scope.

Current self.taxon_namespace value will be replaced with value given in taxon_namespace if this is not None, or a new TaxonNamespace object. Following this, reconstruct_taxon_namespace() will be called: each distinct Taxon object associated with self or members of self that is not alread in taxon_namespace will be replaced with a new Taxon object that will be created with the same label and added to self.taxon_namespace. Calling this method results in the object (and all its member objects) being associated with a new, independent taxon namespace.

Label mapping case sensitivity follows the self.taxon_namespace.is_case_sensitive setting. If False and unify_taxa_by_label is also True, then the establishment of correspondence between Taxon objects in the old and new namespaces with be based on case-insensitive matching of labels. E.g., if there are four Taxon objects with labels ‘Foo’, ‘Foo’, ‘FOO’, and ‘FoO’ in the old namespace, then all objects that reference these will reference a single new Taxon object in the new namespace (with a label some existing casing variant of ‘foo’). If True: if unify_taxa_by_label is True, Taxon objects with labels identical except in case will be considered distinct.

Parameters:

taxon_namespace (TaxonNamespace) – The TaxonNamespace into the scope of which this object will be moved.
unify_taxa_by_label (boolean, optional) – If True, then references to distinct Taxon objects with identical labels in the current namespace will be replaced with a reference to a single Taxon object in the new namespace. If False: references to distinct Taxon objects will remain distinct, even if the labels are the same.
taxon_mapping_memo (dictionary) – Similar to memo of deepcopy, this is a dictionary that maps Taxon objects in the old namespace to corresponding Taxon objects in the new namespace. Mostly for interal use when migrating complex data to a new namespace. Note that any mappings here take precedence over all other options: if a Taxon object in the old namespace is found in this dictionary, the counterpart in the new namespace will be whatever value is mapped, regardless of, e.g. label values.

Examples

Use this method to move an object from one taxon namespace to another.

For example, to get a copy of an object associated with another taxon namespace and associate it with a different namespace:

# Get handle to the new TaxonNamespace
other_taxon_namespace = some_other_data.taxon_namespace

# Get a taxon-namespace scoped copy of a tree
# in another namespace
t2 = Tree(t1)

# Replace taxon namespace of copy
t2.migrate_taxon_namespace(other_taxon_namespace)

You can also use this method to get a copy of a structure and then move it to a new namespace:

t2 = Tree(t1) t2.migrate_taxon_namespace(TaxonNamespace())

# Note: the same effect can be achived by: t3 = copy.deepcopy(t1)

`dendropy.datamodel.taxonmodel`: Taxonomic Namespace Reference and Management¶

The `TaxonNamespace` Class¶

The `Taxon` Class¶

The `TaxonNamespaceAssociated` Class¶

Table of Contents

Previous topic

Next topic

Documentation

Obtaining

Discussion

Announcements

Development

dendropy.datamodel.taxonmodel: Taxonomic Namespace Reference and Management¶

The TaxonNamespace Class¶

The Taxon Class¶

The TaxonNamespaceAssociated Class¶

`dendropy.datamodel.taxonmodel`: Taxonomic Namespace Reference and Management¶

The `TaxonNamespace` Class¶

The `Taxon` Class¶

The `TaxonNamespaceAssociated` Class¶