Merge pull request #362 from sierra-moxon/more_qualifier_examples

More complicated qualifier examples + rules documentation
NCATSTranslator · Aug 16, 2022 · 7520ac5 · 7520ac5
2 parents 07a4a1a + 293fcbe
commit 7520ac5
Show file tree

Hide file tree

Showing 10 changed files with 653 additions and 9 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -1,7 +1,7 @@
 dist: xenial
 language: python
 python:
-  - "3.7"
+  - "3.9"
 install:
   - pip install tox
 script: 

diff --git a/examples/Message/causes_predicate_vs_qualifier.json b/examples/Message/causes_predicate_vs_qualifier.json
@@ -0,0 +1,110 @@
+{
+  "query_graph": {
+    "nodes": {
+      "n0": {
+        "categories": [
+          "biolink:ChemicalEntity"
+        ]
+      },
+      "n1": {
+        "categories": [
+          "biolink:GeneOrGeneProduct"
+        ],
+        "ids": [
+          "HGNC:3467"
+        ]
+      }
+    },
+    "edges": {
+      "e01": {
+        "subject": "n0",
+        "object": "n1",
+        "predicates": [
+          "biolink:affects"
+        ],
+        "qualifier_constraints": [
+          {
+            "qualifier_set": [
+              {
+                "qualifier_type_id": "biolink:object_aspect_qualifier",
+                "qualifier_value": "activity"
+              },
+              {
+                "qualifier_type_id": "biolink:object_modifier_qualifier",
+                "qualifier_value": "increased"
+              },
+              {
+                "qualifier_type_id": "biolink:qualified_predicate",
+                "qualifier_value": "biolink:causes"
+              }
+            ]
+          }
+        ]
+      }
+    }
+  },
+  "knowledge_graph": {
+    "nodes": {
+      "PUBCHEM.COMPOUND:6623": {
+        "categories": [
+          "biolink:ChemicalEntity"
+        ],
+        "name": "Bisphenol A"
+      },
+      "HGNC:3467": {
+        "categories": [
+          "biolink:GeneOrGeneProduct"
+        ],
+        "name": "EGRB2"
+      }
+    },
+    "edges": {
+      "x17770": {
+        "predicate": "biolink:affects",
+        "subject": "PUBCHEM.COMPOUND:6623",
+        "object": "HGNC:3467",
+        "qualifiers": [
+          {
+            "qualifier_type_id": "biolink:object_aspect_qualifier",
+            "qualifier_value": "activity"
+          },
+          {
+            "qualifier_type_id": "biolink:object_modifier_qualifier",
+            "qualifier_value": "increased"
+          },
+          {
+            "qualifier_type_id": "biolink:qualified_predicate",
+            "qualifier_value": "causes"
+          },
+          {
+            "qualifier_type_id": "biolink:mechanism_qualifier",
+            "qualifier_value": "binding"
+          }
+        ]
+      }
+    },
+    "results": [
+      {
+        "node_bindings": {
+          "n0": [
+            {
+              "id": "PUBCHEM.COMPOUND:6623"
+            }
+          ],
+          "n1": [
+            {
+              "id": "HGNC:3467"
+            }
+          ]
+        },
+        "edge_bindings": {
+          "e01": [
+            {
+              "id": "x17770"
+            }
+          ]
+        }
+      }
+    ]
+  }
+}
diff --git a/examples/Message/complex_gocam_qualifiers.json b/examples/Message/complex_gocam_qualifiers.json
@@ -0,0 +1,133 @@
+{
+  "query_graph": {
+    "nodes": {
+      "n0": {
+        "categories": [
+          "biolink:GeneOrGeneProduct"
+        ],
+        "ids": [
+          "FB:FBgn0003205"
+        ]
+      },
+      "n1": {
+        "categories": [
+          "biolink:GeneOrGeneProduct"
+        ],
+        "ids": [
+          "FB:FBgn0003079"
+        ]
+      }
+    },
+    "edges": {
+      "e01": {
+        "subject": "n0",
+        "object": "n1",
+        "predicates": [
+          "biolink:regulates"
+        ],
+        "qualifier_constraints": [
+          {
+            "qualifier_set": [
+              {
+                "qualifier_type_id": "biolink:subject_aspect_qualifier",
+                "qualifier_value": "GO:0043539"
+              },
+              {
+                "qualifier_type_id": "biolink:subject_context_qualifier",
+                "qualifier_value": "GO:0005886"
+              },
+              {
+                "qualifier_type_id": "biolink:object_aspect_qualifier",
+                "qualifier_value": "GO:0004708"
+              },
+              {
+                "qualifier_type_id": "biolink:object_context_qualifier",
+                "qualifier_value": "GO:0005737"
+              },
+              {
+                "qualifier_type_id": "biolink:object_direction_qualifier",
+                "qualifier_value": "increased"
+              },
+              {
+                "qualifier_type_id": "biolink:pathway_context_qualifier",
+                "qualifier_value": "EGFR pathway"
+              }
+            ]
+          }
+        ]
+      }
+    }
+  },
+  "knowledge_graph": {
+    "nodes": {
+      "FB:FBgn0003205": {
+        "categories": [
+          "biolink:GeneOrGeneProduct"
+        ],
+        "name": "Ras85D"
+      },
+      "FB:FBgn0003079": {
+        "categories": [
+          "biolink:GeneOrGeneProduct"
+        ],
+        "name": "Raf"
+      }
+    },
+    "edges": {
+      "x17770": {
+        "predicate": "biolink:regulates",
+        "subject": "FB:FBgn0003205",
+        "object": "FB:FBgn0003079",
+        "qualifiers": [
+          {
+            "qualifier_type_id": "biolink:subject_aspect_qualifier",
+            "qualifier_value": "GO:0043539"
+          },
+          {
+            "qualifier_type_id": "biolink:subject_context_qualifier",
+            "qualifier_value": "GO:0005886"
+          },
+          {
+            "qualifier_type_id": "biolink:object_aspect_qualifier",
+            "qualifier_value": "GO:0004708"
+          },
+          {
+            "qualifier_type_id": "biolink:object_context_qualifier",
+            "qualifier_value": "GO:0005737"
+          },
+          {
+            "qualifier_type_id": "biolink:object_direction_qualifier",
+            "qualifier_value": "increased"
+          },
+          {
+            "qualifier_type_id": "biolink:pathway_context_qualifier",
+            "qualifier_value": "EGFR pathway"
+          }
+        ]
+      }
+    }
+  },
+  "results": [
+    {
+      "node_bindings": {
+        "n0": [
+          {
+            "id": "FB:FBgn0003205"
+          }
+        ],
+        "n1": [
+          {
+            "id": "FB:FBgn0003079"
+          }
+        ]
+      },
+      "edge_bindings": {
+        "e01": [
+          {
+            "id": "x17770"
+          }
+        ]
+      }
+    }
+  ]
+}
diff --git a/examples/Message/examples_and_rules.md b/examples/Message/examples_and_rules.md
@@ -0,0 +1,121 @@
+## Biolink Qualifiers Examples
+
+### Object qualifiers
+_“Bisphenol A results in decreased degradation of ESR1 protein”_
+
+```
+subject: Bisphenol A
+predicate: affects 
+qualified_predicate: causes
+object: ESR1
+object_aspect_qualifier: degradation
+object_direction_qualifier: decreased
+```
+* [object_qualifiers.json](object_qualifiers.json)
+
+Note: the predicate chosen should reflect the relationship between the subject and the object, and is not required
+to be "affects".  For example, below we see a statement where the relationship between Bisphenol A and ESR1 is
+not causal. 
+
+_"Bisphenol A is associated with decreased degradation of ESR1 protein"_
+
+```
+subject: Bisphenol A
+predicate: associated_with
+object: ESR1
+object_aspect_qualifier: degradation
+object_direction_qualifier: decreased
+```
+
+
+### Subject and object qualifiers
+_“Methionine deficiency results in increased expression of ADRB2”_
+
+```
+subject: Methionine
+subject_aspect_qualifier: abundance
+subject_direction_qualifier: decreased
+predicate: affects 
+qualified_predicate: causes
+object: ADRB2 
+object_aspect_qualifier: expression
+object_direction_qualifier: increased
+```
+
+* [subject_and_object_qualifiers.json](subject_and_object_qualifiers.json)
+
+_"Fenofibrate is an agonist of PPARA protein"_
+
+```
+subject: Fenofibrate
+predicate: affects             
+qualified_predicate: causes
+object: PPARA protein
+object_aspect_qualifier: activity
+object_direction_qualifier: increased
+mechanism_qualifier: agonism
+```
+
+### Complex statement
+
+_"The protein ser/thr kinase activator activity of Ras85D in the plasma membrane directly positively regulates MAPKKK 
+activity of Raf in the cytoplasm within the EGFR signaling pathway"_
+
+```
+subject: Dmel Ras85D
+subject_aspect_qualifier: protein ser/thr kinase activator activity
+subject_context_qualifier: plasma membrane
+predicate: regulates   
+qualified_predicate: causes
+object: Dmel Raf
+object_aspect_qualifier: MAPKKK activity
+object_context_qualifier: cytoplasm
+object_direction_qualifier: increased
+pathway_context_qualifier: EGFR pathway
+```
+
+* [complex_gocam_qualifiers.json](complex_gocam_qualifiers.json)
+
+
+### Querying for "_affects transport of_ *OR* _affects localization of_" with qualifiers instead of predicates.
+
+_"What chemicals affect either the localization or the transport of ADRB2"_
+
+* [localization_or_transport.json](localization_or_transport.json)
+
+
+### When to use predicate=causes vs. qualified_predicate=causes
+
+_"What chemicals cause increased activity of PPARA protein"_
+
+* [causes_predicate_vs_qualifier.json](causes_predicate_vs_qualifier.json)
+
+Note: in this example we need to convert the user's request for "causes" (predicate) to an "affects" predicate 
+with a "causes" qualified_predicate.
+
+### Qualifier Rules
+
+These rules can not be enforced in the schema for TRAPI, but should be implemented in a validation layer.
+
+1. __general rules__
+   1. There MUST be only one of each type of qualifier in any edges.qualifier_constraints.qualifier_set
+      1. There MUST be only one qualified_predicate for each set of qualifiers in a QualifierConstraint. 
+      2. qualified_predicate is an optional qualifier. (see [localization_or_transport.json](localization_or_transport.json))
+         1. Both the qualified_predicate and the predicate edge properties SHOULD be queried when a predicate is provided. 
+         see [causes_predicate_vs_qualifier.json](causes_predicate_vs_qualifier.json)
+   2. If a KP receives non-empty QEdge.qualifier_constraints, it MUST only return edges that satisfy the entire set of 
+   qualifier_constraints. If a KP does not yet support QEdge.qualifier_constraints, it MUST return an empty response 
+   because no matches are found.
+      1. If a knowledge statement contains more qualifiers or differently typed qualifiers than those specified in
+      edges.qualifier_constraints.qualifier_set in addition to the entire set of qualifier_constraints, the knowledge 
+      statement MAY also be returned.
+   3. Qualifier constraints should be treated as "or" constraints.
+2. __qualifier_value__  
+   1. is constrained by either: an enumeration in biolink, or an ontology term.  
+      1. When an ontology term is used, the assumption is that annotations that use this term or any of its children 
+      should be returned.
+      2. When an enumerated value is used, the assumption is that annotations that use this enumerated value or any 
+      of its children should be returned. 
+         1. For example, if a query asks for "biolink:object_aspect_qualifier" = "abundance", 
+         then, aspects matching any child of "abundance" should also be returned (if the other qualifiers used in this
+         query are also satisfied).