feat(mrm): causal DAGs and the bundled MRM structures

Ports rmorie's morie_dag and morie_mrm_dags. A DAG here is a checked
container over an edge list that carries its own acyclicity proof by
Kahn's algorithm, the same way the R side does, and keeps edges as
(from, to) tuples -- the representation morie.viz.dag_plot and
morie.fn.bdcrt.backdoor_criterion already take, so a graph built here
plots and identifies without conversion. The back-door check delegates
to fn.bdcrt rather than reimplementing Pearl's criterion.

Both bundled structures encode the same shape, which is the shape that
makes an unadjusted comparison misleading: a set of common causes of
both the exposure and the outcome. In `placement` those are race, prior
record and age; in `use_of_force`, neighbourhood and race.

Verified rather than asserted:

* Parity with morie_mrm_dags(): node sets, edge sets, exposure and
  outcome for both graphs IDENTICAL.
* The back-door facts, checkable by hand on these graphs: the empty set
  does NOT satisfy the criterion for either graph, the full common-cause
  set does, and a proper subset does not.
* 7 tests here, 32 across the three MRM files, all passing.

The module is mrm_graphs.py, not mrm_dags.py: a module sharing a name
with one of its functions shadows it through the lazy export map, so
morie.mrm_dags resolved to the module whenever the submodule had been
imported first. That is import-order dependent, which is worse than a
plain failure -- the parity script passed before the tests caught it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GVZR4QjrTXCv55j4qdo6E2

Author: rootcoder007

src/morie/__init__.py

@@ -156,6 +156,8 @@
     "mrm_load_si_dataset": "mrm_flagship",
     "mrm_reconcile": "mrm_flagship",
     "mrm_report": "mrm_flagship",
+    "causal_dag": "mrm_graphs",
+    "mrm_dags": "mrm_graphs",
     "mrm_check_balancing": "mrm_diagnostics",
     "mrm_check_overlap": "mrm_diagnostics",
     "mrm_classify_mandela": "mrm_otis",
@@ -409,6 +411,8 @@ def load_sample(name: str):
     "mrm_load_si_dataset",
     "mrm_reconcile",
     "mrm_report",
+    "causal_dag",
+    "mrm_dags",
     # Tier 1 diagnostics
     "mrm_standardised_difference",
     "mrm_check_balancing",

src/morie/mrm_graphs.py

@@ -0,0 +1,145 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Causal DAGs for MRM, and the bundled starting-point structures.
+
+Parity with rmorie's R/dag_native.R (`morie_dag`, `morie_mrm_dags`).
+
+A DAG here is a thin, checked container over an edge list. It carries
+its own acyclicity proof and keeps edges as ``(from, to)`` tuples, which
+is the representation `morie.viz.dag_plot` and
+`morie.fn.bdcrt.backdoor_criterion` already take -- so a graph built
+here plots and identifies without conversion.
+
+The bundled structures are starting points for justice-system work, not
+claims about a particular jurisdiction. Both encode the same shape: a
+set of common causes of the exposure and the outcome, which is exactly
+the shape that makes an unadjusted comparison misleading.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from morie.fn.bdcrt import backdoor_criterion as _backdoor_criterion
+
+__all__ = ["CausalDag", "causal_dag", "mrm_dags"]
+
+
+@dataclass
+class CausalDag:
+    nodes: list[str]
+    edges: list[tuple[str, str]]
+    exposure: str
+    outcome: str
+    latent: list[str] = field(default_factory=list)
+
+    def __repr__(self) -> str:
+        return ("CausalDag: %d nodes, %d edges, %s -> %s%s"
+                % (len(self.nodes), len(self.edges), self.exposure,
+                   self.outcome,
+                   "" if not self.latent
+                   else " (latent: %s)" % ", ".join(self.latent)))
+
+    def parents(self, node: str) -> list[str]:
+        return [u for u, v in self.edges if v == node]
+
+    def children(self, node: str) -> list[str]:
+        return [v for u, v in self.edges if u == node]
+
+    def backdoor(self, adjust=()):
+        """Does `adjust` satisfy the back-door criterion for this graph?
+
+        Delegates to morie.fn.bdcrt, which implements Pearl's two
+        conditions; the result exposes `.satisfied`.
+        """
+        if isinstance(adjust, str):
+            adjust = (adjust,)
+        return _backdoor_criterion(self.edges, self.exposure,
+                                   self.outcome, tuple(adjust))
+
+
+def _parse_edge(e) -> tuple[str, str]:
+    if isinstance(e, (tuple, list)):
+        if len(e) != 2 or not all(str(p).strip() for p in e):
+            raise ValueError("edge must be a pair of node names: %r" % (e,))
+        return (str(e[0]).strip(), str(e[1]).strip())
+    parts = [p.strip() for p in str(e).split("->")]
+    if len(parts) != 2 or not all(parts):
+        raise ValueError("edge must look like 'A -> B': %s" % e)
+    return (parts[0], parts[1])
+
+
+def causal_dag(edges, exposure: str, outcome: str,
+               latent=()) -> CausalDag:
+    """Build a DAG from edges, rejecting cycles.
+
+    `edges` may be ``"A -> B"`` strings or ``(from, to)`` pairs. The
+    exposure and the outcome must both appear in the graph: a DAG whose
+    exposure is not in it cannot identify anything, and saying so here
+    beats an empty adjustment set later.
+    """
+    if isinstance(edges, str):
+        edges = [edges]
+    em = [_parse_edge(e) for e in edges]
+    if not em:
+        raise ValueError("`edges` must contain at least one edge")
+    nodes: list[str] = []
+    for u, v in em:
+        for n in (u, v):
+            if n not in nodes:
+                nodes.append(n)
+    if exposure not in nodes:
+        raise ValueError("exposure not in graph: %s" % exposure)
+    if outcome not in nodes:
+        raise ValueError("outcome not in graph: %s" % outcome)
+
+    # Acyclicity by Kahn's algorithm, as the R side does. Counting the
+    # nodes it can retire is the proof: anything left over is in a cycle.
+    indeg = {n: 0 for n in nodes}
+    for _, v in em:
+        indeg[v] += 1
+    queue = [n for n in nodes if indeg[n] == 0]
+    seen = 0
+    while queue:
+        v = queue.pop(0)
+        seen += 1
+        for w in [b for a, b in em if a == v]:
+            indeg[w] -= 1
+            if indeg[w] == 0:
+                queue.append(w)
+    if seen != len(nodes):
+        raise ValueError("graph has a cycle")
+
+    if isinstance(latent, str):
+        latent = [latent]
+    return CausalDag(nodes=nodes, edges=em, exposure=exposure,
+                     outcome=outcome, latent=list(latent))
+
+
+def mrm_dags() -> dict[str, CausalDag]:
+    """The bundled MRM starting-point graphs.
+
+    `placement`: race, prior record and age are common causes of both
+    the placement decision and the outcome, so comparing outcomes by
+    placement without adjusting for them confounds the three.
+
+    `use_of_force`: neighbourhood and race cause both police contact and
+    force, so force conditional on contact is not the effect of contact.
+    """
+    return {
+        "placement": causal_dag(
+            [
+                "race -> placement", "race -> outcome",
+                "prior_record -> placement", "prior_record -> outcome",
+                "age -> placement", "age -> outcome",
+                "placement -> outcome",
+            ],
+            exposure="placement", outcome="outcome"),
+        "use_of_force": causal_dag(
+            [
+                "neighbourhood -> police_contact",
+                "neighbourhood -> force",
+                "race -> police_contact", "race -> force",
+                "police_contact -> force",
+            ],
+            exposure="police_contact", outcome="force"),
+    }

tests/test_mrm_dags.py

@@ -0,0 +1,102 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Causal DAGs for MRM, and the bundled structures.
+
+Parity with rmorie's R/dag_native.R. The back-door assertions are
+graph-theory facts about these specific graphs, independently checkable
+by hand, so they can fail.
+"""
+
+import pytest
+
+import morie
+
+
+def test_edges_parse_from_arrows_or_pairs():
+    a = morie.causal_dag(["x -> y"], exposure="x", outcome="y")
+    b = morie.causal_dag([("x", "y")], exposure="x", outcome="y")
+    assert a.edges == b.edges == [("x", "y")]
+    assert a.nodes == ["x", "y"]
+    # whitespace around the arrow is not significant
+    c = morie.causal_dag(["  x->y  "], exposure="x", outcome="y")
+    assert c.edges == [("x", "y")]
+    # a lone string is one edge, not a sequence of characters
+    d = morie.causal_dag("x -> y", exposure="x", outcome="y")
+    assert d.edges == [("x", "y")]
+
+
+def test_a_cycle_is_rejected():
+    with pytest.raises(ValueError, match="cycle"):
+        morie.causal_dag(["a -> b", "b -> c", "c -> a"],
+                         exposure="a", outcome="c")
+    # a diamond is acyclic and must be accepted
+    g = morie.causal_dag(["a -> b", "a -> c", "b -> d", "c -> d"],
+                         exposure="a", outcome="d")
+    assert len(g.nodes) == 4
+
+
+def test_exposure_and_outcome_must_be_in_the_graph():
+    with pytest.raises(ValueError, match="exposure not in graph"):
+        morie.causal_dag(["a -> b"], exposure="zzz", outcome="b")
+    with pytest.raises(ValueError, match="outcome not in graph"):
+        morie.causal_dag(["a -> b"], exposure="a", outcome="zzz")
+    with pytest.raises(ValueError, match="at least one edge"):
+        morie.causal_dag([], exposure="a", outcome="b")
+    with pytest.raises(ValueError, match="'A -> B'"):
+        morie.causal_dag(["a ~ b"], exposure="a", outcome="b")
+
+
+def test_parents_and_children():
+    g = morie.mrm_dags()["placement"]
+    assert sorted(g.parents("outcome")) == \
+        ["age", "placement", "prior_record", "race"]
+    assert g.children("race") == ["placement", "outcome"]
+    assert g.parents("race") == []
+
+
+def test_bundled_dags_match_rmorie():
+    d = morie.mrm_dags()
+    assert sorted(d) == ["placement", "use_of_force"]
+
+    p = d["placement"]
+    assert p.exposure == "placement" and p.outcome == "outcome"
+    assert sorted(p.nodes) == ["age", "outcome", "placement",
+                               "prior_record", "race"]
+    assert sorted("%s>%s" % e for e in p.edges) == [
+        "age>outcome", "age>placement", "placement>outcome",
+        "prior_record>outcome", "prior_record>placement",
+        "race>outcome", "race>placement"]
+
+    u = d["use_of_force"]
+    assert u.exposure == "police_contact" and u.outcome == "force"
+    assert sorted(u.nodes) == ["force", "neighbourhood", "police_contact",
+                               "race"]
+    assert sorted("%s>%s" % e for e in u.edges) == [
+        "neighbourhood>force", "neighbourhood>police_contact",
+        "police_contact>force", "race>force", "race>police_contact"]
+
+
+def test_the_common_causes_are_what_must_be_adjusted():
+    # THE SUBSTANCE of both bundled graphs: the confounders are common
+    # causes of exposure and outcome, so the unadjusted comparison is
+    # confounded and the full set closes the back doors.
+    p = morie.mrm_dags()["placement"]
+    assert p.backdoor(()).satisfied is False
+    assert p.backdoor(("race", "prior_record", "age")).satisfied is True
+    # a proper subset leaves a back door open
+    assert p.backdoor(("race",)).satisfied is False
+
+    u = morie.mrm_dags()["use_of_force"]
+    assert u.backdoor(()).satisfied is False
+    assert u.backdoor(("neighbourhood", "race")).satisfied is True
+    # a bare string is one node, not a sequence of characters
+    assert u.backdoor("race").satisfied is False
+
+
+def test_edges_are_the_representation_the_rest_of_morie_takes():
+    # dag_plot and fn.bdcrt both take [(from, to)], so a graph built here
+    # needs no conversion.
+    g = morie.mrm_dags()["placement"]
+    assert all(isinstance(e, tuple) and len(e) == 2 for e in g.edges)
+    from morie.fn.bdcrt import backdoor_criterion
+    assert backdoor_criterion(g.edges, g.exposure, g.outcome,
+                              ("race", "prior_record", "age")).satisfied