Initialize Literature Annotation domain model by pafonta · Pull Request #192 · INCF/neuroshapes

pafonta · 2018-09-25T15:55:50Z

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 · 2018-09-28T11:52:17Z

@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 · 2018-10-24T16:30:09Z

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 · 2018-11-06T16:08:54Z

+      "@id": "AnnotationShape",
+      "@type": "sh:NodeShape",
+      "nodeKind": "sh:BlankNodeOrIRI",
+      "class": "oa:Annotation",


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

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

annakristinkaufmann · 2018-11-06T16:16:16Z

+            {
+              "path": "oa:hasTarget",
+              "name": "Target",
+              "description": "The relationship between an Annotation and its Target.",


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

annakristinkaufmann · 2018-11-06T16:17:20Z

+            {
+              "path": "oa:hasBody",
+              "name": "Body",
+              "description": "The relationship between an Annotation and its Body.",


annotation and body lower case?

annakristinkaufmann · 2018-11-06T16:29:05Z

+      "@id": "TargetShape",
+      "@type": "sh:NodeShape",
+      "nodeKind": "sh:BlankNodeOrIRI"
+    },


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

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 · 2018-11-06T16:35:02Z

+      "@id": "BodyShape",
+      "@type": "sh:NodeShape",
+      "nodeKind": "sh:BlankNodeOrIRI"
+    },


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

Same as nsg:TargetShape.

annakristinkaufmann · 2018-11-06T16:45:54Z

+          "minCount": 1
+        }
+      ]
+    }


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

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 · 2018-11-06T16:52:23Z

+  "@context": [
+    "{{base}}/contexts/neurosciencegraph/core/schema/v0.2.0",
+    {
+      "@base": "{{base}}/schemas/neurosciencegraph/commons/selectors/v0.2.0/shapes/"


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

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

annakristinkaufmann · 2018-11-07T08:20:59Z

+          "description": "The class of the Selector.",
+          "minCount": 1,
+          "maxCount": 1
+        }


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?

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 · 2018-11-07T08:35:19Z

+              "name": "End offset",
+              "description": "The end position of the segment of text. The character is not included within the segment.",
+              "datatype": "xsd:integer",
+              "minInclusive": 0,


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)

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

annakristinkaufmann · 2018-11-07T09:12:11Z

+              "maxCount": 1
+            },
+            {
+              "path": "dcterms:conformsTo",


Maybe add a description?

I think I need to add it.

annakristinkaufmann · 2018-11-07T09:52:05Z

+          "name": "Quantity type",
+          "description": "The type of the measured quantity represented by the variable.",
+          "minCount": 1,
+          "maxCount": 1


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

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

annakristinkaufmann · 2018-11-07T10:13:13Z

+  "@context": [
+    "{{base}}/contexts/neurosciencegraph/core/schema/v0.2.0",
+    {
+      "@base": "{{base}}/schemas/neurosciencegraph/core/selectors/v0.2.0/shapes/"


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

See comment for selectors above.

annakristinkaufmann · 2018-11-07T10:13:39Z

+  "@context": [
+    "{{base}}/contexts/neurosciencegraph/core/schema/v0.2.0",
+    {
+      "@base": "{{base}}/schemas/neurosciencegraph/commons/variables/v0.2.0/shapes/"


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

See comment made for selectors.

annakristinkaufmann · 2018-11-07T10:13:57Z

+  "@context": [
+    "{{base}}/contexts/neurosciencegraph/core/schema/v0.2.0",
+    {
+      "@base": "{{base}}/schemas/neurosciencegraph/core/variables/v0.2.0/shapes/"


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

See comment for selectors above.

annakristinkaufmann · 2018-11-07T12:34:19Z

+                  "class": "nsg:AreaTarget"
+                }
+              ],
+              "maxCount": 1


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.

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 · 2018-11-07T12:37:10Z

+      "@type": "sh:NodeShape",
+      "nodeKind": "sh:BlankNodeOrIRI",
+      "targetClass": "nsg:PointValueParameter",
+      "comment": "Parameter shape for the value(s) of an unidimensional variable (i.e., not establishing a relationship between a dependant and an independent variable).",


a unidimensional

I will correct it.

annakristinkaufmann · 2018-11-07T13:54:51Z

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 · 2018-11-07T16:01:17Z

+          ]
+        }
+      ]
+    },


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).

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

- Restricted the domain to annotating entities based on web annotation data model - Used nsg namespace instead of oa for hasTarget, hasBody, hasSource,hasSelector, Annotation - Removed targetClass assertion from all schemas in commons domain - Added a seeAlso links towards the web annotation recommendation - Used schema:value instead of nsg:text and rdf:value - Renamed IndexSelectorShape to DocumentIndexSelectorShape - Directly use DocumentIndexSelectorShape instead of FigureSelectorShape - Removed FigureSelectorShape because it does not add anything new on top of DocumentIndexSelectorShape - Removed EquationSelectorShape - Renamed AreaSelectorShape to DocumentAreaSelectorShape - Renamed selectors schema with annotationselector - Removed @base and use this instead - Removed the different *TargetShape in the core domain - Removed core/EquationTargetShape - Removed selector schema from core domain

Initialize Literature Annotation domain model

e25ff1f

pafonta added literature-annotation literature-annotation-spec labels Sep 25, 2018

pafonta self-assigned this Sep 25, 2018

pafonta requested review from MFSY, annakristinkaufmann and apdavison September 25, 2018 15:55

ghost added the review label Sep 25, 2018

MFSY added the spec label Oct 6, 2018

Literature Annotation domain model v.0.2.0

31ed2c2

annakristinkaufmann reviewed Nov 6, 2018

View reviewed changes

annakristinkaufmann reviewed Nov 7, 2018

View reviewed changes

Merge branch 'master' into prov_literature_annotation

b905766

ghost assigned MFSY Nov 26, 2018

MFSY and others added 5 commits November 26, 2018 21:47

Update build.sbt

2a14064

Initialize Literature Annotation domain model

438b1dc

Removed literatureannotation domain

5ed1533

Removed variables and parameter schemas

c5a7a43

annakristinkaufmann approved these changes Nov 27, 2018

View reviewed changes

Merge branch 'master' into prov_literature_annotation

9b88e98

MFSY merged commit a2ef586 into master Nov 27, 2018

ghost removed the review label Nov 27, 2018

Uh oh!

Conversation

pafonta commented Sep 25, 2018

Uh oh!

pafonta commented Sep 28, 2018

Uh oh!

pafonta commented Oct 24, 2018

Uh oh!

annakristinkaufmann Nov 6, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

annakristinkaufmann Nov 6, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

annakristinkaufmann Nov 6, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

annakristinkaufmann Nov 7, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

annakristinkaufmann commented Nov 7, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

annakristinkaufmann Nov 6, 2018 •

edited

Loading

annakristinkaufmann Nov 6, 2018 •

edited

Loading

annakristinkaufmann Nov 6, 2018 •

edited

Loading

annakristinkaufmann Nov 7, 2018 •

edited

Loading