API Documentation

OT object. High level wrapper for OpenTree calls

class opentree.ot_object.FilesServerWrapper(api_endpoint='files', run_mode=<WebServiceRunMode.RUN: 1>)[source]

This class provides a mid-level wrapper for interaction with OT web services and data.

class opentree.ot_object.OpenTree(api_endpoint='production', run_mode=<WebServiceRunMode.RUN: 1>)[source]

This class provides a high-level wrapper for interaction with OT web services and data. The method names are intended to be clear to a wide variety of users, rather than necessarily matching the API calls directly.

about()[source]

Get information about the Open Tree of Life taxonomy and the synthetic tree.

conflict_info(study_id, tree_id, compare_to='synth')[source]

Get node status data from any tree in the Open Tree of Life Phylesystem.

study_id : single character value
The study id from Open Tree of Life.
tree_id : single character value
The tree id of a tree within the study id provided.
compare_to : a single character value
Usually, you want this to be ‘synth’, to compare to the synthetic tree. Alternatively, you can compare your tree to any other tree in phylesystem.
conflict_str(tree_str, compare_to='synth')[source]

Get node status data from a newick string tree with ott_ids as labels, following the rough format: “((‘_nd1_ott770315’,’newick_nd2_ott417950’)’_nd3_’,’_nd4_ott158484’)’_nd5’;”.

tree_str: a tree in ‘conflict formatted’ newick string compare_to : a single character value

Usually, you want this to be ‘synth’, to compare to the synthetic tree. Alternatively, you can compare your tree to any other tree in phylesystem.
find_studies(value, search_property, exact=False, verbose=False)[source]

Get study ids that match a certain value of a given search property.

value : single character value
The study id from Open Tree of Life.
search_property : single character value
Any value from studies_properties.

exact : boolean

verbose : boolean

find_trees(value, search_property, exact=False, verbose=False)[source]

Get trees that match a certain value of a given search property.

value : single character value
The study id from Open Tree of Life.
search_property : single character value
Any value from studies_properties.

exact : boolean

verbose : boolean

get_citations(studies)[source]

Returns study citations from a list of study or tree ids

get_matchdict_from_taxlist(list_of_taxa)[source]

Input: a list of taxon names Returns: matches - a dictionary of name:ott_id and failed - a set of the names that were not found.

get_ottid_from_gbifid(gbif_id)[source]

Returns an ott id for a gbif id ott_id is set to ‘None’ if the gbif id is not found in the Open Tree Taxanomy

get_ottid_from_name(spp_name)[source]

Returns an ott id for a string - requires exact match. ott_id is set to ‘None’ if the name is not found in the Open Tree Txanomy

get_otus(study_id)[source]

Get OTUs from a study in the Open Tree of Life Phylesystem.

study_id : single character value
The study id from Open Tree of Life.
get_study(study_id)[source]

Get a study and its associated metadata.

study_id : single character value
The study id from Open Tree of Life.
get_tree(study_id, tree_id, tree_format='nexson', label_format='ot:originallabel', demand_success=False)[source]

Get a source tree from phylesystem and its associated metadata.

study_id : single character value
The study id from Open Tree of Life.
tree_id : single character value
The tree id of a tree within the study id provided.
tree_format : single character value
Must be one of “newick”, “nexson”, “nexus”, or “object” If tree format is newick or nexus, returns tree as string in that format. If “nexson”, returns semi-useless tree nexson w/o OTUS.
label_format : single character value

Must be one of “ot:originallabel”, “ot:ottid”, or “ot:otttaxonname”. “ot:originallabel” returns the tree with tip labels as it was originally

submitted to phylesystem by a curator.
“ot:ottid” returns a tree with tip labels corresponding to the matching
ott id.
“ot:otttaxonname” returns a tree with tip labels corresponding to the
matching ott taxon name.
demand_success : boolean
Whether to return an error or return a somewhat failed output silently.
studies_properties()[source]

Get properties that can be used to search across studies and trees in phylesystem.

synth_induced_tree(node_ids=None, ott_ids=None, label_format='name_and_id', ignore_unknown_ids=False)[source]

Get an induced subtree

synth_mrca(node_ids=None, ott_ids=None, ignore_unknown_ids=True)[source]

Get the most recent common ancestor of a group of taxa on the synthetic Open Tree of Life

synth_node_info(node_ids=None, node_id=None, ott_id=None, include_lineage=False)[source]

Get information of a node

synth_subtree(node_id=None, ott_id=None, tree_format='newick', label_format='name_and_id', height_limit=None)[source]

Get a subtree

taxon_info(ott_id=None, source_id=None, include_lineage=False, include_children=False, include_terminal_descendants=False)[source]

Get taxonomic information for a given taxon in the Open Tree taxonomy.

ott_id : single character value
The OTT id of a taxon.

source_id : maybe single character value

include_lineage : boolean

include_children : boolean

include_terminal_descendant : boolean

taxon_mrca(ott_ids=None)[source]
Get the node corresponding to the most recent commom ancestor (mrca) of
a taxon in the synthetic Open Tree of Life tree.
Notes from Luna:
Does it work with just one id? Since it is not always a taxon mrca, should it be called get_mrca?

ott_ids : maybe single character value

taxon_subtree(ott_id=None, label_format='name_and_id')[source]

Get a subtree of a particular taxon

tnrs_autocomplete(name, context_name=None, include_suppressed=False)[source]

Taxonomic name resolution service autocomplete

tnrs_contexts()[source]

Get a list of taxonomic contexts that can be used to constraint a TNRS match.

tnrs_infer_context(names)[source]

Infer taxonomic context for names via a TNRS (Taxonomic Name Resolution Service) match.

tnrs_match(names, context_name=None, do_approximate_matching=False, include_suppressed=False)[source]

Match taxon names to Open Tree Taxonomy using TNRS (Taxonomic Name Resolution Service).

class opentree.object_conversion.DendropyConvert[source]

Class to convert newicks to dendropy objects

class opentree.ot_command_line_tool.OTCommandLineTool(usage, name=None, common_args=None)[source]

Helper class for writing a script that uses a common set of Open Tree command line options.

parse_cli(arg_list=None)[source]

Parses arg_list or sys.argv (if None), handles basic options, returns OpenTree and args.

May call sys.exit - if the user requested an option like –version to display info and exit.

Returns an OpenTree instance configured with the specified api_endpoint and the args
object returned by the argparse object’s parse_args method
class opentree.ot_ws_wrapper.OTWebServiceWrapper(api_endpoint, run_mode=<WebServiceRunMode.RUN: 1>)[source]

This class provides a wrapper to the Open Tree of Life web service methods. Actual HTTP calls are handled by methods implemented in the base class for clarity of this code. API method calls will be mappable to methods in this class. The methods implemented here do argument checking and conversion of the returned JSON to more usable objects.

Miscellaneous light-weight functions for common operations when working with Open Tree data

opentree.util.get_suppressed_taxon_flag_expl_url()[source]

Returns the current URL describing taxon flags that lead to suppression

opentree.util.ott_str_as_int(o)[source]

Returns the OTT Id o as an integer if o is an integer or a string starting with ott (case-insensitive).

Raises a ValueError if the string does not match ^(OTT)?[0-9]+$

Writes a summary of the support/conflict info from a ToL/node_info call response blob to stream out

exception opentree.ws_wrapper.OTClientError(message, call_record=None)[source]

This type of error is raised when the calling code does not make a legitimate request based on the Open Tree of Life API’s (see https://opentreeoflife.github.io/develop/api).

exception opentree.ws_wrapper.OTWebServicesError(message, call_record=None)[source]

This type of error is raised when a web-service call fails for a reason that is impossible or difficult to diagnose. The string representation of the error should contain some helpful information.

class opentree.ws_wrapper.WebServiceCallRecord(service_wrapper, url, http_method, headers, data)[source]

Wrapper around a web-service call, returned by WebServiceWrapper methods.

The main client methods to call are:
  • __bool__ (check if status code was 200)
  • __str__ (explanation of the call status
  • write_response (writes call explanation and response, if there was one).
The most commonly used properties:
  • url: string
  • response: a requests response object
  • status_codeL: None or the HTTP status code as an integer
  • response_dict: None, decoding of a JSON response or {‘content’ : raw_content} (for non-JSON methods)
If the API call returns some encoding of a tree, then the tree property of the WebServiceCallRecord
can be used to decode the response.
curl_call

Returns a string that is a curl representation of the call

class opentree.ws_wrapper.WebServiceRunMode[source]

An enumeration.