dendropy.dataobject.base – Core Infrastructure for Phylogenetic Data Objects

The DataObject Class

class dendropy.dataobject.base.DataObject(label=None, oid=None)

Base class from which all classes that need to persist object attributes or other information as metadata.

default_oid

Returns default oid.

oid

Returns id.

The Annotation Class

class dendropy.dataobject.base.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, oid=None)

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

• name
• value
• datatype_hint
• name_prefix
• namespace
• annotate_as_reference
• is_hidden

The AnnotationSet Class

class dendropy.dataobject.base.AnnotationSet(target, *args)

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

Add a citation as an annotation.

citation

This can be a string representing a BibTex entry, a dictionary with BibTex fields as keys and contents as values, or a dendropy.utility.BibTex.BibTexEntry object.

store_as

Specifies how to record the citation:

“bibtex”

A set of annotations, where each BibTex field becomes a separate annotation.

“prism”

A set of of PRISM (Publishing Requirements for Industry Standard Metadata) annotations.

“dublin”

A set of of Dublic Core annotations.

Defaults to “bibtex”.

name_prefix

Mainly for NeXML output (e.g. “dc:”).

namespace

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

is_hidden

Do not write or print this annotation when writing data.

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, owner_instance=None)

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

attr_name

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

annotation_name

Use this string as the annotation field/name rather than the attribute name.

datatype_hint

Mainly for NeXML output (e.g. “xsd:string”).

namespace_prefix

Mainly for NeXML output (e.g. “dc:”).

namespace

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

name_is_prefixed

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

The value should be interpreted as a URI that points to content.

is_hidden

Do not write or print this annotation when writing data.

owner_instance

The object whose attribute is to be used as the value of the annotation. Defaults to self.target.

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

Add a citation as an annotation.

citation

This can be a string representing a BibTex entry, a dictionary with BibTex fields as keys and contents as values, or a dendropy.utility.BibTex.BibTexEntry object.

read_as

Specifies the format/schema/structure of the citation. Currently only supports ‘bibtex’.

store_as

Specifies how to record the citation, takes one of the following strings as values:

“bibtex”

A set of annotations, where each BibTex field becomes a separate annotation.

“prism”

A set of of PRISM (Publishing Requirements for Industry Standard Metadata) annotations.

“dublin”

A set of of Dublic Core annotations.

Defaults to “bibtex”.

name_prefix

Mainly for NeXML output (e.g. “dc:”).

namespace

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

is_hidden

Do not write or print this annotation when writing data.

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)

Add an annotation, where:

name

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

value

The content of the annotation.

datatype_hint

Mainly for NeXML output (e.g. “xsd:string”).

namespace_prefix

Mainly for NeXML output (e.g. “dc:”).

namespace

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

name_is_prefixed

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

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

The value should be interpreted as a URI that points to content.

is_hidden

Do not write or print this annotation when writing data.

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://packages.python.org/DendroPy/”:

>>> tree.annotations.drop(namespace="http://packages.python.org/DendroPy/")

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

>>> tree.annotations.drop(namespace="http://packages.python.org/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()

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.

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://packages.python.org/DendroPy/")
>>> notes = tree.annotations.findall(namespace="http://packages.python.org/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()

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.

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:

key_attr

String specifying an Annotation object attribute name to be used as keys for the dictionary.

key_func

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 specifying an Annotation object attribute name to be used as values for the dictionary.

value_func

Function that takes an Annotation object as an argument and returns the value to be used as a value for the dictionary.

At most one of key_attr or key_func can be specified. If neither is specified, then by default the keys are generated from Annotation.name. At most one of value_attr or value_func can be specified. If neither is specified, then by default the values are generated from Annotation.value. Key collisions will result in the dictionary entry for that key being overwritten.