Skip to content

Synthetic tree API v3

Jump to bottom Edit New page
Jonathan A Rees edited this page Apr 11, 2016 · 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 graph. The node of interest may be specified using either a node id or an taxon id, but not both. If the specified node or OTT id is not in the graph, 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.
  • ott_id : (long int) The ott id of the node of interest. This argument may not be combined with node_id.
  • 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.
  • 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.

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

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). Node ids that are not in the synthetic tree are dropped from the MRCA calculation. For a valid OTT id that is not in the synthetic tree (i.e. it is not recovered as monophyletic from the source tree information), the taxonomic descendants of the node are used in the MRCA calculation.

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

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: for format=newick, maxtips = 25000 and for format=arguson, limit=??

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.

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

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 consistuted 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

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, 666104, 316878, 102710]}'

Example result:

{
  "newick" : "(((Cinclus_ott267845,Setophaga_ott666104),(Perdix_ott102710,Clangula_ott316878)Galloanserae_ott5839486)Neognathae_ott241846,Struthio_ott292466)Aves_ott81461;"
}
Add a custom footer
Add a custom sidebar

Clone this wiki locally