Otindex and Oti differences

26/09/2016: This page is in progress and should not be taken as final documentation

We have tried to replicate the OTI v3 API study methods in otindex. There are several differences, some incompatible. Many of the differences are due to deprecated (or proposed but never implemented) NeXSON properties. For more information about NeXSON, see the NeXSON documentation and also this google spreadsheet, which lists implementation status in each codebase.

There are three methods implemented in oti: find_studies, find_trees and properties. See links to "studies" methods on the OpenTree API documentation page for official documentation about the v3 (oti) methods. Otindex implements these methods, along with an about methods that list properties of the phylesystem.

about

Returns information about the phylesystem

 GET /studies/about

Sample return:

{
   "number_curators": 146, 
   "number_trees": 7902, 
   "data_store_url": "https://github.com/opentreeoflife/phylesystem/", 
   "number_studies": 3523, 
   "number_otus": 3453839
}

find_studies

find_trees

properties

Method lists the searchable properties for trees and studies.

$ curl -X POST https://api.opentreeoflife.org/v3/studies/properties

The biggest change is that otindex can search on any top-level study or tree property in phylesystem.

Result:

{
    "study_properties": ["dc:subject", "dc:date", "ot:messages", "dc:title", "skos:changeNote", "ot:studyPublicationReference", "ot:candidateTreeForSynthesis", "ot:taxonLinkPrefixes", "ot:focalCladeOTTTaxonName", "prism:modificationDate", "dc:contributor", "dc:creator", "xmlns", "ot:curatorName", "prism:number", "tb:identifier.study.tb1", "id", "dcterms:bibliographicCitation", "ot:dataDeposit", "skos:historyNote", "ot:treesElementOrder", "prism:endingPage", "prism:section", "nexml2json", "ot:notIntendedForSynthesis", "ot:otusElementOrder", "treesById", "about", "tb:identifier.study", "ot:studyYear", "otusById", "nexmljson", "ot:annotationEvents", "prism:doi", "ot:studyId", "prism:pageRange", "dc:publisher", "ot:studyPublication", "prism:volume", "tb:title.study", "ot:agents", "generator", "prism:publicationDate", "prism:publicationName", "ot:comment", "ot:focalClade", "prism:startingPage", "xhtml:license", "prism:creationDate", "version", "ot:tag", "ntrees", "treebaseId"], 
    "tree_properties": ["ot:messages", "xsi:type", "ot:nearestTaxonMRCAName", "meta", "ot:specifiedRoot", "tb:quality.tree", "ot:branchLengthTimeUnit", "ot:nodeLabelMode", "ot:rootNodeId", "ot:inGroupClade", "ot:branchLengthDescription", "ot:MRCAName", "ot:unrootedTree", "ot:nodeLabelTimeUnit", "tb:type.tree", "edgeBySourceId", "ot:nodeLabelDescription", "nodeById", "ot:curatedType", "ot:nearestTaxonMRCAOttId", "ot:tag", "rootedge", "label", "tb:ntax.tree", "tb:kind.tree", "ot:outGroupEdge", "ot:branchLengthMode", "ot:MRCAOttId", "ot:ottId", "ot:studyId", "ntips", "proposed"]
}

Here are the details of the added / deprecated properties.

##Study properties##

Oti returns 19 study properties (17 documented), while otindex returns 53 study properties.

Deprecated properties:

• These properties are returned as searchable by oti, but never actually implemented: ot:studyModified, ot:focalCladeOTTId, ot:studyLastEditor, ot:studyLabel, ot:authorContributed, ot:studyUploaded, ot:focalCladeTaxonName, is_deprecated
• ot:candidateTreeForSynthesis: this is now a tree-level property, rather than a list of trees at the study-level

New properties:

These properties are in addition to the full list of NeXSON study-level properties (see the NexSON and NeXML documentation for details of NexSON properties).

• ntrees: number of trees in the study
• treebaseId: extracted from the data deposit URL if the study comes from treebase

##Tree properties

Oti returns 18 tree properties (17 documented), while otindex returns 32 tree properties.

Deprecated properties:

• These properties were returned as searchable by oti, but never actually implemented: ot:treeModified, is_deprecated, ot:treeLastEdited, ot:treebaseTreeId
• These 'tree' properties are actually properties of OTUs: ot:treebaseOTUId, ot:originalLabel,
• ot:comment is a study-level property
• ot:branchLengthTimeUnits is a typo: in the NeXSONs, this is (singular) ot:branchLengthTimeUnit
• oti_tree_id property was an internal oti database identifier that concatenated the study_id and tree_id. In Otindex, we store the NeXSON tree_id and study_id separately, and use both pieces of information to identify a tree.

New properties:

These properties are in addition to the full list of NeXSON study-level properties (see the NexSON and NeXML documentation for details of NexSON properties).

• ntips : the number of OTUs in a tree
• proposed : whether the tree has been proposed for synthesis; replaced ot:candidateTreeForSynthesis in the v3 methods. Currently a boolean. In near future, property name will change, and will become a string, representing one of many states, instead of a boolean.

##Other changes##

• multi-value properties (such as ot:curator or ot:tag) have all values in the database, not just one of the values