Add QualifierConstraint.qualified_predicate property

[mbrush]

On a recent TRAPI call, we discussed the requirement to allow specification of the qualified predicate that pairs with a set of qualifiers used to constrain a query, so the query itself is clear and complete. This came up in the context of the example query Sierra presented here - where a constraint on the qualified predicate had to be captured in a Qualifier object (even though qualified predicates are not themselves considered to be Qualifiers).

To better accommodate this requirement, we propose adding a new property to the QualifierConstraint object called qualified_predicate with cardinality 0..1, that would sit alongside the existing qualifier_set property.

• QualifierConstraint.qualified_predicate: the qualified predicate that pairs with the qualifiers specified in a qualifier set. As part of a QueryConstraint, this qualified predicate must be present with the constrained qualifiers in order for a given Edge to be returned. This property is not required in a QualifierConstraint object however, as not all qualified Edges in knowledge graphs include a qualified predicate.

We also propose the following updates to descriptions of existing objects and properties, which we feel provide additional clarification.

• Qedge.qualifier_constraints: a list of QualifierConstraints that constrain a query to match specified patterns of qualifiers that must be present on an Edge.

• QualifierConstraint: Defines a query constraint based on the types and values of qualifiers in an Edge. This constraint may optionally include the qualified predicate that pairs with these qualifiers to provide a precise reading of the full statement expressed in the Edge. For example, we us this to constrain a "ChemicalX - affects - ?Gene" query to return only edges where ChemicalX specifically 'increases' the 'expression' of the Gene, by requiring the Edge to have an object_aspect_qualifier with the value "expression", an object_direction_qualifier with the value "increased", and a qualified_predicate with the value "causes".

• QualifierConstraint.qualifier_set: a set of one or more Qualifiers that are found in a single Edge. As part of a QueryConstraint, this set of qualifiers must be found together on a given Edge in order for that Edge to be returned.

• QualifierConstraint.qualified_predicate: the qualified predicate that pairs with the qualifiers specified in a qualifier set. As part of a QueryConstraint, this qualified predicate must be present with the specified qualifiers in a given Edge in order for it to be returned. This property is not required in a QualifierConstraint however, as not all Edges in a knowledge graph that contain qualifiers include a qualified predicate.

[mbrush]

In our documentation, we need to make it clear that AND logic applies between elements within a single QualifierConstraint object – i.e. all components in the constraint must match an edge for it to be returned. OR logic applies across distinct QualifierConstraint objects - i.e. Edges in the data that match the patterns specified in any one QualifierConstraint object should be returned.

For example, if you want to return edges that assert some chemical that causes increased activity or expression of your gene of interest, your query would contain two QualifierConstraint objects – one that defines the 'causes' 'increased' 'activity' constraint, and one that defines the 'causes' 'increased' 'expression' constraint. Edges that matched the patterns defined in either of these constraint objects would be returned.

Below is a TRAPI query example illustrating this more concretely - and demonstrates use of the proposed QueryConstraint.qualified_predicate property.

---

We would use the following json to query for 'Chemicals that increase activity or expression of the PPARA gene':

{
  "message": {
    "query_graph": {
      "nodes": {
        "n0": {
          "category": "biolink:ChemicalSubstance"
        },
        "n1": {
          "id": "HGNC:9232"
        }
      },
      "edges": {
        "e01": {
          "subject": "n0",
          "object": "n1",
          "predicate": [
            "affects"
          ],
          "qualifier_constraints": [

            {
              "qualifier_set": [
                {
                  "qualifier_type_id": "biolink:object_aspect",
                  "qualifier_value": "activity"
                },
                {
                  "qualifier_type_id": "biolink:object_direction",
                  "value": "increased"
                }
              ],
              "qualified_predicate": "biolink:causes"
            },

            {
              "qualifier_set": [
                {
                  "qualifier_type_id": "biolink:object_aspect",
                  "qualifier_value": "expression"
                },
                {
                  "qualifier_type_id": "biolink:object_direction",
                  "value": "increased"
                }
              ],
              "qualified_predicate": "biolink:causes"
            },

          ]
        }
      }
    }
  }
}

This query would return any Edges that state a ChemicalSubstance causes increased activity of PPARA, or increased expression of PPARA. e.g.:

subject: Fenofibrate
predicate: affects
qualified_predicate: causes
object: PPARA 
object_aspect: activity
object_direction: increased

@sierra-moxon @edeutsch please review proposal. Happy to create a PR if that helps.

[edeutsch]

sure, agreed, note that we already do state that if there are multiple qualifier_constraints, there is a an OR relationship:

ReasonerAPI/TranslatorReasonerAPI.yaml

Lines 688 to 689 in 7520ac5

	If multiple QualifierConstraints are provided, there is an OR
	relationship between them. If the QEdge has multiple

But feel free to make a PR to amplify this.

It is true that we don't very explicitly declare that the items in a qualifier_set have an AND relationship (although I assumed by calling them a "set", this was obvious):

ReasonerAPI/TranslatorReasonerAPI.yaml

Lines 892 to 894 in 7520ac5

	A set of Qualifiers that serves to add nuance to a query,
	by constraining allowed values held by Qualifiers
	on queried Edges.

But feel free to make a PR to amplify this.

[edeutsch]

While the above is easy to shoo into TRAPI 1.3 because it is just a clarification that was already intended, your other proposal to pull qualified_predicate out of the qualifier_set is far more disruptive to the late-stage of TRAPI 1.3. Do you intend this for TRAPI 1.4? Should we create a branch for 1.4 so that we can start creating PRs against that?

Or are you keen to see this be put in 1.3 before release?

[mbrush]

Hi Eric. Re: the proposed enhancements to types / properties - IMO these will help clarify some of the observed and anticipated confusion regarding use of qualifier constraints in queries. Even if all some of the suggestions do is amplify / repeat key info in different places in the spec. I'll draft a PR for these simpler changes and let you/others decide if you want to accept, and massage text as needed.

Re: splitting our the qualified_predicate into its own property (instead of permitting this to be included in a QualifierConstraint.qualifier_set) - I do think this will make the overall paradigm of qualifiers and qualifier-based querying more clear and consistent for users. But as you point out - we can already support constraint on a qualified_predicate by including it in the qualifier_set (even though technically it is not a qualifier). I'll leave it up to you as to when to consider implementing this change. If too late to get into 1.3, we can wait to 1.4. I think we also need to consider if/how we will support for specifying a primary predicate that goes with a qualifier set (for cases where a TRAPI query includes >1 primary predicates) . . . so it may make sense to do these things at the same time in 1.4.

@sierra-moxon your thoughts on this?

[mbrush]

Outcomes from 8-25-22 TRAPI Call:

• One view is that qualified_predicate is a qualifier, and thus it is correct semantically/conceptually to capture in a qualifier_set - so no schema changes are necessary. If we go with this view, the modeling team can update their documentation to frame qualified_predicate as a type of qualifier, and we are good.
• But before making any final decisions here, we want to consider the related use case of supporting queries where multiple primary predicates are specified - and needing to link a QualifierConstraint to one or more of these specific predicates. How we handle this may inform how we want to represent qualified_predicate constraints in a QualifierConstraint object.
• On a related note, we do have language in the QEdge.qualifier_constraints description in the current schema indicating that the 'multiple predicate' use case is not currently supported. We should update this text accordingly when we have decided how to support this use case.