Skip to content

Synthetic tree API v3

Jump to bottom Edit New page
Mark T. Holder edited this page Oct 20, 2020 · 67 revisions

Methods to access information about and representations of the (current) draft synthetic tree of life. These methods do not accept taxon names as input, but instead require either:

The base URL for all services:

https://api.opentreeoflife.org/v3/

This page is part of the Open Tree of Life Web APIs.

Detailed descriptions for each method follow below the summary table.

URL Verb Summary
/tree_of_life/about POST Return information about the current synthetic tree itself.
/tree_of_life/node_info POST Return information about a node in the tree.
/tree_of_life/mrca POST Return the most recent common ancestor of a list of nodes in the synthetic tree.
/tree_of_life/subtree POST Return the complete subtree below a given node.
/tree_of_life/induced_subtree POST Return the induced subtree on the synthetic tree that relates a list of nodes.

about (tree of life)

Return information about the current synthetic tree.

POST    /tree_of_life/about

Returns summary information about the current synthetic tree of life, including information about the list of source trees and the taxonomy used to build it.

Input parameters
Parameters with bold type definitions are required.

  • include_source_list : (boolean) Return an ordered list of source trees; default = false

Output parameters

  • date_created : (string) The creation date of the tree
  • num_source_studies : (integer) The number of studies (publications) used as sources
  • num_source_trees : (integer) The number of trees used as sources (may be >1 tree per study)
  • taxonomy : (string) The Open Tree Taxonomy version used as a source
  • filtered_flags : (list of strings) Taxa with these taxonomy flags were not used in construction of the tree
  • root : (dict) Describes the root node; see node-descriptor for details
  • source_list : (list of strings) Present if include_source_list is "true"; each item is a sourceid-string; length is num_source_trees; sourceid_map contains details for each string. The ordering is the precedence order for synthesis, with relationships from earlier trees in the list having priority over those from later trees in the list
  • source_id_map : (dict) Present if include_source_list is "true"; keys are sourceid-strings from source_list; values are git_sha, treeid, studyid; see sourceid_map for details
  • synth_id : (string) The unique string for this version of the tree

Example command:

$ curl -X POST https://api.opentreeoflife.org/v3/tree_of_life/about -H "content-type:application/json" -d '{"include_source_list":true}'

Example result: (source list abbreviated)

{
  "source_list" : [ "pg_2000@tree4098", "ot_167@tree1", "pg_2048@tree4220", "pg_2689@tree6241" ],
  "date_created" : "2016-03-18 15:28:40",
  "root" : {
    "taxon" : {
      "tax_sources" : [ "ncbi:131567" ],
      "unique_name" : "cellular organisms",
      "name" : "cellular organisms",
      "rank" : "no rank",
      "ott_id" : 93302
    },
    "num_tips" : 2424255,
    "node_id" : "ott93302"
  },
  "num_source_trees" : 485,
  "taxonomy" : "ott2.9draft12",
  "source_id_map" : {
    "pg_2000@tree4098" : {
      "git_sha" : "e163a9245c15aefbba79defb685df98d5a73cab3",
      "tree_id" : "tree4098",
      "study_id" : "pg_2000"
    },
    "ot_167@tree1" : {
      "git_sha" : "e163a9245c15aefbba79defb685df98d5a73cab3",
      "tree_id" : "tree1",
      "study_id" : "ot_167"
    },
    "pg_2048@tree4220" : {
      "git_sha" : "e163a9245c15aefbba79defb685df98d5a73cab3",
      "tree_id" : "tree4220",
      "study_id" : "pg_2048"
    },
    "pg_2689@tree6241" : {
      "git_sha" : "e163a9245c15aefbba79defb685df98d5a73cab3",
      "tree_id" : "tree6241",
      "study_id" : "pg_2689"
    },
  },
  "num_source_studies" : 479,
  "filtered_flags" : [ "major_rank_conflict", "major_rank_conflict_inherited", "environmental", "unclassified_inherited", "unclassified", "viral", "barren", "not_otu", "incertae_sedis", "incertae_sedis_inherited", "extinct_inherited", "extinct", "hidden", "unplaced", "unplaced_inherited", "was_container", "inconsistent", "hybrid", "merged" ],
  "synth_id" : "opentree4.1"
}

node_info

Get information about a node in the tree.

POST    /tree_of_life/node_info

Returns summary information about a node in the summary tree (if given node_id or ott_id), or multiple nodes in the summary tree (if given node_ids). Exactly one of ott_id, node_id, or node_ids may be supplied. If a specified node or OTT id is not in the summary tree, an error will be returned.

Input parameters

Parameters with bold type definitions are required.

  • node_id : (string) The node id of the node of interest. This argument may not be combined with ott_id or node_ids.
  • ott_id : (long int) The ott id of the node of interest. This argument may not be combined with node_id or node_ids.
  • node_ids: (list of string) List of node ids. This argument may not be combined with node_id or ott_id. (Backwards-compatible addition, added on 4/22/2019).
  • include_lineage : (boolean) Include the ancestral lineage of the node in the synthetic tree. If this argument is true, then a list of all the ancestors of this node in the synthetic tree, down to the root of the tree itself, will be included in the results. Higher list indices correspond to more inclusive (i.e. deeper) ancestors, with the immediate parent of the specified node occupying position 0 in the list.

Output parameters

  • node_id: (string) The canonical identifier of the node. This may be different than the input node_id.
  • query: (string) The node id that resolved to this node. This can differ from the node_id field if the query id is not canonical.
  • num_tips: (integer) The number of descendent tips
  • taxon : (dict) Taxonomy fields (ott_id, name, rank : rank-string, unique_name, tax_sources), present if the node is a taxon. See taxon-descriptor for details.
  • All the other fields of a node-descriptor are output parameters, including support/conflict information and source_id_map
  • lineage : (list of node-descriptors) The path going to the root of the tree, starting with this node's parent.

If the node_ids input parameter is used, the response will be a list of such objects.

Example command:

$ curl -X POST https://api.opentreeoflife.org/v3/tree_of_life/node_info -H "content-type:application/json" -d '{"ott_id":81461}'

Example result:

{
  "partial_path_of" : {
    "pg_2573@tree5959" : "node1011373"
  },
  "supported_by" : {
    "taxonomy" : "ott2.9draft12"
  },
  "source_id_map" : {
    "pg_2573@tree5959" : {
      "git_sha" : "e163a9245c15aefbba79defb685df98d5a73cab3",
      "tree_id" : "tree5959",
      "study_id" : "pg_2573"
    },
    "taxonomy" : {
      "name" : "ott",
      "version" : "ott2.9draft12"
    },
    "pg_2822@tree6569" : {
      "git_sha" : "e163a9245c15aefbba79defb685df98d5a73cab3",
      "tree_id" : "tree6569",
      "study_id" : "pg_2822"
    }
  },
  "taxon" : {
    "tax_sources" : [ "ncbi:8782", "worms:1836", "gbif:212", "irmng:1142" ],
    "unique_name" : "Aves",
    "name" : "Aves",
    "rank" : "class",
    "ott_id" : 81461
  },
  "num_tips" : 14302,
  "terminal" : {
    "pg_2822@tree6569" : "ott240568"
  },
  "node_id" : "ott81461"
}
  • 4/22/2019: Added node_ids input parameter. Added field query in response objects.

mrca

Return the most recent common ancestor of a list of nodes in the synthetic tree.

POST    /tree_of_life/mrca

Get the MRCA of a list of nodes on the current synthetic tree. Accepts any combination of node ids and OTT ids as input. Returns information about the most recent common ancestor (MRCA) node as well as the most recent taxonomic ancestor (MRTA) node (the smallest taxon that encompasses the query; the MRCA and MRTA may be the same node).

If any of the node_ids does not designate a node in the synthetic tree, or if any of the ott_ids does not designate a taxon, the method yields a 400 response.

Input parameters

Parameters with bold type definitions are required.

  • node_ids : (list of string) A list of node id strings
  • ott_ids : (list of int) A list OTT id integers

Output parameters

  • mrca : a node-descriptor that describes the node that is the mrca of the input ids
  • nearest_taxon : a taxon-descriptor that describes the mrta of the input ids; present only if the mrca is not a taxon
  • source_id_map : (dict) Keys are sourceid-strings from support statements in the mrca node-descriptor; values are git_sha, treeid, studyid; see sourceid_map for details.

Example command:

$ curl -X POST https://api.opentreeoflife.org/v3/tree_of_life/mrca -H "content-type:application/json" -d '{"node_ids":["ott3600590", "ott267845"], "ott_ids":[292466,3600785]}'

Example result:

{
  "mrca" : {
    "partial_path_of" : {
      "pg_2573@tree5959" : "node1011373"
    },
    "supported_by" : {
      "ott2.9draft12" : "ott81461"
    },
    "taxon" : {
      "tax_sources" : [ "ncbi:8782", "worms:1836", "gbif:212", "irmng:1142" ],
      "unique_name" : "Aves",
      "name" : "Aves",
      "rank" : "class",
      "ott_id" : 81461
    },
    "num_tips" : 14302,
    "terminal" : {
      "pg_2822@tree6569" : "node1142003"
    },
    "node_id" : "ott81461"
  },
  "source_id_map" : {
    "ott2.9draft12" : {
      "taxonomy" : "ott2.9draft12"
    },
    "pg_2573@tree5959" : {
      "git_sha" : "e262908a364e3b73ba5e8996fceba51e6997167a",
      "tree_id" : "tree5959",
      "study_id" : "pg_2573"
    },
    "pg_2822@tree6569" : {
      "git_sha" : "e262908a364e3b73ba5e8996fceba51e6997167a",
      "tree_id" : "tree6569",
      "study_id" : "pg_2822"
    }
  }
}

New, experimental feature:

If you find any problems with the feature described below, please Report an issue here

If you include a non-empty list of OTT identifiers in an excluded_node_ids argument in the mrca method, the server will return an terse list of node_ids and the tree's synth_id:

$ curl -X POST https://api.opentreeoflife.org/v3/tree_of_life/mrca -d '{"node_ids": ["ott271578","ott1068778"], "excluded_node_ids": ["ott913935"]}'

Example output:

{
  "node_ids": [
    "mrcaott102ott8118",
    "mrcaott102ott283439",
    "ott816256",
    "mrcaott102ott739",
    "mrcaott42ott102",
    "mrcaott42ott55942",
    "mrcaott42ott45197",
    "ott839752",
    "ott7067181",
    "mrcaott42ott254702",
    "mrcaott42ott48903",
    "mrcaott42ott38834",
    "mrcaott42ott10477",
    "ott864593",
    "mrcaott42ott29157",
    "ott392220",
    "mrcaott42ott30082"
  ],
  "synth_id": "opentree12.3"
}

The response node_ids will be a list starting with the MRCA of the node_ids argument passed to the call, then it's parent, then it's grandparent, etc such that the last node listed in the node_ids list will be the deepest node that is not the ancestor of any OTT listed in the excluded_node_ids

If one of the excluded_node_ids is a descendant of the MRCA of the input node_ids, then a 404 will be returned and the JSON body of the response will contain a reversals field that is a list of OTT identifiers that are descendants of this MRCA:

$ curl -i -X POST https://api.opentreeoflife.org/v3/tree_of_life/mrca -d '{"node_ids": ["ott271578","ott1068778"], "excluded_node_ids": ["ott1068778", "ott913935"]}'

outputs:

HTTP/1.1 404 Not Found
[clipped curl output]
{
  "message": "[/v3/tree_of_life/mrca] Error: Excluded taxa were nested within the include group!",
  "reversals": ["ott1068778"],
  "synth_id": "opentree12.3"
}

subtree (tree of life)

Return the subtree below a given node.

POST    /tree_of_life/subtree

Given a node, return the subtree of the synthetic tree descended from that node, either in Newick or ArguSON format. The start node may be specified using either a node id or an ott id, but not both. There are size limits on this method: maxtips = 25000.

For Newick format results, the leaf labels of the tree may be either taxonomic names, node ids, or the two combined as name_id, depending on the value of the label_format parameter. Nodes in the result not corresponding directly to named taxa will be unlabeled. The Newick string will have no branch lengths.

If any of the node_ids does not designate a node, or if any of the ott_ids does not designate a taxon, the method yields a 400 response.

Input parameters

Parameters with bold type definitions are required.

  • node_id : (string) The node id of the node in the tree that should serve as the root of the tree returned. This argument may not be used in combination with ott_id.
  • ott_id : (integer) The OTT id of the node in the tree that should serve as the root of the tree returned. This argument may not be used in combination with node_id.
  • format : (string) Defines the tree format; either "newick" or "arguson"; default="newick"
  • label_format : (string) For format=newick only; defines the label type; one of “name”, “id”, or “name_and_id”; default = “name_and_id”
  • height_limit : (integer) maximum number of edges on path between root and tips; limits the depth of the subtree; default = 3 with format=arguson; default = -1 (no limit) with format=newick

Output parameters

  • newick : (string) The subtree in newick format; present if format=newick
  • arguson : (dict) The subtree in arguson format; see arguson documentation for details
  • supporting_studies : (list of string) Study ids for studies that contribute trees that support nodes in the subtree (for newick format only, since the arguson format already includes this information)

Example command:

$ curl -X POST https://api.opentreeoflife.org/v3/tree_of_life/subtree -H "content-type:application/json" -d '{"node_id":"ott803675"}'

Example result:

{
  "newick" : "(Gavia_stellata_ott1057044,((Gavia_arctica_ott1085739,Gavia_pacifica_ott651474)mrcaott651474ott1085739,(Gavia_immer_ott1057518,Gavia_adamsii_ott90560)mrcaott90560ott1057518)mrcaott90560ott651474)Gavia_ott803675;"
}

induced_subtree

Return the induced subtree on the synthetic tree that relates a list of nodes.

POST    /tree_of_life/induced_subtree

Return a tree with tips corresponding to the nodes identified in the input list(s), that is consistent with topology of the current synthetic tree. This tree is equivalent to the minimal subtree induced on the synthetic tree by the list of identified nodes. Any combination of node ids and OTT ids may be used as input. The Newick string is constituted the same way as for the subtree method.

If any of the node ids does not designate a node, or if any of the OTT ids does not designate a taxon, the method yields a 400 response.

Input parameters

Parameters with bold type definitions are required.

  • node_ids : (list of string) A list of node id strings
  • ott_ids : (list of int) A list of OTT id integers
  • label_format : (string) Defines the label type; one of “name”, “id”, or “name_and_id”; default = “name_and_id”

Output parameters

  • newick : (string) The subtree in newick format
  • supporting_studies : (list of string) Study and tree ids for studies that contribute trees that support nodes in the subtree, in the format "studyid@treeid", e.g. "ot_1046@tree1"

Example command:

$ curl -X POST https://api.opentreeoflife.org/v3/tree_of_life/induced_subtree -H "content-type:application/json" -d '{"ott_ids":[292466, 267845, 316878, 102710]}'

Example result:

 "broken": {},
 "newick": "(((((((((((((((((((((((((((((Cinclus_ott267845)Cinclidae_ott496027)mrcaott1566ott496009)mrcaott1566ott3598440)mrcaott246ott1566)mrcaott246ott5934)mrcaott246ott3364)mrcaott246ott1488)mrcaott246ott10351)mrcaott246ott176461)mrcaott246ott22325)mrcaott246ott4820)mrcaott246ott32658)mrcaott246ott5929)mrcaott246ott44866)mrcaott246ott428578)mrcaott246ott3212)Passeriformes_ott1041547)mrcaott246ott7113)mrcaott246ott47588)mrcaott246ott3600042)mrcaott246ott2907)mrcaott246ott1858)mrcaott246ott928360)mrcaott246ott5272)mrcaott246ott7145)mrcaott246ott5021)mrcaott246ott5481,((((((((((((((((Perdix_ott102710)mrcaott53700ott466627)mrcaott53700ott572162)mrcaott4765ott53700)mrcaott4765ott51354)mrcaott4765ott415487)mrcaott4765ott49310)mrcaott4765ott49319)mrcaott4765ott54193)mrcaott4765ott151684)mrcaott4765ott104461)mrcaott4765ott75785)mrcaott4765ott109888)mrcaott4765ott6520194)Galliformes_ott837585)mrcaott4765ott6520193,(((((((Clangula_ott316878)mrcaott145504ott316879)mrcaott30843ott145504)mrcaott30843ott962771)mrcaott30843ott75874)Anatidae_ott765193)mrcaott30843ott714464)Anseriformes_ott241841)mrcaott4765ott30843)mrcaott246ott4765,((Struthio_ott292466)Struthionidae_ott857849)mrcaott84218ott1007318)Aves_ott81461;",
 "supporting_studies": [
  "ot_425@tree1",
  "ot_521@tree1",
  "ot_809@tree2",
  "pg_2804@tree6511",
  "ot_290@tree1",
  "ot_783@tree1",
  "pg_2015@tree4152",
  "ot_531@tree1",
  "ot_782@Tr48736",
  "ot_841@tree1",
  "pg_2913@tree6742",
  "ot_534@tree1",
  "ot_757@Tr70438",
  "pg_420@tree522",
  "ot_412@Tr77157",
  "ot_500@tree1",
  "ot_532@tree1",
  "pg_2404@tree5068",
  "pg_2404@tree6388",
  "pg_2913@tree6741",
  "ot_111@tree1",
  "ot_753@tree1",
  "pg_2577@tree5980",
  "ot_1002@tree1",
  "ot_1345@Tr109614",
  "ot_855@tree1",
  "ot_1174@tree3",
  "pg_2866@tree6656",
  "ot_1022@tree1",
  "ot_314@tree1",
  "ot_1516@Tr55113"
 ]
}
Add a custom footer
Add a custom sidebar
Clone this wiki locally