API reference¶

Everything below is re-exported from the top level, so from causalphylo import find_adjustment_set and from causalphylo.backdoor import find_adjustment_set are equivalent.

causalphylo.graph_semantics¶

Which edges may carry a causal claim. See Which edges earn an arrow.

Which edges may carry a causal claim.

A disease graph assembled from public sources mixes two kinds of edge. Some assert a mechanism with a direction: OmniPath's signed regulatory interactions, where a curator has said that A acts on B. Others assert only that two things occur together: a literature co-mention, membership of a shared pathway, an undirected protein interaction whose arrow exists because one protein landed in the first column of an API response.

Do-calculus over the second kind assumes the very thing a causal method is supposed to establish. So this module partitions the edge types and identification runs only on the causal-admissible subgraph. Associational edges keep contributing to evidence scoring; they stop being arrows.

Gene -> disease is admitted only on genetic evidence. A germline variant is randomised at conception, so a genetic association carries a natural-experiment warrant that a co-mention does not -- the Mendelian randomisation argument (Davey Smith & Ebrahim, 2003, Int J Epidemiol 32:1-22). That warrant is what earns the arrow.

AcyclicCore `dataclass` ¶

A DAG carved out of a possibly-cyclic graph, and what was removed.

excluded names every node that sat in a feedback loop. Those nodes are not silently repaired: d-separation is undefined on them, and identification reports cyclic_component rather than guessing an acyclic orientation.

Source code in src/causalphylo/graph_semantics.py

@dataclass(frozen=True)
class AcyclicCore:
    """A DAG carved out of a possibly-cyclic graph, and what was removed.

    ``excluded`` names every node that sat in a feedback loop. Those
    nodes are not silently repaired: d-separation is undefined on them,
    and identification reports ``cyclic_component`` rather than guessing
    an acyclic orientation.
    """

    dag: nx.DiGraph
    excluded: frozenset[str]

is_causal_admissible ¶

is_causal_admissible(attrs: dict) -> bool

Whether an edge with these attributes may carry a causal claim.

Parameters:

Name	Type	Description	Default
`attrs`	`dict`	Edge attribute mapping, as stored on the NetworkX graph. Reads `edge_type` and `evidence_class`.	required

Source code in src/causalphylo/graph_semantics.py

def is_causal_admissible(attrs: dict) -> bool:
    """Whether an edge with these attributes may carry a causal claim.

    Parameters
    ----------
    attrs
        Edge attribute mapping, as stored on the NetworkX graph. Reads
        ``edge_type`` and ``evidence_class``.
    """
    edge_type = attrs.get("edge_type", "")
    if edge_type in CAUSAL_EDGE_TYPES:
        return True
    if edge_type in _ASSOCIATION_EDGE_TYPES:
        return attrs.get("evidence_class", "") in GENETIC_EVIDENCE_CLASSES
    return False

causal_subgraph ¶

causal_subgraph(G: DiGraph) -> nx.DiGraph

The subgraph of causal-admissible edges, attributes preserved.

Nodes left with no admissible edge are dropped: a node that participates in no causal relation cannot be a treatment, an outcome, or a confounder.

Source code in src/causalphylo/graph_semantics.py

def causal_subgraph(G: nx.DiGraph) -> nx.DiGraph:
    """The subgraph of causal-admissible edges, attributes preserved.

    Nodes left with no admissible edge are dropped: a node that
    participates in no causal relation cannot be a treatment, an
    outcome, or a confounder.
    """
    admissible = [
        (u, v) for u, v, attrs in G.edges(data=True)
        if is_causal_admissible(attrs)
    ]
    return G.edge_subgraph(admissible).copy()

cyclic_components ¶

cyclic_components(G: DiGraph) -> list[frozenset[str]]

Strongly connected components with cycles, including self-loops.

Source code in src/causalphylo/graph_semantics.py

def cyclic_components(G: nx.DiGraph) -> list[frozenset[str]]:
    """Strongly connected components with cycles, including self-loops."""
    cyclic = []
    for component in nx.strongly_connected_components(G):
        # Non-trivial SCC (more than one node)
        if len(component) > 1:
            cyclic.append(frozenset(component))
        # Single node with self-loop
        elif len(component) == 1:
            node = next(iter(component))
            if G.has_edge(node, node):
                cyclic.append(frozenset(component))
    return cyclic

acyclic_core ¶

acyclic_core(G: DiGraph) -> AcyclicCore

Remove every node in a strongly connected component with cycles.

Biological regulatory networks are full of feedback, and nx.is_d_separator requires a DAG of the whole graph -- not merely of the neighbourhood under test. So cyclic nodes come out entirely, and the caller is told which.

Source code in src/causalphylo/graph_semantics.py

def acyclic_core(G: nx.DiGraph) -> AcyclicCore:
    """Remove every node in a strongly connected component with cycles.

    Biological regulatory networks are full of feedback, and
    ``nx.is_d_separator`` requires a DAG of the whole graph -- not merely
    of the neighbourhood under test. So cyclic nodes come out entirely,
    and the caller is told which.
    """
    cyclic_nodes: set[str] = set()
    for component in cyclic_components(G):
        cyclic_nodes |= set(component)

    dag = G.copy()
    dag.remove_nodes_from(cyclic_nodes)
    return AcyclicCore(dag=dag, excluded=frozenset(cyclic_nodes))

Vocabularies¶

CAUSAL_EDGE_TYPES: Frozenset of edge_type values that assert a directed mechanism.
GENETIC_EVIDENCE_CLASSES: Frozenset of evidence_class values that license a gene-to-disease arrow.

causalphylo.backdoor¶

Identification on the admissible subgraph. See Identification.

Pearl's backdoor criterion, and an honest verdict when it cannot be met.

Z satisfies the backdoor criterion relative to (X, Y) when no node in Z is a descendant of X, and Z blocks every path between X and Y that starts with an arrow into X (Pearl, Causality, 2nd ed., Def. 3.3.1). Both halves matter: the descendant condition rules out conditioning on a mediator or a collider downstream of the treatment, and blocking only the backdoor paths -- never the causal path itself -- is what a plain d-separation test does not do for free. To test the second half with a generic d-separation routine, the edges leaving the treatment are removed first: that deletes the causal path (and anything X causes) while leaving every backdoor path, the ones entering X through an arrow, exactly as they were.

This module reports why identification failed, not merely that it did. The reasons are a closed enum so that a run's failures aggregate into a distribution rather than a pile of prose.

A note on trivial identification. When no confounder appears in the graph, the empty set satisfies the criterion and the effect is identifiable -- but a knowledge graph is open-world, and a missing edge is missing knowledge rather than evidence of no confounding. So a trivial verdict is reported under its own reason and carries n_near_miss_confounders: how many nodes regulate the treatment and have some association with the outcome that fell short of admissibility. A target with many near misses is fragile. This is the same move as an E-value in observational epidemiology -- not "there is no confounding" but "here is how much it would take to break this".