"Arguson" format

ArguSON is an internal format used for communication between the synthetic tree server (treemachine or tm-lite) and the tree browser (opentree webapp). It should not be considered stable and is subject to change without notice. This page documents "version 3" of ArguSON as generated by "tm-lite".

The main difference between version 2 and version 3 is harmonization of property names with other methods in the API such as node_info and [taxon_info](Taxonomy API v3). See Synthetic tree API v3 for documentation for the synthetic tree v3 API.

There is an unadvertised API method (treemachine/getSyntheticTree) that delivers an ArguSON payload in response to a request that provides a synthetic tree node id.

(The following was copied from v2 ArguSON description in a google doc, and subsequently modified for v3.)

See http://phylo.bio.ku.edu/ot/getSyntheticTree-out.json for a version 2 example for the root, and http://phylo.bio.ku.edu/ot/getSyntheticTree-11-out.json for a version 2 example of a node that has a non-empty pathToRoot).

An ArguSON payload is a set of nested JSON object reflecting the nesting structure of the synthetic tree. The top-level JSON object corresponds to the requested node.

The core properties of an ArguSON node object are:

• node_id string - id of synthetic tree node (v2: nodeid integer - neo4j node ID)
• supported_by (v2: supportedBy) - list of strings. Each string is either “taxonomy” or an opaque key into the source_to_meta_map object.
• ott_id (v2: ottId) optional integer (still string in implementation?). This is redundant with node_id in that if if node_id has the form "ott1234" then ott_id will be 1234, but I think it's a good idea if clients don't need to know this convention.
• name optional string - taxonomic name, if any
• tax_sources optional list of string - list of taxonomic sources e.g. ["ncbi:123", "h2007:", "http://dx.doi.org/10.1186/1471-2148-14-23"]. Each source is given as an RDFa CURIEorIRI. See also here. (v2: taxSource string - comma-separated sequence of taxonomic sources)
• tax_rank (v2: taxRank) (should be rank for consistency with v3/tree_of_life optional string - taxonomic rank, e.g. "species"
• (Considering: unique_name - the tree browser does not use this, so probably not)

(To be consistent with the v3 API, all the taxon-specific fields (everything other than node_id) should be gathered together into a blob under the taxon key.)

The tree-structure-conveying properties are:

• either a children list of node objects, or has_children (v2: hasChildren) boolean (if the node is in the last level of ArguSON nodes returned),
• leaves_in_view (v2: nleaves) int - note: This is not the number of leaves in the synthetic tree under this node, just in this pruned ArguSON subtree in this ArguSON document.

The “top level” ArguSON node object in a web service call will also have:

• max_node_depth (v2: maxnodedepth) int - info on the pruning level
• path_to_root (v2: pathToRoot) ordered list of brief node info objects (see below) - lineage from parent (first) to root (last).
• source_id_map (source_to_meta_map?) (v2: sourceToMetaMap) key value mapping - For trees, the three fields of each value are tree_id, study_id, and git_sha (the SHA for the study). When the key is "taxonomy" the value has a version property.

A "brief" node object in the path_to_root list is an object with just the “core” properties (it lacks children, has_children (which is not needed because it is obviously true), and leaves_in_view properties). In v2 these nodes had:

• (v2: supporting_sources instead of the supported_by property of a full ArguSON - in v3, just use supported_by)
• (v2: uniqname string - from uniqname taxonomy column. Not used. I propose to remove it.)