RichardBruskiewich
commented
1 year ago The biolink model sensitive portions of the current KP JSON test configuration file are the test edge data that look something like this:
{
...
"edges": [
{
"subject_category": "biolink:SmallMolecule",
"object_category": "biolink:Disease",
"predicate": "biolink:treats",
"subject": "CHEBI:3002", # beclomethasone dipropionate
"object": "MESH:D001249" # asthma
},
...other test edges
]
}The general strategy to fix the format to align with Biolink Model 3.0++ is perhaps to ensure that test edge data closely mirror the corresponding TRAPI 1.3++ schema data model:
- Specify subject and object categories: already specified by "
subject_category" and "object_category" json object keys respectively. - Specify subject and object identifiers: already specified by "
subject" and "object" json object keys respectively. Would it be reasonable, however, to rename these to "subject_id" and "object_id" to be more precisely consistent with the actual naming of the corresponding TRAPI fields? - Specify filters on edge qualifiers constraints: this a new test data constraint we need to add, although optional, since they may not be needed or supported by all KP's or needed for most knowledge graphs returned by TRAPI. To implement this, we can look at the TRAPI schemata (see Qualifier Constraints below).
- Specify filters edge attributes constraints: the SRI Testing harness already attempts generic validation on attributes with a special focus on knowledge source provenance constraints; however, the current test edge data doesn't explicitly filter on any other attribute content. To implement this (as an optional filter), we can look at the TRAPI schemata (see Attribute Constraints below)
- Specify biolink:association-based class constraint: although still to be fully discussed with the TRAPI Working Group and possibly hosted in TRAPI 1.4 (not 1.3), the possibility may be made of attempting a "soft" introduction leveraging TRAPI 1.3
Attribute Constraints. The main rationale here is that knowing what association category is expected can provide solid guidance for semantic validation of the edge, for example, the range (or subproperty space) of acceptable values for its subject category, predicate and object category, and possibly, what edge qualifiers are expected or appropriate for the edge (see Association Constraint below).
Qualifier Constraints
The TRAPI model (excerpt) for query graph (QEdge) qualifier specification is:
QEdge:
type: object
...
properties:
...
qualifier_constraints:
type: array
description: >-
A list of QualifierConstraints that provide nuance to the QEdge.
If multiple QualifierConstraints are provided, there is an OR
relationship between them. If the QEdge has multiple
predicates or if the QNodes that correspond to the subject or
object of this QEdge have multiple categories or multiple
curies, then qualifier_constraints MUST NOT be specified
because these complex use cases are not supported at this time.
items:
$ref: '#/components/schemas/QualifierConstraint'
default: []where QualifierConstraint is:
QualifierConstraint:
additionalProperties: false
description: >-
...
properties:
qualifier_set:
type: array
description: >-
A set of Qualifiers that serves to add nuance to a query,
by constraining allowed values held by Qualifiers
on queried Edges.
items:
$ref: '#/components/schemas/Qualifier'
nullable: falseand Qualifier is:
Qualifier:
additionalProperties: false
description: >-
An additional nuance attached to an assertion
type: object
properties:
qualifier_type_id:
type: string
description: >-
...
nullable: false
qualifier_value:
type: string
description: >-
...
nullable: false
required:
- qualifier_type_id
- qualifier_valueThis suggests one direct specification of qualifiers in the test data edge might look something like this:
"qualifier_constraints": [
{
"qualifier_set": [
{
"qualifier_type_id": "biolink:causal_mechanism_qualifier"
"qualifier_value": "agonist"
},
{
"qualifier_type_id": "biolink:catalyst_qualifier"
"qualifier_value": "CHEBI:63951" # estrogen receptor agonist
}
]
},
...other qualifier constraint sets?
]Assuming (perhaps foolishly?) that qualifiers can only be specified once in a query, then perhaps the following alternate direct compact representation of the qualifier_type_id = qualifier_value pair could be envisioned:
"qualifier_constraints": {
"biolink:causal_mechanism_qualifier": "inhibition",
...other qualifier type_id:value pairs?
}
But this doesn't allow for duplicate keys, so perhaps we use the full TRAPI syntax for a single Qualifier entry.
On the other hand, we pose the question whether or not test edge input data ought (or need) to have complex multi-qualifier constraints, namely, arrays of multiple QualifierConstraint qualifier_set objects, each containing an array with multiple Qualifier objects. It is an open question about how complex the test edge should be allowed to be, i.e. how many qualifier_set's are specified. Expectations should be realistic here among test specifiers!
An initial implementation of test edge data format supporting qualifiers could limit itself to one qualifier, for example:
"edges": [
{
"subject_category": etc...
"qualifier": {
"qualifier_type_id": "biolink:causal_mechanism_qualifier"
"qualifier_value": "inhibition"
}
} # end of test edge spec
... more test edges
]A second generation implementation of test edge data format supporting qualifiers could allow a single qualifier_set, for example:
"edges": [
{
"subject_category": etc...
"qualifier_set": [
{
"qualifier_type_id": "biolink:causal_mechanism_qualifier"
"qualifier_value": "inhibition"
},
{
"qualifier_type_id": "biolink:causal_mechanism_qualifier"
"qualifier_value": "inhibition"
}
]
} # end of test edge spec
... more test edges
]A third iteration, maybe additional qualifier sets:
"edges": [
{
"subject_category": etc...
"qualifier_constraints": [
{
"qualifier_set": [
{
"qualifier_type_id": "biolink:causal_mechanism_qualifier"
"qualifier_value": "agonist"
},
{
"qualifier_type_id": "biolink:catalyst_qualifier"
"qualifier_value": "CHEBI:63951" # estrogen receptor agonist
}
]
},
... more qualifier sets
]
} # end of test edge spec
... more test edges
]Attribute Constraints
Although QNodes can also have attribute constraints, to use cases for validation are perhaps less compelling than edge filtering, so for now, we focus on the TRAPI AttributeConstraint schema for query graph (QEdge):
QEdge:
type: object
...
properties:
...
attribute_constraints:
type: array
description: >-
A list of attribute constraints applied to a query edge.
If there are multiple items, they must all be true (equivalent
to AND)
items:
$ref: '#/components/schemas/AttributeConstraint'
default: []where AttributeConstraint is:
AttributeConstraint:
type: object
description: >-
Generic query constraint for a query node or query edge
properties:
id:
allOf:
- $ref: '#/components/schemas/CURIE'
description: >-
CURIE of the concept being constrained. For properties
defined by the Biolink model this SHOULD be a biolink CURIE.
otherwise, if possible, from the EDAM ontology. If a suitable
CURIE does not exist, enter a descriptive phrase here and
submit the new type for consideration by the appropriate
authority.
example: EDAM:data_0844
name:
type: string
description: >-
Human-readable name or label for the constraint concept.
If appropriate, it SHOULD be the term name of the CURIE used
as the 'id'. This is redundant but required for human
readability.
example: molecular mass
not:
type: boolean
default: false
operator:
type: string
description: >-
... see TRAPI for full definition
value:
example: 57.0
description: >-
Value of the attribute. May be any data type, including a list.
If the value is a list and there are multiple items, at least one
comparison must be true (equivalent to OR) unless the '==='
operator is used. If 'value' is of data
type 'object', the keys of the object MAY be treated as a list.
A 'list' data type paired with the '>' or '<' operators will
encode extraneous comparisons, but this is permitted as it is in
SQL and other languages.
unit_id:
example: UO:0000222
description: >-
...
nullable: true
unit_name:
example: kilodalton
description: >-
...
nullable: true
required:
- name
- id
- operator
- value
additionalProperties: falseThe AttributeConstraint schema has less depth than QualifierConstraints but obviously more degrees of freedom at the bottome in that values are returned relative to a specific operator with relatively free ranging value data (types). Alas, attribute constraint model indicates that name, id, operator and value are all required.
SRI Testing harness validation generates various permutations of TRAPI test queries based on test edge data. As such, it may need to embrace a more modest objective of supporting a small number of high value use cases (one of which the system has already has, in the focused validation of string knowledge source provenance data).
One new use case may be the validation of Association Constraint below).
Other explicit use cases could initially limit validation to a subset of use cases, for example, to implicitly always assume use of the operator value '===' on simple scalar (e.g. string, numeric) data.
This suggests an initial specification of attribute constraints in the test data edge might look something like this:
"attribute_constraints": [
{
"id": "<attribute_type_id>"
"value": "<value>"
},
...other attribute constraint id/value pairs?
]Association Constraint
Although TRAPI querying of a biolink:Association constraint may initially need to be specified as an attribute constraint (see above), there is nothing that prevents us here from adding a specific 'association' tag to the test edge data JSON (see below).
Summary
Elaborating our original test data example above, the newly formatted test edge data might finally look something like this:
{
...
"edges": [
{
"subject_category": "biolink:SmallMolecule",
"object_category": "biolink:Disease",
"predicate": "biolink:treats",
"subject_id": "CHEBI:3002", # beclomethasone dipropionate
"object_id": "MESH:D001249" # asthma
"association": "biolink:ChemicalToDiseaseOrPhenotypicFeatureAssociation",
"qualifier_constraints": [
{
"qualifier_type_id": "biolink:causal_mechanism_qualifier"
"qualifier_value": "inhibition"
},
...other qualifier constraint type_id/value pairs?
],
"attribute_constraints": [
{
"id": "<attribute_type_id>"
"value": "<value>"
},
...other qualifier constraint type_id/value pairs
]
},
...other test edges
]
}
cbizon
colleenXu
sierra-moxon
Biolink Model 3.0 introduced a new 'qualifier' framework for knowledge representation and TRAPI query. This new framework will require additional KP test edge information for testing, thus, a new KP test data format is needed, perhaps more closely mirroring the TRAPI 1.3 support for this new semantic space. We also need to consider filtering on existing attribute content. Further ahead, constraining test edges to match a specified subclass of
biolink:Associationmay facilitate validation, including qualifier (secondary statement level) validation.