"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 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 sourceToMetaMap object.
• ott_id (v2: ottId) optional string
• name optional string - taxonomic name, if any
• tax_sources optional list of string - list of taxonomic sources e.g. ["ncbi:123", "gbif:456"]. Each source is given as an RDFa CURIEorURI. (v2: taxSource string - comma-separated sequence of taxonomic sources)
• tax_rank (v2: taxRank) optional string - taxonomic rank, e.g. "species"

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 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) - lineage from parent (first) to root (last).
• 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) except that these nodes have:

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