Open Tree API datatypes

The APIs use a number of standardized dictionaries to group fields in the output parameters. This doc describes these custom datatypes.

This page is part of the Open Tree of Life Web APIs.

##taxon-blob

The taxon-blob groups fields about a taxon. It is used in the tree-of-life and taxonomy methods. A taxon blob has the following fields (a field is absent if no value, not returned as empty string):

• ott_id : (int) the OTT ID
• name : (string) taxon-name-string
• rank : (string) rank-string
• unique_name : (string) the string that uniquely identifies the taxon in OTT
• tax_sources : (list of strings) an ordered list of identifiers for taxonomic sources, such as other taxonomies, that define taxa judged equivalent to this taxon. Each string in the list has a CURIEorIRI syntax, so this field might hold [“ncbi:9242”, “h2007:”, “http://dx.doi.org/10.9779/azhjj0”], for example.

##node-blob The node-blob groups the following fields that describe a node in the synthetic tree:

• node_id : (string) the ID of the synthetic tree node, e.g. “mrcaott3504ott396446”
• taxon : { } a taxon-blob; present only if the node is a taxon
• num_tips : (int) the number of tips in the synthetic tree reachable tipward from the specified node; zero if the node is itself a synthetic tree tip.
• supported_by : support-blob
• conflicts_with : { … } support-blob
• resolves : { … } support-blob
• partial_path_of : { … } support-blob
• terminal : { … } support-blob

The support-blob values are always nonempty. If there are no conflicting (resolving, etc.) source nodes, then the blob has no conflicts_with (resolves, etc.) field rather than a field whose value is an empty dictionary {}.

Whenever a node-blob is returned by a method, there is also (elsewhere in the method response) a source-id-map (see below) so that the source tree ids in the support/conflict properties can be interpreted.

##support-blob The support-blob describes the source tree nodes that correspond to nodes in the synthetic tree. A support-blob is a dictionary keyed by source tree id (sourceid-string). The value is either a single nodeid-string, or a list of nodeid-strings, depending on whether the support/conflict relation involved is one-to-one or one-to-many. supported_by, resolves, and terminal are one-to-one; partial_path_of and conflicts_with are one-to-many.

Example:

    "supported_by" : {
      "pg_1944@tree3959" : "node741000",
      "pg_2539@tree6294" : "node1094822"
    }
    {
      "pg_1944@tree3959" : ["node741000", "node1094822"],
     ...
    }

The sourceid-string is a short identifier for an source tree (or taxonomy). There are several properties required to uniquely identify a source, so we return the full description only once per result (in the source-id-map) and simply return a unique string with pseudo-type sourceid-string in the support-blob. Client code should treat this string as an opaque key and look up the full information in the the source-id-map, which provides full information for each source.

##source-id-map The full description of a source tree consists of a study ID, a tree ID, and the SHA that identifies the version of the study. A source-id-map object is a dictionary with sourceid-strings as keys. The value associated with each key is a blob with three properties: git_sha, tree_id, study_id. The values for each of these properties are strings. The source-id-map can also list the taxonomy as a source, with name and version as properties. Example:

"source_id_map" : {
      "pg_2573@tree5959" : {
        "git_sha" : "c6ce2f9067e9c74ca7b1f770623bde9b6de8bd1f",
        "tree_id" : "tree5959",
        "study_id" : "pg_2573"
      },
      {
        "taxonomy" : {
          "name" : "ott",
          "version" : "2.9draft12"
        }
      }
    }

##extended-taxon-blob Certain taxonomy-related methods return taxon blobs that contain the additional taxon properties flags, synonyms, and is_suppressed.

• ott_id : (int) the OTT ID
• name : (string) taxon-name-string
• rank : (string) rank-string
• unique_name : (string) the string that uniquely identifies the taxon in OTT
• tax_sources : (list of strings) an ordered list of identifiers for taxonomic sources, such as other taxonomies, that define taxa judged equivalent to this taxon. Each string in the list has a CURIEorIRI syntax, so this field might hold [“ncbi:9242”, “h2007:”, “http://dx.doi.org/10.9779/azhjj0”], for example.
• flags : (list of strings) see the taxonomy documentation for more info
• synonyms : (list of strings) the synonyms for this taxon
• is_suppressed : (boolean) ???