Skip to content

Open Tree API datatypes

Jump to bottom Edit New page
Karen Cranston edited this page Apr 17, 2017 · 16 revisions

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-descriptor

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

  • ott_id : (integer) 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-descriptor

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

The support-descriptor values are always nonempty - if there are no nodes in a particular category, then that category is simply absent rather than being an empty dictionary, {}.

Whenever a node-descriptor 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-descriptor

The support-descriptor describes the source tree nodes that correspond to nodes in the synthetic tree. A support-descriptor 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. The various support types are:

  • terminal - input tree nodes (one per tree) that are equivalent to this synthetic tree node (via an exact mapping, or the input tree terminal may be the only terminal descended from this synthetic tree node)
  • supported_by - input tree nodes (one per tree) that support this synthetic tree node
  • partial_path_of - the edge below this synthetic tree node is compatible with the edge below each of these input tree nodes (one per tree). This is not the only edge in the synthetic tree that maps to these nodes in the input trees; multiple synthetic tree edges are redundant with respect to the leaf set of each input tree.
  • resolves - input tree nodes (one per tree) resolved by this synthetic tree node. Each of these input tree nodes could be resolved in a manner that would display a node that corresponds to this synthetic tree node.
  • resolved_by - input tree nodes (one or more per tree) that resolve this synthetic tree node.
  • conflicts_with - input tree nodes (one or more per tree) that conflict with this synthetic node.

For more detailed information on the support and conflict information, see the documentation on Comparing trees.

Example:

  "partial_path_of" : {
    "pg_2573@tree5959" : "node1011373"
  },
  "supported_by" : {
    "taxonomy" : "ott2.9draft12"
  },
  "terminal" : {
    "pg_2822@tree6569" : "ott240568"
  }

The sourceid-string is a short identifier for a 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 descriptor 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 a simple id string. Example:

  "source_id_map" : {
    "pg_2573@tree5959" : {
      "git_sha" : "c6ce2f9067e9c74ca7b1f770623bde9b6de8bd1f",
      "tree_id" : "tree5969",
      "study_id" : "pg_2573"
    },
    "ott2.9draft12" : {
      "taxonomy" : "ott2.9draft12"
    }
  }

extended-taxon-descriptor

Certain taxonomy-related methods return taxon-descriptors that contain the additional taxon properties flags, synonyms, and is_suppressed.

  • ott_id : (integer) 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) Whether or not the taxon is suppressed from TNRS results. See the taxonomy documentation for a list of flags that lead to suppression.
Add a custom footer
Add a custom sidebar
Clone this wiki locally