mbrush
commented
2 years ago 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
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
QualifierConstraintobject calledqualified_predicatewith cardinality 0..1, that would sit alongside the existingqualifier_setproperty.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 anobject_aspect_qualifierwith the value "expression", anobject_direction_qualifierwith the value "increased", and aqualified_predicatewith 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.