Belief Engine API (indra.belief)
- class indra.belief.BayesianScorer(prior_counts, subtype_counts)[source]
This is a belief scorer which assumes a Beta prior and a set of prior counts of correct and incorrect instances for a given source. It exposes and interface to take additional counts and update its probability parameters which can then be used to calculate beliefs on a set of Statements.
- Parameters
- class indra.belief.BeliefEngine(scorer=None, matches_fun=None, refinements_graph=None)[source]
Assigns beliefs to INDRA Statements based on supporting evidence.
- Parameters
scorer (
Optional[BeliefScorer]) – A BeliefScorer object that computes the prior probability of a statement given its its statment type, evidence, or other features. Must implement the score_statements method which takes Statements and computes the belief score of a statement, and the check_prior_probs method which takes a list of INDRA Statements and verifies that the scorer has all the information it needs to score every statement in the list, and raises an exception if not.matches_fun (
Optional[Callable[[Statement],str]]) – A function handle for a custom matches key if a non-default one is used. Default is None.refinements_graph (
Optional[DiGraph]) – A graph whose nodes are statement hashes, and edges point from a more specific to a less specific statement representing a refinement. If not given, a new graph is constructed here.
- get_hierarchy_probs(statements)[source]
Gets hierarchical belief probabilities for INDRA Statements.
- Parameters
statements (
Sequence[Statement]) – A list of INDRA Statements whose belief scores are to be calculated. Each Statement object’s belief attribute is updated by this function.- Return type
- Returns
A dictionary mapping statement hashes to corresponding belief scores. Hashes are calculated using the instance’s self.matches_fun.
- get_hierarchy_probs_from_hashes(statements, refiners_list)[source]
Return the full belief of a statement with refiners given as hashes.
- Parameters
statements (
Sequence[Statement]) – Statements to calculate beliefs for.refiners_list (
List[List[int]]) – A list corresponding to the list of statements, where each entry is a list of statement hashes for the statements that are refinements (i.e., more specific versions) of the corresponding statement in the statements list. If there are no refiner statements the entry should be an empty list.
- Return type
- Returns
A dictionary mapping statement hashes to corresponding belief scores.
- set_hierarchy_probs(statements)[source]
Sets hierarchical belief probabilities for INDRA Statements.
The Statements are assumed to be in a hierarchical relation graph with the supports and supported_by attribute of each Statement object having been set. The hierarchical belief probability of each Statement is calculated based the accumulated evidence from both itself and its more specific statements in the hierarchy graph.
- set_linked_probs(linked_statements)[source]
Sets the belief probabilities for a list of linked INDRA Statements.
The list of LinkedStatement objects is assumed to come from the MechanismLinker. The belief probability of the inferred Statement is assigned the joint probability of its source Statements.
- Parameters
linked_statements (
List[LinkedStatement]) – A list of INDRA LinkedStatements whose belief scores are to be calculated. The belief attribute of the inferred Statement in the LinkedStatement object is updated by this function.- Return type
- set_prior_probs(statements)[source]
Sets the prior belief probabilities for a list of INDRA Statements.
The Statements are assumed to be de-duplicated. In other words, each Statement in the list passed to this function is assumed to have a list of Evidence objects that support it. The prior probability of each Statement is calculated based on the number of Evidences it has and their sources.
- class indra.belief.BeliefScorer[source]
Base class for a belief engine scorer, which computes the prior probability of a statement given its type and evidence.
To use with the belief engine, make a subclass with methods implemented.
- check_prior_probs(statements)[source]
Make sure the scorer has all the information needed to compute belief scores of each statement in the provided list, and raises an exception otherwise.
- score_statement(statement, extra_evidence=None)[source]
Score a single statement by passing arguments to score_statements.
- Return type
- score_statements(statements, extra_evidence=None)[source]
Computes belief probabilities for a list of INDRA Statements.
The Statements are assumed to be de-duplicated. In other words, each Statement is assumed to have a list of Evidence objects that supports it. The probability of correctness of the Statement is generally calculated based on the number of Evidences it has, their sources, and other features depending on the subclass implementation.
- Parameters
statements (
Sequence[Statement]) – INDRA Statements whose belief scores are to be calculated.extra_evidence (
Optional[List[List[Evidence]]]) – A list corresponding to the given list of statements, where each entry is a list of Evidence objects providing additional support for the corresponding statement (i.e., Evidences that aren’t already included in the Statement’s own evidence list).
- Return type
- Returns
The computed prior probabilities for each statement.
- class indra.belief.SimpleScorer(prior_probs=None, subtype_probs=None)[source]
Computes the prior probability of a statement given its type and evidence.
- Parameters
prior_probs (
Optional[Dict[str,Dict[str,float]]]) – A dictionary of prior probabilities used to override/extend the default ones. There are two types of prior probabilities: rand and syst, corresponding to random error and systematic error rate for each knowledge source. The prior_probs dictionary has the general structure {‘rand’: {‘s1’: pr1, …, ‘sn’: prn}, ‘syst’: {‘s1’: ps1, …, ‘sn’: psn}} where ‘s1’ … ‘sn’ are names of input sources and pr1 … prn and ps1 … psn are error probabilities. Examples: {‘rand’: {‘some_source’: 0.1}} sets the random error rate for some_source to 0.1; {‘rand’: {‘’}}subtype_probs (
Optional[Dict[str,Dict[str,float]]]) – A dictionary of random error probabilities for knowledge sources. When a subtype random error probability is not specified, will just use the overall type prior in prior_probs. If None, will only use the priors for each rule.
- check_prior_probs(statements)[source]
Throw Exception if BeliefEngine parameter is missing.
Make sure the scorer has all the information needed to compute belief scores of each statement in the provided list, and raises an exception otherwise.
- score_statements(statements, extra_evidence=None)[source]
Computes belief probabilities for a list of INDRA Statements.
The Statements are assumed to be de-duplicated. In other words, each Statement is assumed to have a list of Evidence objects that supports it. The probability of correctness of the Statement is generally calculated based on the number of Evidences it has, their sources, and other features depending on the subclass implementation.
- Parameters
statements (
Sequence[Statement]) – INDRA Statements whose belief scores are to be calculated.extra_evidence (
Optional[List[List[Evidence]]]) – A list corresponding to the given list of statements, where each entry is a list of Evidence objects providing additional support for the corresponding statement (i.e., Evidences that aren’t already included in the Statement’s own evidence list).
- Return type
- Returns
The computed prior probabilities for each statement.
- indra.belief.assert_no_cycle(g)[source]
If the graph has cycles, throws AssertionError.
This can be used to make sure that a refinements graph is a DAG.
- Parameters
g (
DiGraph) – A refinements graph.- Return type
- indra.belief.build_refinements_graph(statements, matches_fun=None)[source]
Return a DiGraph based on matches hashes and Statement refinements.
- Parameters
- Return type
DiGraph- Returns
A networkx graph whose nodes are statement hashes carrying a stmt attribute with the actual statement object. Edges point from less detailed to more detailed statements (i.e., from a statement to another statement that refines it).
- indra.belief.check_extra_evidence(extra_evidence, num_stmts)[source]
Check whether extra evidence list has correct length/contents.
Raises ValueError if the extra_evidence list does not match the length num_stmts, or if it contains items other than empty lists or lists of Evidence objects.
- Parameters
extra_evidence (
Optional[List[List[Evidence]]]) – A list of length num_stmts where each entry is a list of Evidence objects, or None. If extra_evidence is None, the function returns without raising an error.num_stmts (
int) – An integer giving the required length of the extra_evidence list (which should correspond to a list of statements)
- Return type
- indra.belief.evidence_random_noise_prior(evidence, type_probs, subtype_probs)[source]
Gets the random-noise prior probability for this evidence.
If the evidence corresponds to a subtype, and that subtype has a curated prior noise probability, use that.
Otherwise, gives the random-noise prior for the overall rule type.
- Return type
- indra.belief.extend_refinements_graph(g, stmt, less_specifics, matches_fun=None)[source]
Extend refinements graph with a new statement and its refinements.
- Parameters
g (
DiGraph) – A refinements graph to be extended.stmt (
Statement) – The statement to be added to the refinements graph.less_specifics (
List[int]) – A list of statement hashes of statements that are refined by this statement (i.e., are less specific versions of it).matches_fun (
Optional[Callable[[Statement],str]]) – An optional function to calculate the matches key and hash of a given statement. Default: None
- Return type
DiGraph
- indra.belief.get_ev_for_stmts_from_hashes(statements, refiners_list, refinements_graph)[source]
Collect evidence from the more specific statements of a list of statements.
Similar to
get_ev_for_stmts_from_supports(), but the more specific statements are specified explicitly by the hashes in refiners_list rather than obtained from the supports attribute of each statement. In addition, the refinements_graph argument is expected to have been pre-calculated (using the same matches key function used to generate the hashes in refiners_list) and hence is not optional.- Parameters
statements (
Sequence[Statement]) – A list of Statements with supports Statements.refiners_list (
List[List[int]]) – A list corresponding to the list of statements, where each entry is a list of statement hashes for the statements that are refinements (i.e., more specific versions) of the corresponding statement in the statements list. If there are no refiner statements for a statement the entry should be an empty list.refinements_graph (
DiGraph) – A networkx graph whose nodes are statement hashes carrying a stmt attribute with the actual statement object. Edges point from less detailed to more detailed statements (i.e., from a statement to another statement that refines it).
- Return type
- Returns
A list corresponding to the given list of statements, where each entry is a list of Evidence objects providing additional support for the corresponding statement (i.e., Evidences that aren’t already included in the Statement’s own evidence list).
- indra.belief.get_ev_for_stmts_from_supports(statements, refinements_graph=None, matches_fun=None)[source]
Collect evidence from the more specific statements of a list of statements.
- Parameters
statements (
Sequence[Statement]) – A list of Statements with supports Statements.refinements_graph (
Optional[DiGraph]) – A networkx graph whose nodes are statement hashes carrying a stmt attribute with the actual statement object. Edges point from less detailed to more detailed statements (i.e., from a statement to another statement that refines it). If not provided, the graph is generated from statements using the functionbuild_refinements_graph().matches_fun (
Optional[Callable[[Statement],str]]) – An optional function to calculate the matches key and hash of a given statement. If not provided, the default matches function is used. Default: None.
- Return type
- Returns
A list corresponding to the given list of statements, where each entry is a list of Evidence objects providing additional support for the corresponding statement (i.e., Evidences that aren’t already included in the Statement’s own evidence list).
- indra.belief.get_stmt_evidence(stmt, ix, extra_evidence)[source]
Combine a statements’ own evidence with any extra evidence provided.
- indra.belief.sample_statements(stmts, seed=None)[source]
Return statements sampled according to belief.
Statements are sampled independently according to their belief scores. For instance, a Statement with a belief score of 0.7 will end up in the returned Statement list with probability 0.7.
- Parameters
- Return type
- Returns
A list of INDRA Statements that were chosen by random sampling according to their respective belief scores.