"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. 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 [CURIEorURI](https://www.w3.org/TR/2011/WD-rdfa-core-20110331/#dfn-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 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_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 (question: not clear why this would be in the brief node but not in non-brief nodes. it should be in both or neither. if not used by tree browser, I suggest neither. if it is used, then maybe it should be optional when the uniqname is the same as the name.)