"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".

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 are:

• name - string
• node_id - string node id (document me)
• v2: nodeid - integer neo4j node ID - support discontinued on v3 release
• tax_sources - list of taxonomic sources e.g. ["ncbi:123", "gbif:456"]. Each source string is an RDFa CURIEorURI.
• v2: taxSource - string. comma-separated sequence of taxonomic sources e.g. `"ncbi:123,gbif:456"
• tax_rank - taxonomic rank as a string, e.g. "species". Optional
• v2: taxRank - optional string
• v2: ottId - optional string
• supported_by (v2: supportedBy) - list of strings. Each string is either “taxonomy” or an opaque key into the sourceToMetaMap object.

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),
• new name? (v2: nleaves) int - note: This is not the number of leaves in the synthetic tree under this node, just in this pruned ArguSON sub graph.

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) from parent (first) to root (last).
• source_to_meta_map (v2: sourceToMetaMap) key value mapping. For studies the 3 fields of each value are git_sha, tree_id, and study_id. When the key is "taxonomy" it 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 nleaves (replacement) properties) except that these nodes have:

• (v2: supporting_sources instead of the supported_by property of a full ArguSON - in v3, use supported_by)
• uniqname string from taxonomy column of same name