dendropy.datamodel.basemodel: Core Infrastructure for Phylogenetic Data Objects

The DataObject Class

class dendropy.datamodel.basemodel.DataObject(label=None)

Base class for all phylogenetic data objects.

clone(depth=1)

Creates and returns a copy of self.

Parameters:

depth (integer) –

The depth of the copy:

• 0: shallow-copy: All member objects are references, except for :attr:annotation_set of top-level object and member Annotation objects: these are full, independent instances (though any complex objects in the value field of Annotation objects are also just references).

• 1: taxon-namespace-scoped copy: All member objects are full independent instances, except for TaxonNamespace and Taxon instances: these are references.

• 2: Exhaustive deep-copy: all objects are cloned.

taxon_namespace_scoped_copy(memo=None)

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 Annotable Class

class dendropy.datamodel.basemodel.Annotable

Mixin class which all classes that need to persist object attributes or other information as metadata should subclass.

__copy__(memo=None)

Cloning level: 0. :attr:annotation_set of top-level object and member Annotation objects are full, independent instances. All other member objects (include objects referenced by dynamically-bound attribute values of Annotation objects) are references. All member objects are references, except for

copy_annotations_from(other, attribute_object_mapper=None)

Copies annotations from other, which must be of Annotable type.

Copies are deep-copies, in that the Annotation objects added to the annotation_set AnnotationSet collection of self are independent copies of those in the annotate_set collection of other. However, dynamic bound-attribute annotations retain references to the original objects as given in other, which may or may not be desirable. This is handled by updated the objects to which attributes are bound via mappings found in attribute_object_mapper. In dynamic bound-attribute annotations, the _value attribute of the annotations object (Annotation._value) is a tuple consisting of “(obj, attr_name)”, which instructs the Annotation object to return “getattr(obj, attr_name)” (via: “getattr(*self._value)”) when returning the value of the Annotation. “obj” is typically the object to which the AnnotationSet belongs (i.e., self). When a copy of Annotation is created, the object reference given in the first element of the _value tuple of dynamic bound-attribute annotations are unchanged, unless the id of the object reference is fo

Parameters:

• other (Annotable) – Source of annotations to copy.

• attribute_object_mapper (dict) – Like the memo of __deepcopy__, maps object id’s to objects. The purpose of this is to update the parent or owner objects of dynamic attribute annotations. If a dynamic attribute Annotation gives object x as the parent or owner of the attribute (that is, the first element of the Annotation._value tuple is other) and id(x) is found in attribute_object_mapper, then in the copy the owner of the attribute is changed to attribute_object_mapper[id(x)]. If attribute_object_mapper is None (default), then the following mapping is automatically inserted: id(other): self. That is, any references to other in any Annotation object will be remapped to self. If really no reattribution mappings are desired, then an empty dictionary should be passed instead.

deep_copy_annotations_from(other, memo=None)

Note that all references to other in any annotation value (and sub-annotation, and sub-sub-sub-annotation, etc.) will be replaced with references to self. This may not always make sense (i.e., a reference to a particular entity may be absolute regardless of context).

The Annotation Class

class dendropy.datamodel.basemodel.Annotation(name, value, datatype_hint=None, name_prefix=None, namespace=None, name_is_prefixed=False, is_attribute=False, annotate_as_reference=False, is_hidden=False, label=None, real_value_format_specifier=None)

Metadata storage, composition and persistance, with the following attributes:

• name

• value

• datatype_hint

• name_prefix

• namespace

• annotate_as_reference

• is_hidden

• real_value_format_specifier - format specifier for printing or rendering values as string, given in Python’s format specification mini-language. E.g., ‘.8f’, ‘4E’, ‘>04d’.

clone(attribute_object_mapper=None)

Essentially a shallow-copy, except that any objects in the _value field with an id found in attribute_object_mapper will be replaced with attribute_object_mapper[id].

copy_annotations_from(other, attribute_object_mapper=None)

Copies annotations from other, which must be of Annotable type.

Copies are deep-copies, in that the Annotation objects added to the annotation_set AnnotationSet collection of self are independent copies of those in the annotate_set collection of other. However, dynamic bound-attribute annotations retain references to the original objects as given in other, which may or may not be desirable. This is handled by updated the objects to which attributes are bound via mappings found in attribute_object_mapper. In dynamic bound-attribute annotations, the _value attribute of the annotations object (Annotation._value) is a tuple consisting of “(obj, attr_name)”, which instructs the Annotation object to return “getattr(obj, attr_name)” (via: “getattr(*self._value)”) when returning the value of the Annotation. “obj” is typically the object to which the AnnotationSet belongs (i.e., self). When a copy of Annotation is created, the object reference given in the first element of the _value tuple of dynamic bound-attribute annotations are unchanged, unless the id of the object reference is fo

Parameters:

• other (Annotable) – Source of annotations to copy.

• attribute_object_mapper (dict) – Like the memo of __deepcopy__, maps object id’s to objects. The purpose of this is to update the parent or owner objects of dynamic attribute annotations. If a dynamic attribute Annotation gives object x as the parent or owner of the attribute (that is, the first element of the Annotation._value tuple is other) and id(x) is found in attribute_object_mapper, then in the copy the owner of the attribute is changed to attribute_object_mapper[id(x)]. If attribute_object_mapper is None (default), then the following mapping is automatically inserted: id(other): self. That is, any references to other in any Annotation object will be remapped to self. If really no reattribution mappings are desired, then an empty dictionary should be passed instead.

deep_copy_annotations_from(other, memo=None)

Note that all references to other in any annotation value (and sub-annotation, and sub-sub-sub-annotation, etc.) will be replaced with references to self. This may not always make sense (i.e., a reference to a particular entity may be absolute regardless of context).

The AnnotationSet Class

class dendropy.datamodel.basemodel.AnnotationSet(target, *args)

__add__(other)

Returns OrderedSet consisting of union of values in self and other.

__contains__(value)

Returns True if value is in self or False otherwise.

__delitem__(index)

Deletes value at index. Note takes index of than value as key.

__getitem__(name)

Experimental! Inefficient! Volatile! Subject to change!

__iter__()

Returns iterator over values in self.

__reversed__()

Returns OrderedSet with values in reversed order.

__setitem__(name, value)

Experimental! Inefficient! Volatile! Subject to change!

add(value)

Adds a new element, value, to self if value is not already in self.

add_bibtex(citation, store_as='bibtex', name_prefix=None, namespace=None, is_hidden=False)

Add a citation as an annotation.

Parameters:

• citation (string or dict or BibTexEntry) – The citation to be added. If a string, then it must be a BibTex-formatted entry. If a dictionary, then it must have BibTex fields as keys and contents as values.

• store_as (string, optional) – Specifies how to record the citation, with one of the following strings as values: “bibtex” (a set of annotations, where each BibTex field becomes a separate annotation); “prism” (a set of PRISM [Publishing Requirements for Industry Standard Metadata] annotations); “dublin” (A set of of Dublic Core annotations). Defaults to “bibtex”.

• name_prefix (string, optional) – Mainly for NeXML output (e.g. “dc:”).

• namespace (string, optional) – Mainly for NeXML output (e.g. “http://www.w3.org/XML/1998/namespace”).

• is_hidden (boolean, optional) – Do not write or print this annotation when writing data.

Returns:

annotation (|Annotation|) – The new Annotation created.

add_bound_attribute(attr_name, annotation_name=None, datatype_hint=None, name_prefix=None, namespace=None, name_is_prefixed=False, annotate_as_reference=False, is_hidden=False, real_value_format_specifier=None, owner_instance=None)

Add an attribute of an object as a dynamic annotation. The value of the annotation will be dynamically bound to the value of the attribute.

Parameters:

• attr_name (string) – The (string) name of the attribute to be used as the source of the content or value of the annotation.

• annotation_name (string, optional) – Use this string as the annotation field/name rather than the attribute name.

• datatype_hint (string, optional) – Mainly for NeXML output (e.g. “xsd:string”).

• namespace_prefix (string, optional) – Mainly for NeXML output (e.g. “dc:”).

• namespace (string, optional) – Mainly for NeXML output (e.g. “http://www.w3.org/XML/1998/namespace”).

• name_is_prefixed (string, optional) – Mainly for NeXML input: name will be split into prefix and local part before storage (e.g., “dc:citations” will result in prefix = “dc” and name=”citations”)

• annotate_as_reference (bool, optional) – The value should be interpreted as a URI that points to content.

• is_hidden (bool, optional) – Do not write or print this annotation when writing data.

• owner_instance (object, optional) – The object whose attribute is to be used as the value of the annotation. Defaults to self.target.

Returns:

annotation (|Annotation|) – The new Annotation created.

add_citation(citation, read_as='bibtex', store_as='bibtex', name_prefix=None, namespace=None, is_hidden=False)

Add a citation as an annotation.

Parameters:

• citation (string or dict or BibTexEntry) – The citation to be added. If a string, then it must be a BibTex-formatted entry. If a dictionary, then it must have BibTex fields as keys and contents as values.

• read_as (string, optional) – Specifies the format/schema/structure of the citation. Currently only supports ‘bibtex’.

• store_as (string, optional) – Specifies how to record the citation, with one of the following strings as values: “bibtex” (a set of annotations, where each BibTex field becomes a separate annotation); “prism” (a set of PRISM [Publishing Requirements for Industry Standard Metadata] annotations); “dublin” (A set of of Dublic Core annotations). Defaults to “bibtex”.

• name_prefix (string, optional) – Mainly for NeXML output (e.g. “dc:”).

• namespace (string, optional) – Mainly for NeXML output (e.g. “http://www.w3.org/XML/1998/namespace”).

• is_hidden (boolean, optional) – Do not write or print this annotation when writing data.

Returns:

annotation (|Annotation|) – The new Annotation created.

add_new(name, value, datatype_hint=None, name_prefix=None, namespace=None, name_is_prefixed=False, is_attribute=False, annotate_as_reference=False, is_hidden=False, real_value_format_specifier=None)

Add an annotation.

Parameters:

• name (string) – The property/subject/field of the annotation (e.g. “color”, “locality”, “dc:citation”)

• value (string) – The content of the annotation.

• datatype_hint (string, optional) – Mainly for NeXML output (e.g. “xsd:string”).

• namespace_prefix (string, optional) – Mainly for NeXML output (e.g. “dc:”).

• namespace (string, optional) – Mainly for NeXML output (e.g. “http://www.w3.org/XML/1998/namespace”).

• name_is_prefixed (string, optional) – Mainly for NeXML input: name will be split into prefix and local part before storage (e.g., “dc:citations” will result in prefix = “dc” and name=”citations”)

• is_attribute (boolean, optional) – If value is passed as a tuple of (object, “attribute_name”) and this is True, then actual content will be the result of calling getattr(object, "attribute_name").

• annotate_as_reference (boolean, optional) – The value should be interpreted as a URI that points to content.

• is_hidden (boolean, optional) – Do not write or print this annotation when writing data.

• real_value_format_specifier (str) – Format specifier for printing or rendering values as string, given in Python’s format specification mini-language. E.g., ‘.8f’, ‘4E’, ‘>04d’.

Returns:

annotation (|Annotation|) – The new Annotation created.

discard(key)

Deletes value of key from self. No error if no value of key is not in self.

drop(**kwargs)

Removes Annotation objects that match based on all criteria specified in keyword arguments.

Remove all annotation objects with name == “color”:

>>> tree.annotations.drop(name="color")

Remove all annotation objects with namespace == “http://pypi.org/project/DendroPy/”:

>>> tree.annotations.drop(namespace="http://pypi.org/project/DendroPy/")

Remove all annotation objects with namespace == “http://pypi.org/project/DendroPy/” and name == “color”:

>>> tree.annotations.drop(namespace="http://pypi.org/project/DendroPy/",
        name="color")

Remove all annotation objects with name_prefix == “dc”:

>>> tree.annotations.drop(name_prefix="dc")

Remove all annotation objects with prefixed_name == “dc:color”:

>>> tree.annotations.drop(prefixed_name="dc:color")

If no keyword argument filter criteria are given, all annotations are removed:

>>> tree.annotations.drop()

Returns:

results (|AnnotationSet|) – AnnotationSet containing Annotation objects that were removed.

find(**kwargs)

Returns the first Annotation associated with self.target which matches based on all criteria specified in keyword arguments:

>>> note = tree.annotations.find(name="color")
>>> note = tree.annotations.find(name_prefix="dc", name="color")
>>> note = tree.annotations.find(prefixed_name="dc:color")

If no match is found, None is returned.

If no keyword arguments are given, a TypeError is raised.

Returns:

results (|Annotation| or |None|) – First Annotation object found that matches criteria, or None if no matching annotations found.

findall(**kwargs)

Returns AnnotationSet of Annotation objects associated with self.target that match based on all criteria specified in keyword arguments:

>>> notes = tree.annotations.findall(name="color")
>>> notes = tree.annotations.findall(namespace="http://pypi.org/project/DendroPy/")
>>> notes = tree.annotations.findall(namespace="http://pypi.org/project/DendroPy/",
                              name="color")
>>> notes = tree.annotations.findall(name_prefix="dc")
>>> notes = tree.annotations.findall(prefixed_name="dc:color")

If no matches are found, the return AnnotationSet is empty.

If no keyword arguments are given, all annotations are returned:

>>> notes = tree.annotations.findall()

Returns:

results (|AnnotationSet| or |None|) – AnnotationSet containing Annotation objects that match criteria, or None if no matching annotations found.

get_value(name, default=None)

Returns the value of the first Annotation associated with self.target which has name in the name field.

If no match is found, then default is returned.

Parameters:

• name (string) – Name of Annotation object whose value is to be returned.

• default (any, optional) – Value to return if no matching Annotation object found.

Returns:

results (|Annotation| or |None|) – value of first Annotation object found that matches criteria, or None if no matching annotations found.

index(value)

Returns index of element with value of value.

next()

Returns iterator over values in self.

pop(last=True)

Removes and return value in self. By default, removes last value.

remove(key)

Deletes value of key from self. KeyErrorif no value of key is not in self.

require_value(name)

Returns the value of the first Annotation associated with self.target which has name in the name field.

If no match is found, then KeyError is raised.

Parameters:

name (string) – Name of Annotation object whose value is to be returned.

Returns:

results (|Annotation| or |None|) – value of first Annotation object found that matches criteria.

update(other)

Updates self with values in other for each value in other that is not already in self.

values_as_dict(**kwargs)

Returns annotation set as a dictionary. The keys and values for the dictionary will be generated based on the following keyword arguments:

Keyword Arguments:

• key_attr (string) – String specifying an Annotation object attribute name to be used as keys for the dictionary.

• key_fn (string) – Function that takes an Annotation object as an argument and returns the value to be used as a key for the dictionary.

• value_attr (string) – String specifying an Annotation object attribute name to be used as values for the dictionary.

• value_fn (string) – Function that takes an Annotation object as an argument and returns the value to be used as a value for the dictionary.

• neither (At most one of value_attr or value_fn can be specified. If) –

• Annotation.name. (is specified, then by default the keys are generated from) –

• neither –

• Annotation.value. (is specified, then by default the values are generated from) –

• being (Key collisions will result in the dictionary entry for that key) –

• overwritten. –

Returns:

values (dict)

Supporting Classes

class dendropy.utility.bibtex.BibTexEntry(citation=None)

Tracks a single BibTeX entry.

Sets up internal dictionary of BibTeX fields, and initializes if argument is given.

__delattr__(name)

Allows bibtex fields (and any additional ones) to be treated like object attributes.

__getattr__(name)

Allows bibtex fields (and any additional ones) to be treated like object attributes.

__repr__()

Internal representation of self.

__setattr__(name, value)

Allows bibtex fields (and any additional ones) to be treated like object attributes.

__str__()

String representation of self.

as_bibtex(wrap_width=78)

Composes entry in BibTex format.

as_compact_bibtex()

Composes entry in BibTex format.

property fields

Returns list of populated fields in order (does not include bibtype and citekey).

fields_as_dict()

Returns the fields (i.e., all public attributes except for bibtype and citekey as a dictionary).

parse_text(text)

Parses a BibTeX text entry.