Skip to content

A worked example

Everything on this page runs offline and is executed as a doctest, so the numbers below are what the code produced rather than what it was hoped it would produce.

The example builds a small disease graph by hand instead of querying the live sources. That is not a convenience: it makes the example reproducible, and it puts the edge attributes — the things the causal engine actually reads — in plain sight.

The graph

Four entities and four edges. The disease, a target with a genetic association (CCR5), a target with only a literature co-mention (TNF), and a regulator of CCR5 that is itself genetically associated with the disease (CCL5).

>>> from neorx import DiseaseGraph, GraphNode, GraphEdge, NodeType, EdgeType
>>> graph = DiseaseGraph(
...     disease_name="HIV",
...     as_of="2026-01-01",
...     nodes=[
...         GraphNode(node_id="MONDO:0005109", name="HIV",
...                   node_type=NodeType.DISEASE),
...         GraphNode(node_id="CCR5", name="CCR5", node_type=NodeType.GENE,
...                   source="OpenTargets", score=0.8),
...         GraphNode(node_id="TNF", name="TNF", node_type=NodeType.GENE,
...                   source="Monarch", score=0.9),
...         GraphNode(node_id="CCL5", name="CCL5", node_type=NodeType.GENE,
...                   source="OmniPath", score=0.5),
...     ],
...     edges=[
...         GraphEdge(source_id="CCR5", target_id="MONDO:0005109",
...                   edge_type=EdgeType.ASSOCIATED_WITH, weight=0.8,
...                   evidence_class="genetic_association"),
...         GraphEdge(source_id="TNF", target_id="MONDO:0005109",
...                   edge_type=EdgeType.ASSOCIATED_WITH, weight=0.9,
...                   evidence_class="literature"),
...         GraphEdge(source_id="CCL5", target_id="CCR5",
...                   edge_type=EdgeType.REGULATES, weight=0.7,
...                   evidence_class="regulatory"),
...         GraphEdge(source_id="CCL5", target_id="MONDO:0005109",
...                   edge_type=EdgeType.ASSOCIATED_WITH, weight=0.6,
...                   evidence_class="genetic_association"),
...     ],
...     sources_queried=["OpenTargets", "Monarch", "OmniPath"],
... )
>>> graph.n_genes
3

Note what TNF has: the highest node score in the graph, 0.9, and the heaviest edge to the disease, 0.9. On an association ranking it wins.

Why as_of is set here

as_of marks this as a dated build. A dated build does not apply the tissue-expression gate, because that gate queries the Human Protein Atlas live and nothing pins it — today's answer must not decide a classification on a graph built from a past release. Setting it here is what makes this example reach no network at all. See From verdict to target.

Evaluating every candidate

evaluate_all_targets evaluates the whole candidate population and filters nothing. This is the function to use whenever you want a statistic about the procedure.

>>> from neorx.core.causal.identifier import evaluate_all_targets
>>> for result in evaluate_all_targets(graph):
...     print(f"{result.gene_name:5} {result.identifiable!s:5} "
...           f"{result.identification_reason:26} "
...           f"adj={result.adjustment_set} "
...           f"conf={result.causal_confidence:.3f} "
...           f"{result.classification.value}")
CCR5  True  identifiable_by_adjustment adj=['CCL5'] conf=0.478 inconclusive
CCL5  True  identifiable_trivially     adj=[] conf=0.408 inconclusive
TNF   False no_causal_path             adj=[] conf=0.324 correlational

Read that from the right. TNF is classified correlational despite carrying the strongest association in the graph, and the reason is not a threshold: it is no_causal_path. TNF's only edge to the disease is a literature co-mention, which is not admissible as an arrow, so once identification restricts to the admissible subgraph TNF has no path to the outcome at all. There is nothing for the backdoor criterion to reason about.

CCR5 is identifiable by adjustment, and the adjustment set is named: ['CCL5']. CCL5 regulates CCR5 and is associated with the disease, so it opens a backdoor path CCR5 ← CCL5 → HIV. Conditioning on CCL5 closes it. The verdict carries the set, not just the boolean.

CCL5 is identifiable trivially — the empty set satisfies the criterion, because nothing in this graph confounds it. That is a weaker result than it looks, and NeoRx reports it under its own reason for exactly that purpose; see Identification.

Neither CCR5 nor CCL5 reaches causal here. With three genes and two sources there is not enough evidence to clear the threshold, and inconclusive is the honest label. Pushing a four-node toy graph to causal would require weakening the classifier, which is the opposite of the point.

What the pipeline would do with that

identify_causal_targets is evaluate_all_targets followed by ranking and truncation:

>>> from neorx import identify_causal_targets
>>> top = identify_causal_targets(graph, top_n=2, min_causal_confidence=0.4)
>>> [t.gene_name for t in top]
['CCR5', 'CCL5']

Ranking is by causal_confidence, which awards a bonus for being identifiable. So the returned list is a sample selected partly by a property you might want to measure over the candidates — which is why the two functions are separate, and why an identifiability rate computed over identify_causal_targets output would be measuring itself.

Scoring a molecule against that target

Given a target's causal confidence, a candidate molecule is scored on six dimensions. Here is aspirin, measured rather than guessed, scored against CCR5 at the confidence the run just produced:

>>> from neorx.molscreen import (parse_smiles, qed_score, sa_score,
...                              run_all_filters, classify_drug_likeness)
>>> aspirin = parse_smiles("CC(=O)Oc1ccccc1C(O)=O")
>>> round(qed_score(aspirin), 3)
0.55
>>> round(sa_score(aspirin), 3)
1.58
>>> filters = run_all_filters(aspirin)
>>> [(f.name, f.passed) for f in filters]
[('Lipinski', True), ('Veber', True), ('Ghose', False), ('Egan', True), ('PAINS', True), ('Brenk', False)]
>>> classify_drug_likeness(filters)
'Lead-like'
>>> from neorx import score_candidate
>>> candidate = score_candidate(
...     smiles="CC(=O)Oc1ccccc1C(O)=O",
...     target_protein_id="CCR5",
...     target_protein_name="CCR5",
...     causal_confidence=0.478,
...     binding_affinity=-7.5,
...     qed_score=0.55,
...     sa_score=1.58,
...     molecular_weight=180.04,
...     n_filters_passed=4,
... )
>>> candidate.composite_score
0.5757
>>> candidate.score_breakdown
{'causal_confidence': 0.1434, 'binding_affinity': 0.1562, 'qed': 0.0825,
 'sa': 0.0936, 'admet': 0.05, 'novelty': 0.05}

The breakdown is per-dimension and additive, so you can see where a score came from. admet and novelty sit at their 0.5 defaults here because nothing supplied them. The −7.5 kcal/mol is an illustrative number, not a docking result: a real one comes from DockBot.

What this example left out

Two whole stages, both because they cannot be made offline and deterministic:

  • Graph assembly. build_disease_graph("HIV") queries eight sources over HTTP. See The graph and its sources.
  • Docking. AutoDock Vina needs a prepared receptor and a binding site. See DockBot.

The run record system exists for precisely this gap: a real run writes what it read and what it produced, so its numbers are traceable even though they cannot be reproduced from a doctest. See Experiments and run records.