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.
-
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_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
-
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.
-
-
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]+$
-
opentree.util.
write_node_info_links_to_input_trees
(blob, out=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>)[source]¶ 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