Check whether a model satisfies a property (indra.explanation.model_checker
)
Shared Model Checking Functionality (indra.explanation.model_checker.model_checker
)
- class indra.explanation.model_checker.model_checker.ModelChecker(model, statements=None, do_sampling=False, seed=None, nodes_to_agents=None)[source]
The parent class of all ModelCheckers.
- Parameters
model (pysb.Model or indra.assemblers.indranet.IndraNet or PyBEL.Model) – Depending on the ModelChecker class, can be different type.
statements (Optional[list[indra.statements.Statement]]) – A list of INDRA Statements to check the model against.
do_sampling (bool) – Whether to use breadth-first search or weighted sampling to generate paths. Default is False (breadth-first search).
seed (int) – Random seed for sampling (optional, default is None).
nodes_to_agents (dict) – A dictionary mapping nodes of intermediate signed edges graph to INDRA agents.
- graph
A DiGraph with signed nodes to find paths in.
- Type
nx.Digraph
- add_statements(stmts)[source]
Add to the list of statements to check against the model.
- Parameters
stmts (list[indra.statements.Statement]) – The list of Statements to be added for checking.
- check_model(max_paths=1, max_path_length=5, agent_filter_func=None, edge_filter_func=None, allow_direct=True)[source]
Check all the statements added to the ModelChecker.
- Parameters
max_paths (Optional[int]) – The maximum number of specific paths to return for each Statement to be explained. Default: 1
max_path_length (Optional[int]) – The maximum length of specific paths to return. Default: 5
agent_filter_func (Optional[function]) – A function to constrain the intermediate nodes in the path. A function should take an agent as a parameter and return True if the agent is allowed to be in a path and False otherwise.
edge_filter_func (Optional[function]) – A function to filter out edges from the graph. A function should take nodes (and key in case of MultiGraph) as parameters and return True if an edge can be in the graph and False if it should be filtered out.
allow_direct (Optional[bool]) – Whether to allow direct path of length 1 (edge between source and target) to be returned as a result. Default: True.
- Returns
Each tuple contains the Statement checked against the model and a PathResult object describing the results of model checking.
- Return type
list of (Statement, PathResult)
- check_statement(stmt, max_paths=1, max_path_length=5, agent_filter_func=None, node_filter_func=None, edge_filter_func=None, allow_direct=True)[source]
Check a single Statement against the model.
- Parameters
stmt (indra.statements.Statement) – The Statement to check.
max_paths (Optional[int]) – The maximum number of specific paths to return for each Statement to be explained. Default: 1
max_path_length (Optional[int]) – The maximum length of specific paths to return. Default: 5
agent_filter_func (Optional[function]) – A function to constrain the intermediate nodes in the path. A function should take an agent as a parameter and return True if the agent is allowed to be in a path and False otherwise.
node_filter_func (Optional[function]) – Similar to agent_filter_func but it takes a node as a parameter instead of agent. If not provided, node_filter_func will be generated from agent_filter_func.
edge_filter_func (Optional[function]) – A function to filter out edges from the graph. A function should take nodes (and key in case of MultiGraph) as parameters and return True if an edge can be in the graph and False if it should be filtered out.
allow_direct (Optional[bool]) – Whether to allow direct path of length 1 (edge between source and target) to be returned as a result. Default: True.
- Returns
result – A PathResult object containing the result of a test.
- Return type
indra.explanation.modelchecker.PathResult
- find_paths(subj, obj, max_paths=1, max_path_length=5, loop=False, filter_func=None, allow_direct=True)[source]
Check for a source/target path in the model.
- Parameters
subj (indra.explanation.model_checker.NodesContainer) – NodesContainer representing test statement subject.
obj (indra.explanation.model_checker.NodesContainer) – NodesContainer representing test statement object.
max_paths (int) – The maximum number of specific paths to return.
max_path_length (int) – The maximum length of specific paths to return.
loop (bool) – Whether we are looking for a loop path.
filter_func (function or None) – A function to constrain the search. A function should take a node as a parameter and return True if the node is allowed to be in a path and False otherwise. If None, then no filtering is done.
allow_direct (Optional[bool]) – Whether to allow direct path of length 1 (edge between source and target) to be returned as a result. Default: True.
- Returns
PathResult object indicating the results of the attempt to find a path.
- Return type
- get_nodes_to_agents(*args, **kwargs)[source]
Return a dictionary mapping nodes of intermediate signed edges graph to INDRA agents.
- process_statement(stmt)[source]
This method processes the test statement to get the data about subject and object, according to the specific model requirements for model checking, e.g. PysbModelChecker gets subject monomer patterns and observables, while graph based ModelCheckers will return signed nodes corresponding to subject and object. If any of the requirements are not satisfied, result code is also returned to construct PathResult object.
- Parameters
stmt (indra.statements.Statement) – A statement to process.
- Returns
subj_data (NodesContainer) – NodesContainer for statement subject.
obj_data (NodesContainer) – NodesContainer for statement object.
result_code (str or None) – Result code to construct PathResult.
- process_subject(subj_data)[source]
Processes the subject of the test statement and returns the necessary information to check the statement. In case of PysbModelChecker, method returns input_rule_set. If any of the requirements are not satisfied, result code is also returned to construct PathResult object.
- update_filter_func(agent_filter_func)[source]
Converts a function filtering agents to a function filtering nodes
- Parameters
agent_filter_func (function) – A function to constrain the intermediate nodes in the path. A function should take an agent as a parameter and return True if the agent is allowed to be in a path and False otherwise.
- Returns
node_filter_func – A new filter function applying the logic from agent_filter_func to nodes instead of agents.
- Return type
function
- class indra.explanation.model_checker.model_checker.NodesContainer(main_agent, ref_agents=None)[source]
Contains the information about nodes corresponding to a given agent of the test statement.
- Parameters
main_agent (indra.statements.Agent) – An INDRA agent representing a subject or object of test statement.
ref_agents (list[indra.statements.Agent]) – A list of agents that are refinements of main agent.
- common_target
Common target node connected to all nodes. If there’s only one node in all_nodes, then common_target is not used.
- Type
tuple or None
- main_interm
A list of intermediate representation between main agent and main nodes (only used in PySB currently - MonomerPatterns).
- Type
list[MonomerPattern]
- class indra.explanation.model_checker.model_checker.PathMetric(source_node, target_node, length)[source]
Describes results of simple path search (path existence).
- class indra.explanation.model_checker.model_checker.PathResult(path_found, result_code, max_paths, max_path_length)[source]
Describes results of running the ModelChecker on a single Statement.
- result_code
STATEMENT_TYPE_NOT_HANDLED - The provided statement type is not handled
SUBJECT_MONOMERS_NOT_FOUND or SUBJECT_NOT_FOUND - Statement subject not found in model
OBSERVABLES_NOT_FOUND or OBJECT_NOT_FOUND - Statement has no associated observable
NO_PATHS_FOUND - Statement has no path for any observable
MAX_PATH_LENGTH_EXCEEDED - Statement has no path len <= MAX_PATH_LENGTH
PATHS_FOUND - Statement has path len <= MAX_PATH_LENGTH
INPUT_RULES_NOT_FOUND - No rules with Statement subject found
MAX_PATHS_ZERO - Path found but MAX_PATHS is set to zero
- Type
string
- max_paths
The maximum number of specific paths to return for each Statement to be explained.
- Type
- path_metrics
A list of PathMetric objects, each describing the results of a simple path search (path existence).
- Type
list[
indra.explanation.model_checker.PathMetric
]
- indra.explanation.model_checker.model_checker.prune_signed_nodes(graph)[source]
Prune nodes with sign (1) if they do not have predecessors.
- indra.explanation.model_checker.model_checker.signed_edges_to_signed_nodes(graph, prune_nodes=True, edge_signs={'neg': 1, 'pos': 0}, copy_edge_data=False)[source]
Convert a graph with signed edges to a graph with signed nodes.
Each pair of nodes linked by an edge in an input graph are represented as four nodes and two edges in the new graph. For example, an edge (a, b, 0), where a and b are nodes and 0 is a sign of an edge (positive), will be represented as edges ((a, 0), (b, 0)) and ((a, 1), (b, 1)), where (a, 0), (a, 1), (b, 0), (b, 1) are signed nodes. An edge (a, b, 1) with sign 1 (negative) will be represented as edges ((a, 0), (b, 1)) and ((a, 1), (b, 0)).
- Parameters
graph (networkx.MultiDiGraph) – Graph with signed edges to convert. Can have multiple edges between a pair of nodes.
prune_nodes (Optional[bool]) – If True, iteratively prunes negative (with sign 1) nodes without predecessors.
edge_signs (dict) – A dictionary representing the signing policy of incoming graph. The dictionary should have strings ‘pos’ and ‘neg’ as keys and integers as values.
copy_edge_data (bool|set(keys)) – Option for copying edge data as well from graph. If False (default), no edge data is copied (except sign). If True, all edge data is copied. If a set of keys is provided, only the keys appearing in the set will be copied, assuming the key is part of a nested dictionary.
- Returns
signed_nodes_graph
- Return type
networkx.DiGraph
Checking PySB model (indra.explanation.model_checker.pysb
)
- class indra.explanation.model_checker.pysb.PysbModelChecker(model, statements=None, agent_obs=None, do_sampling=False, seed=None, model_stmts=None, nodes_to_agents=None)[source]
Check a PySB model against a set of INDRA statements.
- Parameters
model (pysb.Model) – A PySB model to check.
statements (Optional[list[indra.statements.Statement]]) – A list of INDRA Statements to check the model against.
agent_obs (Optional[list[indra.statements.Agent]]) – A list of INDRA Agents in a given state to be observed.
do_sampling (bool) – Whether to use breadth-first search or weighted sampling to generate paths. Default is False (breadth-first search).
seed (int) – Random seed for sampling (optional, default is None).
model_stmts (list[indra.statements.Statement]) – A list of INDRA statements used to assemble PySB model.
nodes_to_agents (dict) – A dictionary mapping nodes of intermediate signed edges graph to INDRA agents.
- graph
A DiGraph with signed nodes to find paths in.
- Type
nx.Digraph
- draw_im(fname)[source]
Draw and save the influence map in a file.
- Parameters
fname (str) – The name of the file to save the influence map in. The extension of the file will determine the file format, typically png or pdf.
- generate_im(model)[source]
Return a graph representing the influence map generated by Kappa
- Parameters
model (pysb.Model) – The PySB model whose influence map is to be generated
- Returns
graph – A MultiDiGraph representing the influence map
- Return type
networkx.MultiDiGraph
- get_all_mps(agents, ignore_activities=False, mapping=False)[source]
Get a list of all monomer patterns for a list of agents.
- get_graph(prune_im=True, prune_im_degrade=True, prune_im_subj_obj=False, add_namespaces=False, edge_filter_func=None)[source]
Get influence map and convert it to a graph with signed nodes.
- get_im(force_update=False)[source]
Get the influence map for the model, generating it if necessary.
- Parameters
force_update (bool) – Whether to generate the influence map when the function is called. If False, returns the previously generated influence map if available. Defaults to True.
- Returns
The influence map can be rendered as a pdf using the dot layout program as follows:
im_agraph = nx.nx_agraph.to_agraph(influence_map) im_agraph.draw('influence_map.pdf', prog='dot')
- Return type
networkx MultiDiGraph object containing the influence map.
- get_nodes_to_agents(add_namespaces=False)[source]
Return a dictionary mapping influence map nodes to INDRA agents.
- process_statement(stmt)[source]
This method processes the test statement to get the data about subject and object, according to the specific model requirements for model checking, e.g. PysbModelChecker gets subject monomer patterns and observables, while graph based ModelCheckers will return signed nodes corresponding to subject and object. If any of the requirements are not satisfied, result code is also returned to construct PathResult object.
- Parameters
stmt (indra.statements.Statement) – A statement to process.
- Returns
subj_data (NodesContainer) – NodesContainer for statement subject.
obj_data (NodesContainer) – NodesContainer for statement object.
result_code (str or None) – Result code to construct PathResult.
- process_subject(subj_mp)[source]
Processes the subject of the test statement and returns the necessary information to check the statement. In case of PysbModelChecker, method returns input_rule_set. If any of the requirements are not satisfied, result code is also returned to construct PathResult object.
- prune_influence_map()[source]
Remove edges between rules causing problematic non-transitivity.
First, all self-loops are removed. After this initial step, edges are removed between rules when they share all child nodes except for each other; that is, they have a mutual relationship with each other and share all of the same children.
Note that edges must be removed in batch at the end to prevent edge removal from affecting the lists of rule children during the comparison process.
- prune_influence_map_degrade_bind_positive(model_stmts)[source]
Prune positive edges between X degrading and X forming a complex with Y.
- prune_influence_map_subj_obj()[source]
Prune influence map to include only edges where the object of the upstream rule matches the subject of the downstream rule.
- score_paths(paths, agents_values, loss_of_function=False, sigma=0.15, include_final_node=False)[source]
Return scores associated with a given set of paths.
- Parameters
paths (list[list[tuple[str, int]]]) – A list of paths obtained from path finding. Each path is a list of tuples (which are edges in the path), with the first element of the tuple the name of a rule, and the second element its polarity in the path.
agents_values (dict[indra.statements.Agent, float]) – A dictionary of INDRA Agents and their corresponding measured value in a given experimental condition.
loss_of_function (Optional[boolean]) – If True, flip the polarity of the path. For instance, if the effect of an inhibitory drug is explained, set this to True. Default: False
sigma (Optional[float]) – The estimated standard deviation for the normally distributed measurement error in the observation model used to score paths with respect to data. Default: 0.15
include_final_node (Optional[boolean]) – Determines whether the final node of the path is included in the score. Default: False
- indra.explanation.model_checker.pysb.remove_im_params(model, im)[source]
Remove parameter nodes from the influence map.
- Parameters
model (pysb.core.Model) – PySB model.
im (networkx.MultiDiGraph) – Influence map.
- Returns
Influence map with the parameter nodes removed.
- Return type
networkx.MultiDiGraph
Checking Signed Graph (indra.explanation.model_checker.signed_graph
)
- class indra.explanation.model_checker.signed_graph.SignedGraphModelChecker(model, statements=None, do_sampling=False, seed=None, nodes_to_agents=None)[source]
Check an signed MultiDiGraph against a set of INDRA statements.
- Parameters
model (networkx.MultiDiGraph) – Signed MultiDiGraph to check.
statements (Optional[list[indra.statements.Statement]]) – A list of INDRA Statements to check the model against.
do_sampling (bool) – Whether to use breadth-first search or weighted sampling to generate paths. Default is False (breadth-first search).
seed (int) – Random seed for sampling (optional, default is None).
nodes_to_agents (dict) – A dictionary mapping nodes of intermediate signed edges graph to INDRA agents.
- graph
A DiGraph with signed nodes to find paths in.
- Type
nx.Digraph
- get_graph(edge_filter_func=None, copy_edge_data=None)[source]
Get a signed nodes graph to search for paths in.
- Parameters
edge_filter_func (Optional[function]) – A function to filter out edges from the graph. A function should take nodes (and key in case of MultiGraph) as parameters and return True if an edge can be in the graph and False if it should be filtered out.
copy_edge_data (set(str)) – A set of keys to copy from original model edge data to the graph edge data. If None, only belief data is copied by default.
- process_statement(stmt)[source]
This method processes the test statement to get the data about subject and object, according to the specific model requirements for model checking, e.g. PysbModelChecker gets subject monomer patterns and observables, while graph based ModelCheckers will return signed nodes corresponding to subject and object. If any of the requirements are not satisfied, result code is also returned to construct PathResult object.
- Parameters
stmt (indra.statements.Statement) – A statement to process.
- Returns
subj_data (NodesContainer) – NodesContainer for statement subject.
obj_data (NodesContainer) – NodesContainer for statement object.
result_code (str or None) – Result code to construct PathResult.
Checking Unsigned Graph (indra.explanation.model_checker.unsigned_graph
)
- class indra.explanation.model_checker.unsigned_graph.UnsignedGraphModelChecker(model, statements=None, do_sampling=False, seed=None, nodes_to_agents=None)[source]
Check an unsigned DiGraph against a set of INDRA statements.
- Parameters
model (networkx.DiGraph) – Unsigned DiGraph to check.
statements (Optional[list[indra.statements.Statement]]) – A list of INDRA Statements to check the model against.
do_sampling (bool) – Whether to use breadth-first search or weighted sampling to generate paths. Default is False (breadth-first search).
seed (int) – Random seed for sampling (optional, default is None).
nodes_to_agents (dict) – A dictionary mapping nodes of intermediate signed edges graph to INDRA agents.
- graph
A DiGraph with signed nodes to find paths in.
- Type
nx.Digraph
- get_graph(edge_filter_func=None, copy_edge_data=None)[source]
Get a signed nodes graph to search for paths in.
- Parameters
edge_filter_func (Optional[function]) – A function to filter out edges from the graph. A function should take nodes (and key in case of MultiGraph) as parameters and return True if an edge can be in the graph and False if it should be filtered out.
copy_edge_data (set(str)) – A set of keys to copy from original model edge data to the graph edge data. If None, only belief data is copied by default.
- process_statement(stmt)[source]
This method processes the test statement to get the data about subject and object, according to the specific model requirements for model checking, e.g. PysbModelChecker gets subject monomer patterns and observables, while graph based ModelCheckers will return signed nodes corresponding to subject and object. If any of the requirements are not satisfied, result code is also returned to construct PathResult object.
- Parameters
stmt (indra.statements.Statement) – A statement to process.
- Returns
subj_data (NodesContainer) – NodesContainer for statement subject.
obj_data (NodesContainer) – NodesContainer for statement object.
result_code (str or None) – Result code to construct PathResult.
Checking PyBEL Graph (indra.explanation.model_checker.pybel
)
- class indra.explanation.model_checker.pybel.PybelModelChecker(model, statements=None, do_sampling=False, seed=None, nodes_to_agents=None)[source]
Check a PyBEL model against a set of INDRA statements.
- Parameters
model (pybel.BELGraph) – A Pybel model to check.
statements (Optional[list[indra.statements.Statement]]) – A list of INDRA Statements to check the model against.
do_sampling (bool) – Whether to use breadth-first search or weighted sampling to generate paths. Default is False (breadth-first search).
seed (int) – Random seed for sampling (optional, default is None).
nodes_to_agents (dict) – A dictionary mapping nodes of intermediate signed edges graph to INDRA agents.
- graph
A DiGraph with signed nodes to find paths in.
- Type
nx.Digraph
- get_graph(include_variants=False, symmetric_variant_links=False, include_components=True, symmetric_component_links=True, edge_filter_func=None)[source]
Convert a PyBELGraph to a graph with signed nodes.
- process_statement(stmt)[source]
This method processes the test statement to get the data about subject and object, according to the specific model requirements for model checking, e.g. PysbModelChecker gets subject monomer patterns and observables, while graph based ModelCheckers will return signed nodes corresponding to subject and object. If any of the requirements are not satisfied, result code is also returned to construct PathResult object.
- Parameters
stmt (indra.statements.Statement) – A statement to process.
- Returns
subj_data (NodesContainer) – NodesContainer for statement subject.
obj_data (NodesContainer) – NodesContainer for statement object.
result_code (str or None) – Result code to construct PathResult.