Namespace/Annotation field and autocomplete workflow requirements

[wshayes]

Evidence json:

• BELMgr needs human readable content for Annotation field (e.g. Type=Species Value=Human or Homo sapiens) to fill out edit form

Annotation/Namespace search results:

• Human and machine formats for Namespace/AnnotationType and ID/Label in search results
• match text (already available)
• Namespace results - information on _links.item[].type - are they equivalents or orthologs or ...?

Having to follow the _links.collection to get the collection name and prefix would necessitate many additional http queries for a single autocomplete request impacting the user experience

[abargnesi]

Regarding the evidence resource the annotations are present under the experiment_context property. This gist shows an experiment_context object with name/value. This response should also have conveyed the annotation's URI so I'll investigate why it does not.

Would the following experiment_context object be sufficient? This will allow you to present human-readable values and the identifier you can use on save.

{
    "experiment_context": [
        {
            "name": "Ncbi Taxonomy",
            "value": "Homo sapiens",
            "_links": {
                "self": {
                    "type": "annotation_value",
                    "href": "http://next.belframework.org/api/annotations/ncbi-taxonomy/values/9606"
                }
            }
        }
    ]
}

---

Adding the namespace and annotation resource to the respective value resource is a great idea, since they will frequently be used together. What about extending _annotationvalue and _namespacevalue resources to include annotation and namespace respectively? These will be included by default.

Example for Ncbi Taxonomy / Homo sapiens:

{
    "annotation_value": {
        "type": "SpeciesAnnotationConcept",
        "identifier": "9606",
        "name": "Homo sapiens",
        "annotation": {
            "name": "Ncbi Taxonomy",
            "prefix": "taxon",
            "domain": "species"
        },
        "_links": {
            "self": {
                "type": "annotation_value",
                "href": "http://next.belframework.org/api/annotations/ncbi-taxonomy/values/9606"
            },
            "collection": {
                "type": "annotation",
                "href": "http://next.belframework.org/api/annotations/ncbi-taxonomy"
            }
        }
    }
}

---

Regarding the _namespace_valuecollection links for a _namespacevalue resource I agree we should change these. Maybe something descriptive like _namespace_valueequivalents and _namespace_valueorthologs?

[wshayes]

Those example JSON responses look good and fit the need well. Using 'namespace_value_equivalents', etc to indicate the type of item works well.

What would be saved in the experiment_context of the BEL Evidence? Does the first JSON example get round-tripped back to the POST/PUT for that Evidence? maybe with a minimal form of

            "_links": {
                "self": {
                    "type": "annotation_value",
                    "href": "http://next.belframework.org/api/annotations/ncbi-taxonomy/values/9606"
                }
            }

[abargnesi]

The documentation for how _experimentcontext is mapped is lacking so I'll make a note.

The first example can be round-tripped using POST/PUT on that evidence link.

Each object in the _experimentcontext can have either name/value properties or a uri property. The evidence.schema.json describes the expected schema.

[wshayes]

Perfect - thanks!

[abargnesi]

On second thought the original evidence's Species annotation would not have a uri because Species does not map to the Ncbi Taxonomy.

However this evidence does have annotations with uri properties when they map correctly:

...
"experiment_context": [
    {
        "name": "Ncbi Taxonomy",
        "value": "Homo sapiens",
        "uri": "http://next.belframework.org/api/annotations/taxon/values/9606"
    },
    {
        "name": "CellularStructures",
        "value": "Cell Nucleus"
    },
    {
        "name": "Mesh Anatomy",
        "value": "Muscle, Smooth, Vascular",
        "uri": "http://next.belframework.org/api/annotations/mesha/values/D009131"
    }
],
...

[wshayes]

Very happy to shift to the NCBI Taxonomy and drop Species - this gains us the identifiers.org RDF mapping as well.

[abargnesi]

Deployed enhancement to next.belframework.org to address OpenBEL/openbel-server#38.

How do they look?

Affected routes with example:

• Single value
  • http://next.belframework.org/api/annotations/do/values/silicosis
• Value search across all annotations
  • http://next.belframework.org/api/annotations/values?filter={%22category%22:%22fts%22,%22name%22:%22search%22,%22value%22:%22lung%22}
• Value search within an annotation
  • http://next.belframework.org/api/annotations/do/values?filter={%22category%22:%22fts%22,%22name%22:%22search%22,%22value%22:%22lung%22}

[wshayes]

These look very good. What URI should I use for the Evidence.json? The self href? Thanks!

[abargnesi]

Yes. The self link with type annotation_value.

[abargnesi]

Would you mind if I moved this issue to the openbel-server project?

[wshayes]

Nope and it's ready to close as far as I'm concerned.

[abargnesi]

This issue was moved to OpenBEL/openbel-server#90

[abargnesi]

Wow, +1 for https://github-issue-mover.appspot.com/.