Initialize Literature Annotation domain model

[pafonta]

Hello,

Here is the first iteration of the Literature Annotation domain model.

It's goal is to achieve #51. It is related to #43 and #49.

Created SHACL shapes are compliant with W3C Web Annotation recommendations.

Known current limitations:

1 - Annotation of facts are not modelled yet. These annotations do not have parameters.

2 - Literature references are not modelled yet. Reason: prioritization and some work has already been done on the subject in #43. TODO: Contribute to @apdavison proposition.

3 - Provenance is not modelled explicitly yet. Implicitly, it is:

• parameters are linked to an annotation (hasBody),
• annotations have SelectorTarget objects (hasTarget) which describe precisely where the information come from in the literature reference (hasSelector) and which literature reference it is (hasSource).
• agents are known and linked with each annotation (contribution.agent).

4 - The NeuroCurator field 'relationship' which describes more precisely on what the measure of a parameter is has not been modelled yet.

5 - rdf:value and dcterms:conformsTo has not been added to /contexts/neurosciencegraph/core/data/vx.x.x yet.

6 - schema:unitCode has been explicitly asked to be used instead of schema:unitText even though values corresponds to the later definition for now.

7 - Literature references without DOI or PMID are currently not modelled for the hasSource property.

Known tricky cases:

8 - Should TargetShape exists?

9 - Should BodyShape exists?

10 - There is no check at the SHACL level to declare invalid instances with a required property with an empty string as value.

[pafonta]

@apdavison
Here are:

• the list of terms BBP-xxxxxx used as parameter types.
• the workflow (IPython notebook) and the productivity toolkit (Python modules) I built to shape the original annotations into these SHACL shapes.

[pafonta]

v0.2.0 adds the oa prefix in the shapes and the prefixes in the property paths of the test data.

The goal was to have feedback first but it was needed to add this to make the data findable in Nexus.

[annakristinkaufmann]

should we replace this with a comment? Or add a comment to point out that we capture the oa:Annotation description in these shapes? Also, can "sh:class" be used outside property shapes? @MFSY

[pafonta]

I did it to so that oa:Annotation is in @typefor all instances using directly or indirectly AnnotationShape.

[annakristinkaufmann]

Maybe provide description in sentence case (i.e. annotation and target lower case) @MFSY

[annakristinkaufmann]

annotation and body lower case?

[annakristinkaufmann]

Is this shape necessary since there are no property shapes defined in it?

[pafonta]

I did it to make explicit the specialization by SelectorTargetShape as the latter is not the only kind of oa:hasTarget. Besides I did it because I wanted to have a shape for this property in the generic nsg:AnnotationShape.

[annakristinkaufmann]

Is this shape necessary since there are no property shapes defined in it?

[pafonta]

Same as nsg:TargetShape.

[annakristinkaufmann]

Instead of creating the ContributionShape here, the existing agent shape https://github.com/INCF/neuroshapes/blob/master/modules/core/src/main/resources/schemas/neurosciencegraph/core/agent/v0.1.0.json could be used as value of the node "nsg:contribution" in the property shapes of this schema

[pafonta]

I did it to enforce the fact that we want to have IRI of agents so that they come from a defined list, i.e. are not defined in this payload. Besides, the existing shapes for agents are not in a good 'shape':
https://github.com/BlueBrain/nexus-prov/blob/master/modules/prov/src/main/resources/schemas/nexus/provsh/agent/v1.0.0.json
https://github.com/BlueBrain/nexus-prov/blob/master/modules/prov/src/main/resources/schemas/nexus/prov/agent/v1.0.0.json

[annakristinkaufmann]

We might want to rename it to commons/selector/v0.2.0 to have it consistent with other schemas (i.e. schema name singular)?

[pafonta]

If I remember correctly, @MFSY said to use the plural form for the ones where I did this. To be confirmed.

[annakristinkaufmann]

What is the purpose of this property shape "Selector type"? Aren't you enforcing the type anyways through the "class" key in the individual selector shapes?

[pafonta]

Yes, through the sh:class constraint in the specialised SelectorShapes, an rdf:type is already required. However, I also wanted to have a generic SelectorShape reusable by others and a oa:Selector requires a rdf:type.

[annakristinkaufmann]

Maybe put minInclusive: 1 since the value can never be 0 (because the value is not included in the segment and the oa:start property needs to be less than the oa:end property)

[pafonta]

I agree. I have just done it because this is how it is described in https://www.w3.org/TR/annotation-vocab/#end.

[annakristinkaufmann]

Maybe add a description?

[pafonta]

I think I need to add it.

[annakristinkaufmann]

Longer term, this shape should probably re-use the TypedLabeledOntologyTerm schema (https://github.com/INCF/neuroshapes/blob/master/modules/commons/src/main/resources/schemas/neurosciencegraph/commons/typedlabeledontologyterm/v0.1.4.json) with an included OntologyTermShape for the quantity types

[pafonta]

Looks good. To be seen with @MFSY for the specific XyzOntologyTermShape.

[annakristinkaufmann]

We might want to rename it to core/selector/v0.2.0 to have it consistent with other schemas (i.e. schema name singular)?

[pafonta]

See comment for selectors above.

[annakristinkaufmann]

We might want to rename it to commons/variable/v0.2.0 to have it consistent with other schemas (i.e. schema name singular)?

[pafonta]

See comment made for selectors.

[annakristinkaufmann]

We might want to rename it to core/variable/v0.2.0 to have it consistent with other schemas (i.e. schema name singular)?

[pafonta]

See comment for selectors above.

[annakristinkaufmann]

As far as I understood, the Web Annotation Data Model (https://www.w3.org/TR/annotation-model/#bodies-and-targets) specifies, that the minCount for a target is 1 while there is no minCount on the body (see excerpts below). Should the property shape oa:hasTarget hence have a minCount of 1 and the minCount constraint on the oa:hasBody property shape below be removed?

The relationship between an Annotation and its Target. 
There must be 1 or more target relationships associated with an Annotation.

The relationship between an Annotation and its Body. 
There should be 1 or more body relationships associated with an Annotation but there may be 0.

[pafonta]

oa:hasTarget has already a sh:minCount of 1 because ParameterAnnotationShape is specializing AnnotationShape where there is this constraint.

oa:hasBody has sh:minCount of 1 because it is a ParameterAnnotationShape aso it needs parameters and I wanted to differentiate it from the annotations of facts which are not modeled yet and which have not parameters.

[annakristinkaufmann]

a unidimensional

[pafonta]

I will correct it.

[annakristinkaufmann]

More general comments:

• Could multiple target class declarations (e.g. as in https://github.com/INCF/neuroshapes/pull/192/files#diff-14ead9ee347ec1149f6facdca5ce0587) be an issue in the validation process?
• Should the general class hierarchy be captured in the schema structure?
• How to add MINDS-relevant properties?

[annakristinkaufmann]

Alternatively, AlgebraicValueShape could be modelled like the AgeShape in the subject schema:

 {
      "@id": "this:AgeShape",
      "@type": "sh:NodeShape",
      "property": [
        {
          "path": "nsg:period",
          "name": "Period",
          "in": [
            "Pre-natal",
            "Post-natal"
          ],
          "minCount": 1,
          "maxCount": 1
        },
        {
          "path": "schema:value",
          "name": "Age value",
          "node": "{{base}}/schemas/neurosciencegraph/commons/quantitativevalue/v0.1.0/shapes/QuantitativeValueShape",
          "minCount": 1,
          "maxCount": 1
        }
      ]
    }

by extending the QuantitativeValueShape with an nsg:statistic property shape (just like the AgeShape extends the QuantitativeValueShape with the nsg:period property shape).

[pafonta]

QuantitativeValueShape is broader. We might want to use it.
https://github.com/INCF/neuroshapes/blob/master/modules/commons/src/main/resources/schemas/neurosciencegraph/commons/quantitativevalue/v0.1.2.json