TRAPI Response Validation

class reasoner_validator.validator.TRAPIResponseValidator(default_test: str | None = None, default_target: str | None = None, trapi_version: str | None = None, biolink_version: str | None = None, target_provenance: Dict[str, str] | None = None, strict_validation: bool | None = None, suppress_empty_data_warnings: bool = False)

Bases: BiolinkValidator

TRAPIResponseValidator is an overall wrapper class for validating conformance of full TRAPI Responses to TRAPI and the Biolink Model.

Methods

add_messages(new_messages)

Batch addition of MESSAGES_BY_TARGET messages to a ValidationReporter instance. :param new_messages: MESSAGES_BY_TARGET, messages indexed by target, test and categories: one of "information", "skipped tests", "warnings", "errors" or "critical", with code-keyed dictionaries of (structured) message parameters.

apply_validation(validation_method, *args, ...)

Wrapper to allow validation_methods direct access to the ValidationReporter.

build_source_trail(sources)

Returns a 'source_trail' path from 'primary_knowledge_source' upwards.

case_edge_bindings(q_edge_ids, ...)

Check if target query edge id and knowledge graph edge id are in specified edge_bindings.

case_input_found_in_response(case, response)

Predicate to validate if test data test case specified edge is returned in the Knowledge Graph of the TRAPI Response Message.

case_node_found(target, identifiers, case, nodes)

Check for presence of the target identifier, with expected categories, in the "nodes" catalog.

case_result_found(query_graph, subject_id, ...)

Validate that test case S--P->O edge is found bound to the Results? :param query_graph: Dict, query graph to which the results pertain :param subject_id: str, subject node (CURIE) identifier :param object_id: str, subject node (CURIE) identifier :param edge_id: str, subject node (CURIE) identifier :param results: List of (TRAPI-version specific) Result objects :return: bool, True if case S-P-O edge was found in the results

check_biolink_model_compliance(graph, graph_type)

Validate a TRAPI-schema compliant Message graph-like data structure against the currently active Biolink Model Toolkit model version.

check_biolink_model_compliance_of_input_edge(edge)

Validate a templated test input edge contents against the current BMT Biolink Model release.

check_compliance_of_trapi_response(response)

One stop validation of all components of a TRAPI-schema compliant Query.Response, including its Message against a designated Biolink Model release.

dump([title, id_rows, msg_rows, ...])

Dump all available messages captured by the ValidationReporter, printed as formatted human-readable text, on a specified file device.

dump_all_messages([test, target, flat])

Dump all messages for a given test from a given target, as JSON.

dump_critical([test, target, flat])

Dump critical error messages as JSON.

dump_errors([test, target, flat])

Dump 'error' messages as JSON.

dump_info([test, target, flat])

Dump 'information' messages as JSON.

dump_messages_type(message_type[, test, ...])

Dump ValidationReporter messages of type 'message_type' as JSON.

dump_skipped([test, target, flat])

Dump 'skipped test' messages as JSON.

dump_warnings([test, target, flat])

Dump 'warning' messages as JSON.

dumps([id_rows, msg_rows, compact_format])

Text string version of dump(): returns all available messages captured by the ValidationReporter, as a formatted human-readable text blob.

get_all_messages()

Get copy of all MESSAGES_BY_TARGET as a Python data structure.

get_all_messages_of_type(message_type)

Get MESSAGE_PARTITION dictionary of all ValidationReporter messages of a given 'message_type', harvested from all target and test contexts.

get_biolink_version()

return:

Biolink Model version currently tracked by the TRAPISchemaValidator.

get_critical([test, target])

Get copy of all recorded 'critical' error messages, for a given test from a given target.

get_default_target()

Returns the current target of the ValidationReporter.

get_default_test()

Returns the current default test identifier of the ValidationReporter.

get_errors([test, target])

Get copy of all recorded 'error' messages, for a given test from a given target.

get_info([test, target])

Get copy of all recorded 'information' messages, for a given test from a given target.

get_inverse_predicate(predicate)

Utility wrapper of logic to robustly test if a predicate exists and has an inverse.

get_message_type(code)

Get type of message code.

get_messages_by_target([target])

Returns a block of MESSAGES_BY_TEST corresponding to a given or default target.

get_messages_by_test([test, target])

Returns MESSAGE_CATALOG corresponding to a given or default target. Note that the dictionary returned is not a copy of the original thus caution should be taken not to mutate it! :param test: str, specified test (gets current 'default' test if not given) :param target: str, specified target (gets current 'default' test if not given) :return: MESSAGES_BY_TEST corresponding to a resolved target.

get_messages_of_type(message_type[, test, ...])

Get Python data dictionary of ValidationReporter messages of 'message_type', for a specified (or default?) target and test.

get_node_categories(node_id)

Categories by 'node_id'. :param node_id: :return: For a given node_id, returns the associated categories; None if node_id is currently unknown or has no categories.

get_node_identifiers()

return:

List of currently registered node_ids

get_result()

Get result of validation.

get_skipped([test, target])

Get copy of all recorded 'skipped test' messages, for a given test from a given target.

get_target_provenance()

Returns infores-prefix-normalized target provenance metadata.

get_trapi_version()

return:

str, TRAPI (SemVer) version currently targeted by the TRAPISchemaValidator.

get_warnings([test, target])

Get copy of all recorded 'warning' messages, for a given test from a given target.

has_critical([test, target])

Predicate to detect any recorded critical error messages.

has_errors([test, target])

Predicate to detect any recorded error messages.

has_information([test, target])

Predicate to detect any recorded information messages.

has_message_type(message_type[, test, target])

Predicate to detect if ValidationReporter has any non-empty messages of type 'message_type'.

has_messages([test, target])

Predicate to detect any recorded validation messages.

has_skipped([test, target])

Predicate to detect any recorded 'skipped test' messages.

has_valid_knowledge_graph(message[, edges_limit])

Validate a TRAPI Knowledge Graph.

has_valid_query_graph(message)

Validate a TRAPI Query Graph.

has_valid_results(message[, sample_size])

Validate a TRAPI Results.

has_warnings([test, target])

Predicate to detect any recorded warning messages.

is_strict_validation(graph_type)

Predicate to test if strict validation is to be applied.

is_symmetric(name)

Checks if a given element identified by name, is a symmetric (predicate) slot.

is_valid_trapi_query(instance[, component])

Make sure that the Message is a syntactically valid TRAPI Query JSON object.

merge(reporter)

Merge all messages and metadata from a second BiolinkValidator, into the calling TRAPISchemaValidator instance.

merge_coded_messages(aggregated, additions)

Merge additional MESSAGE_PARTITION content into an already aggregate MESSAGE_PARTITION.

minimum_required_biolink_version(version)

param version:

simple 'major.minor.patch' Biolink Model SemVer

minimum_required_trapi_version(version)

param version:

simple 'major.minor.patch' TRAPI schema release SemVer

report(code[, test, target, source_trail])

Capture a single validation message, as per specified 'code' (with any code-specific contextual parameters). :param code: str, dot delimited validation path code :param test: str, specified test (gets current 'default' test if not given) :param target: str, specified target (gets current 'default' test if not given) :param source_trail, Optional[str], audit trail of knowledge source provenance for a given Edge, as a string. Defaults to "global" if not specified. :param message: **Dict, named parameters representing extra (str-formatted) context for the given code message :return: None (internally record the validation message).

report_header([title, compact_format])

Return a suitably generated report header. :param title: Optional[str], if title is None, then only the 'reasoner-validator' version is printed out in the header. If the title is an empty string (the default), then 'Validation Report' used. :param compact_format: bool, whether to print the header in compact format (default: True). Extra line feeds are otherwise provided to provide space around the header and control characters are output to underline the header. :return: str, generated header.

reset_biolink_version(version)

Reset Biolink Model version tracked by the ValidationReporter.

reset_default_target(name)

Resets the default target identifier of the ValidationReporter to a new string.

reset_default_test(name)

Resets the default test identifier of the ValidationReporter to a new string.

reset_trapi_version(version)

Reset TRAPI version tracked by the TRAPISchemaValidator.

sample_graph(graph[, edges_limit])

Only process a strict subsample of the TRAPI Response Message knowledge graph.

sample_results(results[, sample_size])

Subsample the results to a maximum size of 'sample_size'

sanitize_workflow(response)

Workflows in TRAPI Responses cannot be validated further due to missing tags and None values.

set_nodes(nodes)

Records additional nodes, uniquely by node_id, with specified categories.

test_case_has_validation_errors(tag, case)

Check if test case has validation errors.

to_dict()

Export BiolinkValidator contents as a Python dictionary (including Biolink version and parent class dictionary content).

validate(instance, component)

Validate instance against schema.

validate_agent_type(edge_id, found, value)

Validate the value of a 'agent_type' of the given edge.

validate_attribute_constraints(edge_id, edge)

Validate Query Edge Attributes.

validate_attributes(graph_type, edge_id, edge)

Validate Knowledge Edge Attributes.

validate_biolink()

Predicate to check if the Biolink (version) is tagged to 'suppress' compliance validation.

validate_category(context, node_id, category)

Validate a Biolink category.

validate_element_status(graph_type, context, ...)

Detect element missing from Biolink, or is deprecated, abstract or mixin, signalled as a failure or warning.

validate_graph_edge(edge, graph_type)

Validate slot properties of a relationship ('biolink:Association') edge.

validate_graph_node(node_id, slots, graph_type)

Validate slot properties (mainly 'categories') of a node.

validate_infores(context, edge_id, identifier)

Validate that the specified identifier is a well-formed Infores CURIE.

validate_knowledge_level(edge_id, found, value)

Validate the value of a 'knowledge_level' of the given edge.

validate_predicate(edge_id, predicate, ...)

Validates predicates based on their meta-nature: existence, mixin, deprecation, etc.

validate_provenance(edge_id, ara_source, ...)

Validates ARA and KP infores knowledge sources based on surveyed Edge slots (recorded in edge "attributes" pre-1.4.0; in "sources", post-1.4.0).

validate_qualifier_constraints(edge_id, edge)

Validate Query Edge Qualifier Constraints.

validate_qualifier_entry(context, edge_id, ...)

Validate Qualifier Entry (JSON Object).

validate_qualifiers(edge_id, edge[, ...])

Validate Knowledge Edge Qualifiers.

validate_slot_value(slot_name, context, ...)

Validate the single-valued value of a specified slot of the given knowledge graph entity slot. :param slot_name, str, name of a valid slot, a value for which is to be validated :param context: str, context of the validation (e.g. node or edge id) :param found: bool, current status of slot detection, Should be true if the slot was already previously seen :param value: Optional[str], the value to be validated :return: bool, True if valid slot and value (validation messages recorded in the BiolinkValidator).

validate_sources(edge_id, edge)

Validate (TRAPI 1.4.0-beta ++) Edge sources provenance.

count_node

get_attribute_type_exclusions

get_bmt

has_dangling_nodes

has_valid_node_information

is_trapi_1_4_or_later

merge_identified_messages

merge_scoped_messages

reset_node_info

validate_input_edge_node
static case_edge_bindings(q_edge_ids: Tuple[str], target_edge_id: str, data: Dict) → bool

Check if target query edge id and knowledge graph edge id are in specified edge_bindings. :rtype: object :param q_edge_ids: Tuple[str], expected query edge identifiers in a matching result :param target_edge_id: str, expected knowledge edge identifier in a matching result :param data: TRAPI version-specific Response context from which the ‘edge_bindings’ may be retrieved :return: True, if found

case_input_found_in_response(case: Dict, response: Dict) → bool

Predicate to validate if test data test case specified edge is returned in the Knowledge Graph of the TRAPI Response Message. This method assumes that the TRAPI response is already generally validated as well-formed.

Parameters:

  • case – Dict, input data test case

  • response – Dict, TRAPI Response whose message ought to contain the test case edge

Returns:

True if test case edge found; False otherwise

case_node_found(target: str, identifiers: List[str], case: Dict, nodes: Dict) → bool

Check for presence of the target identifier, with expected categories, in the “nodes” catalog.

Parameters:

  • target – ‘subject’ or ‘object’

  • identifiers – List of node (CURIE) identifiers to be checked in the “nodes” catalog

  • case – Dict, full test case (to access the target node ‘category’)

  • nodes – Dict, nodes category indexed by node identifiers.

Returns:

case_result_found(query_graph: Dict, subject_id: str, object_id: str, edge_id: str, results: List) → bool

Validate that test case S–P->O edge is found bound to the Results? :param query_graph: Dict, query graph to which the results pertain :param subject_id: str, subject node (CURIE) identifier :param object_id: str, subject node (CURIE) identifier :param edge_id: str, subject node (CURIE) identifier :param results: List of (TRAPI-version specific) Result objects :return: bool, True if case S-P-O edge was found in the results

check_compliance_of_trapi_response(response: Dict | None, max_kg_edges: int = 0, max_results: int = 0)

One stop validation of all components of a TRAPI-schema compliant Query.Response, including its Message against a designated Biolink Model release. The high level structure of a Query.Response is described in https://github.com/NCATSTranslator/ReasonerAPI/blob/master/docs/reference.md#response-.

The TRAPI Query.Response.Message is a Python Dictionary with three entries:

  • Query Graph (“QGraph”): knowledge graph query input parameters

  • Knowledge Graph: output knowledge (sub-)graph containing knowledge (Biolink Model compliant nodes, edges)

    returned from the target resource (KP, ARA) for the query.

  • Results: a list of (annotated) node and edge bindings pointing into the Knowledge Graph, to represent the

    specific answers (subgraphs) satisfying the query graph constraints.

Parameters:

  • response – Optional[Dict], Query.Response to be validated.

  • max_kg_edges – int, maximum number of edges to be validated from the knowledge graph of the response. A value of zero triggers validation of all edges in the knowledge graph (Default: 0 - use all edges)

  • max_results – int, target sample number of results to validate (default: 0 for ‘use all results’).

has_valid_knowledge_graph(message: Dict, edges_limit: int = 0) → bool

Validate a TRAPI Knowledge Graph.

Parameters:

  • message – Dict, input message expected to contain the ‘knowledge_graph’

  • edges_limit – int, integer maximum number of edges to be validated in the knowledge graph. A value of zero triggers validation of all edges in the knowledge graph (Default: 0 - use all edges)

Returns:

bool, False, if validation errors

has_valid_query_graph(message: Dict) → bool

Validate a TRAPI Query Graph. :param message: input message expected to contain the ‘query_graph’ :return: bool, False, if validation errors

has_valid_results(message: Dict, sample_size: int = 0) → bool

Validate a TRAPI Results.

Parameters:

  • message – input message expected to contain the ‘results’

  • sample_size – int, sample number of results to validate (default: 0 for ‘use all results’).

Returns:

bool, False, if validation errors

is_trapi_1_4_or_later() → bool
static sample_graph(graph: Dict, edges_limit: int = 0) → Dict

Only process a strict subsample of the TRAPI Response Message knowledge graph.

Parameters:

  • graph (Dict) – original knowledge graph

  • edges_limit (int) – integer maximum number of edges to be validated in the knowledge graph. A value of zero triggers validation of all edges in the knowledge graph (Default: 0 - use all edges)

Returns:

Dict, ‘edges_limit’ sized subset of knowledge graph

static sample_results(results: List, sample_size: int = 0) → List

Subsample the results to a maximum size of ‘sample_size’

Parameters:

  • results – List, original list of Results

  • sample_size – int, target sample size (default: 0 for ‘use all results’).

Returns:

List, ‘sample_size’ sized subset of Results

static sanitize_workflow(response: Dict) → Dict

Workflows in TRAPI Responses cannot be validated further due to missing tags and None values. This method is a temporary workaround to sanitize the query for additional validation.

Parameters:

response – Dict full TRAPI Response JSON object

Returns:

Dict, response with discretionary removal of content which triggers (temporarily) unwarranted TRAPI validation failures