Add 0:0 special cardinality value. (#480)

Resolves [#477]

This PR adds a new cardinality value of `0:0`, to be used for mapping
records where both the `subject_id` and the `object_id` are
`sssom:NoTermFound`. Such records are allowed and may be used to
represent the fact that there is no overlap between a subject vocabulary
and an object vocabulary.

The spec is updated to explain how mappings involved `sssom:NoTermFound`
should be handled when computing cardinality values.

We also try to explain a bit more what the different cardinality values
mean exactly, and provide two examples:

* one that illustrates all possible cardinality values between real
mappings (1:1, 1:n, n:1, n:n);
* one that illustrates the special cases where the subject_id and/or the
object_id is sssom:NoTermFound.

closes #477

---------

Co-authored-by: Nico Matentzoglu <[email protected]>
Co-authored-by: Emily Hartley <[email protected]>

Author: 3 people

CHANGELOG.md

@@ -14,6 +14,7 @@
 - Change all URI-typed slots to clarify that they expect _non-relative_ URIs as values ([issue](https://github.com/mapping-commons/sssom/issues/448)).
 - Add `curation_rule` and `curation_rule_text` to the `MappingSet` class and made propagatable ([issue](https://github.com/mapping-commons/sssom/issues/464)).
 - Add `cardinality_scope` slot ([issue](https://github.com/mapping-commons/sssom/issues/467)).
+- Add new value `0:0` to the `mapping_cardinality_enum` ([issue](https://github.com/mapping-commons/sssom/issues/477)).
 
 ## SSSOM version 1.0.0
 

examples/schema/cardinality-with-unmapped-entities.sssom.tsv

@@ -0,0 +1,11 @@
+#curie_map:
+#  OBJ: https://example.org/object/
+#  SRC: https://example.org/sources/
+#  SUBJ: https://example.org/subject/
+#mapping_set_id: https://example.org/sets/cardinality-with-unmapped-entities
+#license: https://creativecommons.org/licenses/by/4.0/
+subject_id	predicate_id	object_id	mapping_justification	subject_source	object_source	mapping_cardinality	comment
+SUBJ:0001	skos:exactMatch	sssom:NoTermFound	semapv:ManualMappingCuration	SRC:A	SRC:B	1:0	S1 in vocabulary A has no exact match in vocabulary B
+SUBJ:0001	skos:closeMatch	OBJ:0001	semapv:ManualMappingCuration	SRC:A	SRC:B	1:1	S1 mapped only to O1, O1 mapped only to S1 -- the record involving sssom:NoTermFound does not count, as it is an absence of match rather than an actual mapping
+sssom:NoTermFound	skos:exactMatch	OBJ:0002	semapv:ManualMappingCuration	SRC:C	SRC:D	0:1	O2 in vocabulary D has no exact match in vocabulary C
+sssom:NoTermFound	skos:exactMatch	sssom:NoTermFound	semapv:ManualMappingCuration	SRC:E	SRC:F	0:0	No exact match between any term from vocabulary E and any term for vocabulary F (in other words, the two vocabularies are completely disjoint, at least as far as exact matches are considered)

examples/schema/cardinality.sssom.tsv

@@ -0,0 +1,15 @@
+#curie_map:
+#  OBJ: https://example.org/object/
+#  SUBJ: https://example.org/subject/
+#mapping_set_id: https://example.org/sets/cardinality
+#license: https://creativecommons.org/licenses/by/4.0/
+subject_id	predicate_id	object_id	mapping_justification	mapping_cardinality	comment
+SUBJ:0001	skos:exactMatch	OBJ:0001	semapv:LexicalMatching	1:1	S1 and O1 only mapped to each other
+SUBJ:0001	skos:exactMatch	OBJ:0001	semapv:MappingReview	1:1	S1 and O1 only mapped to each other
+SUBJ:0002	skos:exactMatch	OBJ:0002	semapv:LexicalMatching	1:n	S2 mapped to both O2 and O3, O2 mapped only to S2
+SUBJ:0002	skos:exactMatch	OBJ:0003	semapv:LexicalMatching	1:n	S2 mapped to both O2 and O3, O3 mapped only to S2
+SUBJ:0003	skos:exactMatch	OBJ:0004	semapv:LexicalMatching	n:1	S3 and S4 both mapped to only O4
+SUBJ:0004	skos:exactMatch	OBJ:0004	semapv:LexicalMatching	n:1	S3 and S4 both mapped to only O4
+SUBJ:0005	skos:exactMatch	OBJ:0005	semapv:LexicalMatching	n:n	S5 mapped to O5 and O6, O5 mapped to S5 and S6
+SUBJ:0005	skos:exactMatch	OBJ:0006	semapv:LexicalMatching	1:n	S5 mapped to O5 and O6, O6 mapped only to S5
+SUBJ:0006	skos:exactMatch	OBJ:0005	semapv:LexicalMatching	n:1	S6 mapped only to O5, O5 mapped to both S5 and S6

src/docs/spec-model.md

@@ -128,7 +128,7 @@ The `sssom:NoTermFound` value MUST NOT be used in any other slot than `subject_i
 
 The meaning of the NOT predicate modifier in a mapping that refers to `sssom:NoTermFound` is unspecified.
 
-When computing cardinality values (to fill the `mapping_cardinality` slot), mappings that refer to `sssom:NoTermFound` MUST be ignored.
+When computing cardinality values (to fill the `mapping_cardinality` slot): (1) a mapping record with a `object_id` (respectively `subject_id`) of `sssom:NoTermFound` MUST be assigned a cardinality value of `1:0` (respectively `0:1`), regardless of any other record; (2) a mapping record with both the `subject_id` and the `object_id` set to `sssom:NoTermFound` MUST be assigned a cardinality value of `0:0`, regardless of any other record; (3) such records MUST be ignored when computing the cardinality of other records.
 
 
 ## Mapping cardinality and cardinality scope
@@ -288,3 +288,4 @@ Not all changes can be annotated thusly in the LinkML model, though. For changes
 * The type of the `see_also` slot has been changed to `sssom:NonRelativeURI`. When parsing a SSSOM 1.0 set, implementations SHOULD accept arbitrary string values in that slot.
 * All slots that were typed as `xsd:anyURI` have been re-typed as `sssom:NonRelativeURI`. When parsing a SSSOM 1.0 set, implementations SHOULD accept relative URI values in those slots.
 * The `curation_rule` and `curation_rule_text` slots which previously only existed on the `Mapping` class, have been added to the `MappingSet` class. Both slots have now been typed [propagatable](#propagation-of-mapping-set-slots).
+* A new value `0:0` has been added to the `mapping_cardinality_enum`.

src/sssom_schema/schema/sssom_schema.yaml

@@ -76,12 +76,30 @@ enums:
         meaning: sssom:NegatedPredicate
   mapping_cardinality_enum:
     permissible_values:
-      "1:1": One-to-one mapping
-      "1:n": One-to-many mapping
-      "n:1": Many-to-one mapping
-      "1:0": One-to-none mapping
-      "0:1": None-to-one mapping
-      "n:n": Many-to-many mapping
+      "1:1":
+        description: Indicates the mapping record is about a one-to-one mapping, that is,
+          the subject and the object are only mapped to each other, exclusive of any
+          other subject or object.
+      "1:n":
+        description: Indicates the mapping record is about a one-to-many mapping, that
+          is, the same subject is mapped to several different objects.
+      "n:1":
+        description: Indicates the mapping record is about a many-to-one mapping, that
+          is, several different subjects are mapped to the same object.
+      "n:n":
+        description: Indicates the mapping record is about a many-to-many mapping, that
+          is, the subject is mapped to several different objects and the object is
+          mapped to several different subjects.
+      "1:0":
+        description: Indicates that the subject has no match in the object vocabulary.
+          This value MUST only be used when the object_id is sssom:NoTermFound.
+      "0:1":
+        description: Indicates that the object has no match in the subject vocabulary.
+          This value MUST only be used when the subject_id is sssom:NoTermFound.
+      "0:0":
+        description: Indicates that there is no match between the subject vocabulary
+          and the object vocabulary. This value MUST only be used when both the
+          subject_id and the object_id are sssom:NoTermFound.
 
 types:
  EntityReference:
@@ -574,17 +592,27 @@ slots:
       - value: MONDO_MAPPINGS:mondo_exactmatch_ncit.sssom.tsv
         description: A reference to the mapping set that originally contained this mapping.
   mapping_cardinality:
-    description: A string indicating whether this mapping is from a 1:1 (the subject_id
-      maps to a single object_id), 1:n (the subject maps to more than one object_id), 
-      n:1, 1:0, 0:1 or n:n group. Note that this is a convenience field that should be derivable 
-      from the mapping set.
+    description: A value indicating whether the subject (respectively object) of this
+      mapping record is present in other records involving a different object
+      (respectively subject), within the subset of records defined by the
+      cardinality_scope slot (or within the entire mapping set if cardinality_scope
+      is undefined).
+      Note that this is a convenience field, whose values can always be derived from
+      the mapping set.
     range: mapping_cardinality_enum
     examples:
       - value: "1:1"
-        description: A one-to-one mapping.
+        description: A one-to-one mapping. There are no other records in which the same
+          subject is mapped to a different object, and no other records in which the
+          same object is mapped to a different subject.
       - value: "1:n"
-        description: A one-to-many mapping.
+        description: A one-to-many mapping. There are other records in which the same
+          subject is mapped to at least one different object than the object present in
+          this record; there are no other records in which the object is mapped to a
+          different subject.
     see_also:
+      - https://github.com/mapping-commons/sssom/blob/master/examples/schema/cardinality.sssom.tsv
+      - https://github.com/mapping-commons/sssom/blob/master/examples/schema/cardinality-with-unmapped-entities.sssom.tsv
       - https://github.com/mapping-commons/sssom/blob/master/examples/schema/cardinality-scope-empty.sssom.tsv
   cardinality_scope:
     description: A list of mapping slots that define the scope for the value found