discuss TRAPI 1.3 constraints: 3 types

[colleenXu]

This is for brainstorming these "constraint"/post-query filtering behaviors (we can make other issues once we have a concrete idea of the requirements and logic/behavior we want).

The stuff below was previously in #450 posts but has been moved here and edited.

---

Issues:

• This is a BIG set of tasks, lots of parts (not quite clear how it's all going to work or work together yet...)
• The logic in the TRAPI 1.2/1.3 specs is pretty complex (aka hard implementation?). See old notes https://github.com/biothings/BioThings_Explorer_TRAPI/issues/380 and
• Other deadlines / requirements are related:
  • TRAPI 1.3 renamed/introduced new stuff - deployment is underway
  • Biolink-model 3.0 is released but the timeline is unclear (depends on when UI team can support qualifiers?).
    • right now, we can't have biolink-model 3.0 on some BTE instances and not others. Because the important part of biolink-model 3.0 stuff is in the x-bte annotation...(and code is needed in BTE to ingest it)
    • I think the process of adding qualifiers to operations (for those that it would make sense for) could be incremental operations that could use qualifiers Right now, moving to biolink 3.0 is "breaking" (x-bte annotation isn't kept separate for different BTE instances....and I'm not sure how that would work without separate temporary registrations...)

---

QNode.constraints

• Previous limited work is likely broken right now.
• Related to this effort by me
• Current documentation: this and QEdge.attribute_constraints have values that are arrays, with items that follow the AttributeConstraint schema in TRAPI 1.3. There's also an implementation rule here (EDITED because they pushed a fix to the documentation).

QEdge.attribute_constraints

• allowlist/denylist behavior (doing queries that exclude certain knowledge sources) is a special case of this. Andrew said that this is useful / prioritized.
  • TRAPI 1.3 implementation rules has some info / an example of this
  • Some prior brainstorming on this :
    • Note that this uses the concept of "knowledge source", not KP infores IDs...this is also meant to be more general than what biolink-model has (aggregator_knowledge_source / primary_knowledge_source / etc....)
    • For non-TRAPI KPs, we can use the "source" part of each x-bte operation (is this on their MetaEdges?) and remove operations where that "source" value (which is an infores) matches the value of this constraint-thing. Note that not all x-bte operations have "source" (sometimes Colleen didn't include it)
    • For TRAPI KPs, we can pass the QEdge.attribute_constraints along, and hope they handle it gracefully / correctly
    • Note that this may not completely cut out a "source". Sometimes, we have operations that have multiple underlying "sources" (think of disgenet pulling from a bunch of diff stuff). It would involve custom (per-operation basis? >.<) filtering post-sub-querying to handle this

QEdge.qualifier_constraints

• can only be tested / implemented WITH OR AFTER the move to biolink-model 3.0 (use of qualifiers)?
• [EDIT] still being discussed by TRAPI team? https://github.com/NCATSTranslator/ReasonerAPI/issues/328
• can only be used in certain situations? read the description very carefully and the implementation rules
• uses different logic than the other two. See current documentation: it's an array of items that follow the QualifierConstraint and the Qualifier schemas
• The original PR may be helpful but look at the latest code in the 1.3 branch too
• TRAPI team told us that these were supposed to only be in QEdges, not QNodes.

[colleenXu]

These are quick example queries I wrote to test some TRAPI 1.3 code. I want to do some more thinking / writing before using these as examples / showing these to others in Translator.

(for example I think the QEdge.qualifier_constraints example needs valid biolink-model 3.0 predicates...)

QNode constraints (chem must be above stage 1 clinical trial)

trying to find chem that regulate the gene's expression ``` { "message": { "query_graph": { "nodes": { "creativeQuerySubject": { "categories":["biolink:ChemicalEntity"], "constraints": [{ "id": "biolink:drug_regulatory_status_world_wide", "name": "clinical trial level", "operator": ">", "value": 1 }] }, "nA": { "categories":["biolink:DiseaseOrPhenotypicFeature"], "is_set": true }, "creativeQueryObject": { "ids":["MONDO:0005147"], "categories":["biolink:DiseaseOrPhenotypicFeature"], "name": "type 1 dm" } }, "edges": { "eA": { "subject": "creativeQuerySubject", "object": "nA", "predicates": ["biolink:treats"] }, "eB": { "subject": "nA", "object": "creativeQueryObject", "predicates": ["biolink:subclass_of"] } } } } } ```

QEdge attribute_constraints (not semmeddb as knowledge source)

trying not to use semmeddb on one of the edges. ``` { "message": { "query_graph": { "nodes": { "creativeQuerySubject": { "categories":["biolink:ChemicalEntity"] }, "nA": { "categories":["biolink:DiseaseOrPhenotypicFeature"], "is_set": true }, "creativeQueryObject": { "ids":["MONDO:0005147"], "categories":["biolink:DiseaseOrPhenotypicFeature"], "name": "type 1 dm" } }, "edges": { "eA": { "subject": "creativeQuerySubject", "object": "nA", "predicates": ["biolink:treats"], "attribute_constraints": [{ "id": "biolink:knowledge_source", "name": "knowledge source", "not": true, "operator": "==", "value": "infores:semmeddb" }] }, "eB": { "subject": "nA", "object": "creativeQueryObject", "predicates": ["biolink:subclass_of"] } } } } } ```

QEdge qualifier_constraints (Gene expression)

trying to find chem that regulate the gene's expression ``` { "message": { "query_graph": { "nodes": { "creativeQuerySubject": { "categories":["biolink:ChemicalEntity"] }, "nA": { "categories":["biolink:Gene"], "is_set": true }, "creativeQueryObject": { "ids":["MONDO:0007035"], "categories":["biolink:DiseaseOrPhenotypicFeature"], "name": "acanth" } }, "edges": { "eA": { "subject": "creativeQuerySubject", "object": "nA", "predicates": ["biolink:regulates"], "qualifier_constraints": [{ "qualifier_set": [ { "qualifier_type_id": "object_aspect_qualifier", "qualifier_value": "expression" }] }] }, "eB": { "subject": "nA", "object": "creativeQueryObject", "predicates": ["biolink:causes"] } } } } } ```

[colleenXu]

Note that PRs-merging / discussion is still happening over qualifier constraints. https://github.com/NCATSTranslator/ReasonerAPI/pull/364

EDIT: Found this issue that may be useful for tracking changes https://github.com/NCATSTranslator/ReasonerAPI/issues/357

[colleenXu]

Recording an exercise I did during the Sept 2022 Relay: trying to convert the following question to TRAPI

Question: "What are compounds that significantly reduce CHRNA1 expression while increasing CHRNA1 expression in myocytes?"

basic TRAPI 1.3 with Biolink 2.4.8, using QEdge.attribute-constraints

``` { "message": { "query_graph": { "nodes": { "gene": { "ids": ["NCBIGene:1134"], "name": "CHRNA1" }, "chemical": { "categories": ["biolink:ChemicalEntity"], "name": "compounds" } }, "edges": { "decreases_expression": { "subject": "chemical", "object": "gene", "predicates": ["biolink:decreases_expression_of"] }, "increases_expression": { "subject": "chemical", "object": "gene", "predicates": ["biolink:increases_expression_of"], "attribute_constraints": [{ "id": "biolink:expression_site", "name": "increasing CHRNA1 expression in myocytes", "operator": "==", "value": "CL:0000187" }] } } } } } ```

TRAPI 1.3 with Biolink 3.0.2 qualifiers...seems very hard to compose

``` { "message": { "query_graph": { "nodes": { "gene": { "ids": ["NCBIGene:1134"], "name": "CHRNA1" }, "chemical": { "categories": ["biolink:ChemicalEntity"], "name": "compounds" } }, "edges": { "decreases_expression": { "subject": "chemical", "object": "gene", "predicates": ["biolink:affects"], "qualifier_constraints": [{ "qualifier_set": [ { "qualifier_type_id": "object_direction_qualifier", "qualifier_value": "decreased" }, { "qualifier_type_id": "object_aspect_qualifier", "qualifier_value": "expression" } ] }] }, "increases_expression": { "subject": "chemical", "object": "gene", "predicates": ["biolink:affects"], "qualifier_constraints": [{ "qualifier_set": [ { "qualifier_type_id": "object_direction_qualifier", "qualifier_value": "increased" }, { "qualifier_type_id": "object_aspect_qualifier", "qualifier_value": "expression" }, { "qualifier_type_id": "anatomical_context_qualifier", "qualifier_value": "CL:0000187" } ] }] } } } } } ```

I also noticed the use of qualified predicate in the biolink-model, but I don't remember seeing this field in TRAPI 1.3...

Also what are qualifier sets for (should the "object" stuff and anatomical context stuff be separate sets?)?

[colleenXu]

Putting here as food for thought: Is there a case for multiple kinds of constraints in 1 query? Or multiple constraints of the same type in 1 query?

[colleenXu]

Putting here as notes:

• QNode.constraints: changing the error message, to match PR…
• QEdge.qualifier_constraints: changing behavior to match new implementation rules?

[colleenXu]

Note that the latest implementation rules were released in TRAPI v1.3.0 Sept 1st: https://github.com/NCATSTranslator/ReasonerAPI/blob/v1.3.0/ImplementationRules.md. It has info on QNode constraints, QEdge attribute_constraints (on resource allow/denylist), and QEdge qualifier_constraints.

[andrewsu]

what (if anything) in this ticket is still relevant?

[colleenXu]

@andrewsu

Here's my opinions (but I didn't dig super deep). My recommendations are in the bottom section of this comment.

QNode.constraints: based on console logs, BTE is running defunct code related to this (any logs about "constraints"). So I think we need to address this

• we don't have any meaningful Node attributes to constrain. So unless we plan to add Node attributes...we probably want to remove the defunct code / logs...
• we may want to implement some of the guidelines on what to do when you don't support a QNode constraint in a Query

QEdge.attribute_constraints: I think this effort is now defunct, and we may not want to implement this. However, we may want to implement the guideline for properties on QEdges.

• we mostly wanted to implement this for "resource allowlist / denylist": custom "including / excluding some MetaEdges based on source info"
• but now source info isn't even in Edge attributes anymore...now it's in its own section and I didn't notice any TRAPI 1.4 info on how to specify a similar constraint

QEdge.qualifier_constraints: We've implemented this, and it's done as far as I can tell.

---

So....my recommendations are: close this issue, and open 1-2 new issues

• cleaning up the defunct QNode.constraints stuff
• implementing the guidelines for not supporting QNode.constraints and QEdge.attribute_constraints.