Taxonomic service for adding new taxa
Mockups here
Our initial use case is from the curation webapp, using the modal popup shown here:
The request (from the webapp to the service) looks something like this:
{
"taxa": [{"tag": arbitrary *string* value (unique among the listed taxa),
"name": string (proper name for this taxon),
"original_label": string, unchanged from the input tree / OTU (optional),
"adjusted_label": string, as modified by regex or manual edits (optional),
"name_derivation": reason for name changes, from a controlled vocabulary (pulldown),
"rank": rank (optional),
"parent": OTT id,
"sources" : [{"source": curieOrURI,
"source_type": from controlled vocabulary (pulldown) },
...],
"comment": string (optional)},
{"tag": tag, ...}],
"study_id": the study id (optional),
"curator": {"name": string,
"login": string,
"email": string},
"user_agent": string, with an expected values like "opentree-curation-webapp"
}
The purpose of the tags is just to match the metadata in the request with the new OTT ids coming back in the response. The webapp could use OTU ids as tags, but it wouldn't have to.
The response looks something like this:
{"id": additions doc id, "assignments": [{"tag": tag, "ott_id": OTT id}, ...]}
The effect is to
- create a new additions document that looks like the request but with OTT ids added
- deposit it in a phylesystem-like additions repository on github
- alert taxomachine that it needs to index the new taxa
- eventually tell smasher to add the new taxa to the next version of OTT (actually smasher will just read the whole additions repository)
The additions doc id gives the file location in the repository. It is provided in case someone wants to edit it later. If we're lucky we won't need this in the webapp right away, but it's easy to imagine a different client needing it, if only for debugging purposes.
The choice of additions doc is up to the service, but one way to build it would be to get the lowest and highest numbered OTT ids defined in it, say x and y, and let the doc id be x-y.json or additions-x-y.json.
Update: This new service has been implemented in phylesystem-api and peyotl. The new-taxon UI makes early calls to /v3/tnrs/match_names (to check for duplicates) and /v3/tnrs/autocomplete_name (to help find the parent taxon), but the actual submission is done via POST to /v3/amendment. Here's an example call (with JSON formatted for clarity) using cURL:
curl 'https://devapi.opentreeoflife.org/v3/amendment?author_name=Jim+Allman&author_email=jim%40ibang.com&auth_token=REDACTED' \
-H 'Content-Type: application/json; charset=UTF-8' \
--data-binary '\
{
"user_agent":"opentree-curation-webapp",
"date_created":"2016-08-31T06:37:45.202Z",
"taxa":[
{
"tag":"otu388719",
"original_label":"Phytophthora taxon clade8a1 P10355",
"adjusted_label":"Phytophthora taxon KLAID8a1 P10355",
"name":"Phytophthora taxon clade8a1 P10355",
"name_derivation":"No change to original label",
"rank":"species",
"parent":933772,
"sources":[
{"source_type":"The taxon is described in this study",
"source":null}
],
"comment":"IGNORE this test."
},
{
"tag":"otu388728",
"original_label":"Phytophthora taxon clade8a1 P3876",
"adjusted_label":"Phytophthora taxon KLAID8a1 P3876",
"name":"Phytophthora taxon clade8a1 P3876",
"name_derivation":"No change to original label",
"rank":"species",
"parent":933772,
"sources":[
{"source_type":"The taxon is described in this study",
"source":null}
],
"comment":""
}
],
"study_id":"pg_2606",
"curator":{
"name":"Jim Allman",
"login":"jimallman",
"email":"[email protected]"
},
"new_ottids_required":2
} \
' --compressed
{
"description": "Updated document #additions-10000042-10000043",
"branch_name": "master",
"tag_to_ottid": {
"otu388728": 10000043,
"otu388719": 10000042
},
"resource_id": "additions-10000042-10000043",
"sha": "0a278cef003769afed0a44ba02b77d58a949f810",
"merge_needed": false,
"error": 0
}- taxon's parent alternatively specified using a tag instead of an OTT id:
"parent_tag": tag, - taxon flags:
"flags": [flag, ...],(optional) - synonyms. These could be done as a list at the top level of the response (sister to
"taxa"):
{"taxa": ...,
"synonyms": [{"name": string,
"type": string,
"taxon": OTT id,
"sources": [... as above ...]},
...],
...}
where, as for parent, one can write either "taxon": OTT id or "taxon_tag": tag.
The document stored in the repository is very similar to the request as described above, but with the following added:
-
date_created(per document) - a date (ISO 8601 string) set by the server; this helps to clarify any electronic sources (URLs) that are subject to change over time. -
ott_id(per taxon) - the new id assigned to the taxon, as an integer. -
id(per document) - the addition document id assigned to the document, e.g."additions-99000030-99000031"- this will be the same as the file name (not including trailing.json)
New method: /v3/taxonomy/process_additions (via POST)
Input: addition_document - string. The value is the text of an additions document.
Output: none. If there is a syntax error in the document, the method yields a 400 response.
The effect of this call is to make the new taxa visible in taxonomy and tnrs service calls. For example:
curl -X POST http://localhost:7476/db/data/ext/taxonomy_v3/graphdb/taxon_info \
-H "content-type:application/json" -d '{"ott_id": 99000030}'
{
"is_suppressed" : false,
"tax_sources" : [ "additions-99000030-99000031:99000030" ],
"unique_name" : "Test taxon 1",
"synonyms" : [ ],
"name" : "Test taxon 1",
"flags" : [ ],
"ott_id" : 99000030,
"rank" : "species"
}
If an ott_id is already assigned to a taxon, the addition request for that id/taxon is silently ignored. (Well maybe we should complain a little bit, but that's how the prototype works.)