agoutis 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
agoutis-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,10 @@
1
+ Metadata-Version: 2.3
2
+ Name: agoutis
3
+ Version: 0.1.0
4
+ Summary: Declarative structural causal models and counterfactual simulation on NumPy.
5
+ Requires-Dist: numpy>=1.26
6
+ Requires-Dist: pandas>=2.0 ; extra == 'pandas'
7
+ Requires-Python: >=3.11
8
+ Provides-Extra: pandas
9
+ Description-Content-Type: text/markdown
10
+
File without changes
@@ -0,0 +1,41 @@
1
+ [build-system]
2
+ requires = ["uv_build>=0.11.0,<0.12"]
3
+ build-backend = "uv_build"
4
+
5
+ [project]
6
+ name = "agoutis"
7
+ version = "0.1.0"
8
+ description = "Declarative structural causal models and counterfactual simulation on NumPy."
9
+ readme = "README.md"
10
+ requires-python = ">=3.11"
11
+ dependencies = [
12
+ "numpy>=1.26",
13
+ ]
14
+
15
+ [project.optional-dependencies]
16
+ pandas = [
17
+ "pandas>=2.0",
18
+ ]
19
+
20
+ [dependency-groups]
21
+ dev = [
22
+ "pandas>=2.0",
23
+ "pytest>=8.0",
24
+ "ruff>=0.11",
25
+ ]
26
+
27
+ [tool.ruff]
28
+ target-version = "py311"
29
+ line-length = 90
30
+ src = ["src"]
31
+ extend-exclude = ["tests"]
32
+
33
+ [tool.ruff.lint]
34
+ select = ["E", "W", "F", "B", "UP", "I", "SIM", "C90", "S", "PTH", "RUF"]
35
+
36
+ [tool.ruff.format]
37
+ docstring-code-format = true
38
+
39
+ [tool.pyrefly]
40
+ project-includes = ["src"]
41
+ project-excludes = ["**/tests", "**/.venv"]
@@ -0,0 +1,88 @@
1
+ """
2
+ Define and query structural causal models (SCMs) on NumPy arrays.
3
+
4
+ Nomenclature:
5
+ unit one simulated individual or Monte Carlo draw across the model
6
+ equation the structural assignment defining one variable in the model
7
+ latent variable an unobserved variable marked with `latent(...)` (omitted from
8
+ `sample()` outputs and candidate backdoor adjustment sets)
9
+ static variable a variable computed once per unit, constant across time steps
10
+ dynamic variable a variable recomputed at each step `0..steps - 1` because it
11
+ uses `.lag()`, `t`, `per_step()`, or an upstream dynamic variable
12
+ world a model paired with an ordered sequence of `do()` interventions
13
+ and `given()` conditioning events
14
+ natural value what a variable's structural equation produces before an
15
+ intervention on that variable rewrites it
16
+ node key a `(variable_name, step)` pair (`step=None` for static variables)
17
+ identifying one concrete random quantity in an unrolled graph
18
+
19
+ Example:
20
+ from agoutis import *
21
+
22
+ m = SCM(
23
+ U=latent(N()),
24
+ Z=Bern(sigmoid(var("U"))),
25
+ X=Bern(sigmoid(2 * var("Z") - 1)),
26
+ Y=3 * var("X") + 2 * var("Z") + var("U") + N(0, 0.5),
27
+ )
28
+
29
+ m.sample(1000) # observational DataFrame
30
+ m.given(var("X") == 1).E("Y") # rung 1: conditioning
31
+ m.do(X=1).E("Y") - m.do(X=0).E("Y") # rung 2: intervention (ATE)
32
+ m.given(var("X") == 1, var("Y") > 4).do(X=0).P(var("Y") > 4) # rung 3: counterfactual
33
+ m.dsep("X", "U", "Z"), m.backdoor("X", "Y", "Z"), m.adjustment("X", "Y")
34
+ m.sweep(X=[0, 0.5, 1]).E("Y") # grid of interventions
35
+ """
36
+
37
+ from numpy import clip, cos, exp, log, maximum, minimum, sin, sqrt, tanh, where
38
+
39
+ from agoutis.distributions import Bern, Cat, Data, Exp, N, Unif
40
+ from agoutis.expressions import (
41
+ Expr,
42
+ LatentSpec,
43
+ Var,
44
+ VarSpec,
45
+ fn,
46
+ latent,
47
+ per_step,
48
+ per_unit,
49
+ relu,
50
+ sigmoid,
51
+ t,
52
+ var,
53
+ )
54
+ from agoutis.model import DEFAULT_STEPS, SCM, Sweep
55
+
56
+ __all__ = [
57
+ "DEFAULT_STEPS",
58
+ "SCM",
59
+ "Bern",
60
+ "Cat",
61
+ "Data",
62
+ "Exp",
63
+ "Expr",
64
+ "LatentSpec",
65
+ "N",
66
+ "Sweep",
67
+ "Unif",
68
+ "Var",
69
+ "VarSpec",
70
+ "clip",
71
+ "cos",
72
+ "exp",
73
+ "fn",
74
+ "latent",
75
+ "log",
76
+ "maximum",
77
+ "minimum",
78
+ "per_step",
79
+ "per_unit",
80
+ "relu",
81
+ "sigmoid",
82
+ "sin",
83
+ "sqrt",
84
+ "t",
85
+ "tanh",
86
+ "var",
87
+ "where",
88
+ ]
@@ -0,0 +1,209 @@
1
+ """
2
+ Causal graph inspection, d-separation, backdoor adjustment, and Graphviz rendering.
3
+
4
+ All graph identification routines operate on `NodeKey` parent maps from the unrolled
5
+ (or intervened) DAG, using iterative traversals so deep time-series models never
6
+ exceed Python's recursion limit. Public results return plain node name strings (`'Z'`,
7
+ `'ERK[0]'`) so standard Python `in`, `==`, `set`, and `sorted()` operations work
8
+ without triggering symbolic `Expr` comparisons.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ from collections.abc import Callable, Collection, Iterable, Mapping
14
+ from itertools import combinations
15
+
16
+ from agoutis.expressions import Lag, NodeKey, Var
17
+ from agoutis.unroll import UnrolledGraph
18
+
19
+
20
+ def find_ancestors(
21
+ roots: Iterable[NodeKey], parent_map: Mapping[NodeKey, Collection[NodeKey]]
22
+ ) -> set[NodeKey]:
23
+ """Return `roots` together with all of their upstream ancestors in `parent_map`."""
24
+ ancestors: set[NodeKey] = set()
25
+ pending = list(roots)
26
+ while pending:
27
+ node = pending.pop()
28
+ if node not in ancestors:
29
+ ancestors.add(node)
30
+ pending.extend(parent_map[node])
31
+ return ancestors
32
+
33
+
34
+ def build_child_map(
35
+ parent_map: Mapping[NodeKey, Collection[NodeKey]],
36
+ ) -> dict[NodeKey, list[NodeKey]]:
37
+ """Invert `parent_map` into `{parent: [children...]}`."""
38
+ children: dict[NodeKey, list[NodeKey]] = {}
39
+ for node, parents in parent_map.items():
40
+ for parent in parents:
41
+ children.setdefault(parent, []).append(node)
42
+ return children
43
+
44
+
45
+ def find_descendants(
46
+ roots: Iterable[NodeKey], child_map: Mapping[NodeKey, Collection[NodeKey]]
47
+ ) -> set[NodeKey]:
48
+ """Return all strict downstream descendants of `roots`."""
49
+ descendants: set[NodeKey] = set()
50
+ pending = list(roots)
51
+ while pending:
52
+ for child in child_map.get(pending.pop(), ()):
53
+ if child not in descendants:
54
+ descendants.add(child)
55
+ pending.append(child)
56
+ return descendants
57
+
58
+
59
+ def is_d_separated(
60
+ x_keys: list[NodeKey],
61
+ y_keys: list[NodeKey],
62
+ given_keys: set[NodeKey],
63
+ parent_map: Mapping[NodeKey, Collection[NodeKey]],
64
+ ) -> bool:
65
+ """
66
+ Test whether `x_keys` and `y_keys` are d-separated given `given_keys` via the
67
+ Bayes-Ball / moralised ancestral graph criterion.
68
+
69
+ 1. Restrict the DAG to the ancestral closure of `X | Y | Z`.
70
+ 2. Moralise (marry co-parents of every node in the ancestral subgraph) and drop
71
+ edge directions.
72
+ 3. Check whether any path from `X` reaches `Y` without passing through `Z`.
73
+ """
74
+ ancestors = find_ancestors([*x_keys, *y_keys, *given_keys], parent_map)
75
+ moral_adj: dict[NodeKey, set[NodeKey]] = {node: set() for node in ancestors}
76
+ for node in ancestors:
77
+ parents = parent_map[node]
78
+ for parent in parents:
79
+ moral_adj[node].add(parent)
80
+ moral_adj[parent].add(node)
81
+ for p1, p2 in combinations(parents, 2):
82
+ moral_adj[p1].add(p2)
83
+ moral_adj[p2].add(p1)
84
+
85
+ visited = set(x_keys) - given_keys
86
+ pending = list(visited)
87
+ while pending:
88
+ current = pending.pop()
89
+ for neighbour in moral_adj[current] - given_keys - visited:
90
+ visited.add(neighbour)
91
+ pending.append(neighbour)
92
+
93
+ return visited.isdisjoint(y_keys)
94
+
95
+
96
+ def satisfies_backdoor(
97
+ x_keys: list[NodeKey],
98
+ y_keys: list[NodeKey],
99
+ z_keys: set[NodeKey],
100
+ parent_map: Mapping[NodeKey, Collection[NodeKey]],
101
+ child_map: Mapping[NodeKey, Collection[NodeKey]],
102
+ ) -> bool:
103
+ """
104
+ Check Pearl's backdoor criterion for adjustment set `z_keys` on `X -> Y`:
105
+ 1. No node in `Z` is a descendant of `X`.
106
+ 2. `Z` d-separates `X` and `Y` in the mutilated graph `G_{\\underline{X}}` where
107
+ all outgoing edges from `X` are removed.
108
+ """
109
+ if z_keys & find_descendants(x_keys, child_map):
110
+ return False
111
+ x_set = set(x_keys)
112
+ mutilated_parents = {
113
+ node: [p for p in parents if p not in x_set]
114
+ for node, parents in parent_map.items()
115
+ }
116
+ return is_d_separated(x_keys, y_keys, z_keys, mutilated_parents)
117
+
118
+
119
+ _DOT_KEYWORDS = frozenset({"node", "edge", "graph", "digraph", "subgraph", "strict"})
120
+
121
+
122
+ def _prune_adjustment_candidates(
123
+ candidates: list[NodeKey],
124
+ x_keys: list[NodeKey],
125
+ y_keys: list[NodeKey],
126
+ parent_map: Mapping[NodeKey, Collection[NodeKey]],
127
+ child_map: Mapping[NodeKey, Collection[NodeKey]],
128
+ ) -> set[str] | None:
129
+ if not satisfies_backdoor(x_keys, y_keys, set(candidates), parent_map, child_map):
130
+ return None
131
+ minimal = list(candidates)
132
+ for key in candidates:
133
+ reduced = [other for other in minimal if other != key]
134
+ if satisfies_backdoor(x_keys, y_keys, set(reduced), parent_map, child_map):
135
+ minimal = reduced
136
+ return {str(key) for key in minimal}
137
+
138
+
139
+ def find_adjustment_set(
140
+ all_keys: Collection[NodeKey],
141
+ latents: Collection[str],
142
+ x_keys: list[NodeKey],
143
+ y_keys: list[NodeKey],
144
+ parent_map: Mapping[NodeKey, Collection[NodeKey]],
145
+ child_map: Mapping[NodeKey, Collection[NodeKey]],
146
+ ) -> set[str] | None:
147
+ """
148
+ Find a valid observed backdoor adjustment set for `X -> Y`, or None if none exists.
149
+
150
+ Searches for a minimum-cardinality set when `<= 12` observed candidate ancestors
151
+ exist, and prunes greedily to an inclusion-minimal set on larger graphs.
152
+ """
153
+ ancestors = find_ancestors([*x_keys, *y_keys], parent_map)
154
+ excluded = set(x_keys) | set(y_keys) | find_descendants(x_keys, child_map)
155
+ candidates = [
156
+ key
157
+ for key in all_keys
158
+ if key in ancestors and key.name not in latents and key not in excluded
159
+ ]
160
+
161
+ if len(candidates) > 12:
162
+ return _prune_adjustment_candidates(
163
+ candidates, x_keys, y_keys, parent_map, child_map
164
+ )
165
+
166
+ for size in range(len(candidates) + 1):
167
+ for subset in combinations(candidates, size):
168
+ if satisfies_backdoor(x_keys, y_keys, set(subset), parent_map, child_map):
169
+ return {str(key) for key in subset}
170
+ return None
171
+
172
+
173
+ def _quote_dot_id(identifier: str) -> str:
174
+ if identifier.isidentifier() and identifier.lower() not in _DOT_KEYWORDS:
175
+ return identifier
176
+ escaped = identifier.replace("\\", "\\\\").replace('"', '\\"')
177
+ return f'"{escaped}"'
178
+
179
+
180
+ def format_dot(
181
+ equations: Mapping[str, object],
182
+ latents: Collection[str],
183
+ graph: UnrolledGraph,
184
+ intervened_names: Collection[str],
185
+ edges: Iterable[tuple[str, str]],
186
+ get_mechanism_inputs: Callable[[str], list[Var | Lag]],
187
+ ) -> str:
188
+ """Render the causal graph in Graphviz DOT notation."""
189
+ lines = [
190
+ *(f" {_quote_dot_id(name)} [style=dashed]" for name in equations if name in latents),
191
+ *(f" {_quote_dot_id(name)} [shape=box]" for name in intervened_names),
192
+ ]
193
+ if graph.dynamic_vars:
194
+ for name in equations:
195
+ for inp in get_mechanism_inputs(name):
196
+ if isinstance(inp, Lag):
197
+ attr = f' [style=dashed, label="t-{inp.steps}"]'
198
+ elif inp.step is not None:
199
+ attr = f' [style=dotted, label="[{inp.step}]"]'
200
+ else:
201
+ attr = ""
202
+ lines.append(
203
+ f" {_quote_dot_id(inp.name)} -> {_quote_dot_id(name)}{attr}"
204
+ )
205
+ else:
206
+ lines.extend(
207
+ f" {_quote_dot_id(src)} -> {_quote_dot_id(dst)}" for src, dst in edges
208
+ )
209
+ return "digraph {\n" + "\n".join(lines) + "\n}"
@@ -0,0 +1,190 @@
1
+ """
2
+ Reparameterised probability distributions, empirical data columns, and RNG streams.
3
+
4
+ Every distribution is expressed as a deterministic function `f(noise, *params)` of an
5
+ exogenous `Noise` node (`normal`, `uniform`, or dataset row indices). This makes
6
+ abduction-action-prediction counterfactuals exact: `given()` filters unit indices,
7
+ `do()` rewires structural equations, and distinct worlds with the same seed read the
8
+ same underlying exogenous draws.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ from collections.abc import Callable
14
+ from hashlib import blake2b
15
+ from itertools import accumulate
16
+ from typing import Any
17
+
18
+ import numpy as np
19
+
20
+ from agoutis.expressions import (
21
+ BoundNoise,
22
+ CallOp,
23
+ Expr,
24
+ LatentSpec,
25
+ Noise,
26
+ NoiseDistribution,
27
+ VarSpec,
28
+ lift_expr,
29
+ )
30
+
31
+ try:
32
+ import pandas as pd
33
+ except ImportError:
34
+ pd = None
35
+
36
+
37
+ def _distribution(
38
+ name: str,
39
+ noise_kind: NoiseDistribution,
40
+ transform_fn: Callable[..., Any],
41
+ *params: Any,
42
+ ) -> CallOp:
43
+ args = (Noise(noise_kind), *(lift_expr(param) for param in params))
44
+ return CallOp(name, transform_fn, args, hidden_leading_args=1)
45
+
46
+
47
+ def N(mu: Any = 0, sd: Any = 1) -> Expr:
48
+ """Normal distribution with mean `mu` and standard deviation `sd`."""
49
+ return _distribution("N", "normal", lambda u, m, s: m + s * u, mu, sd)
50
+
51
+
52
+ def Unif(a: Any = 0, b: Any = 1) -> Expr:
53
+ """Continuous uniform distribution on `[a, b]`."""
54
+ return _distribution("Unif", "uniform", lambda u, lo, hi: lo + (hi - lo) * u, a, b)
55
+
56
+
57
+ def Bern(p: Any = 0.5) -> Expr:
58
+ """Bernoulli `{0, 1}` distribution with success probability `p`."""
59
+ return _distribution("Bern", "uniform", lambda u, prob: (u < prob).astype(int), p)
60
+
61
+
62
+ def Exp(rate: Any = 1) -> Expr:
63
+ """Exponential distribution with rate parameter `rate`."""
64
+ return _distribution("Exp", "uniform", lambda u, r: -np.log1p(-u) / r, rate)
65
+
66
+
67
+ def _eval_categorical(u: Any, *weights: Any) -> Any:
68
+ if any(np.any(np.asarray(w) < 0) for w in weights):
69
+ raise ValueError("Cat() weights must be non-negative")
70
+ total = sum(weights)
71
+ if np.any(np.asarray(total) <= 0):
72
+ raise ValueError("Cat() weights must have a positive sum")
73
+ scaled = u * total
74
+ category: Any = np.zeros_like(scaled, dtype=int)
75
+ for cumulative in accumulate(weights[:-1]):
76
+ category = category + (scaled >= cumulative).astype(int)
77
+ return category
78
+
79
+
80
+ def Cat(*p: Any) -> Expr:
81
+ """
82
+ Categorical distribution over `0..k - 1` with unnormalised weights `p`.
83
+
84
+ Accepts either positional weights `Cat(0.2, 0.3, 0.5)` or a single sequence
85
+ `Cat([0.2, 0.3, 0.5])`. Weights may be symbolic `Expr`s.
86
+ """
87
+ weights = p[0] if len(p) == 1 and isinstance(p[0], (list, tuple)) else p
88
+ if not weights:
89
+ raise ValueError("Cat() requires at least one category weight")
90
+ return _distribution("Cat", "uniform", _eval_categorical, *weights)
91
+
92
+
93
+ def Data(*cols: Any) -> Expr | list[Expr]:
94
+ """
95
+ Empirical column inputs, one row per unit.
96
+
97
+ Use `X = Data(arr)` for a single column, or `A, B = Data(df.a, df.b)` to keep
98
+ multiple columns row-paired via a shared row-index stream. Calling `sample(n)`
99
+ with `n == len(arr)` uses the rows in exact order; otherwise rows are resampled
100
+ with replacement.
101
+ """
102
+ if not cols:
103
+ raise ValueError("Data() requires at least one column")
104
+ arrays = [np.asarray(col) for col in cols]
105
+ lengths = {len(arr) for arr in arrays}
106
+ if len(lengths) != 1:
107
+ raise ValueError("All Data() columns must have the same length")
108
+ row_count = next(iter(lengths))
109
+ if row_count == 0:
110
+ raise ValueError("Data() columns cannot be empty")
111
+
112
+ row_stream = Noise("rows", num_rows=row_count)
113
+ outputs: list[Expr] = [
114
+ CallOp(
115
+ f"Data[{len(arr)}]",
116
+ lambda indices, col=arr: col[indices],
117
+ (row_stream,),
118
+ is_label_only=True,
119
+ )
120
+ for arr in arrays
121
+ ]
122
+ return outputs[0] if len(outputs) == 1 else outputs
123
+
124
+
125
+ def coerce_input_value(value: Any) -> Expr:
126
+ """
127
+ Convert an assigned or intervened value into an `Expr`.
128
+
129
+ 1D sequences, NumPy arrays, and pandas Series are wrapped in `Data(arr)` so
130
+ per-unit empirical arrays can be passed directly to `SCM(X=arr)` or `m.do(X=arr)`.
131
+ """
132
+ if isinstance(value, (Expr, LatentSpec, VarSpec)):
133
+ return lift_expr(value)
134
+ if pd is not None and isinstance(value, pd.Series):
135
+ candidate: Any = value.to_numpy()
136
+ elif isinstance(value, (list, tuple)):
137
+ candidate = np.asarray(value)
138
+ else:
139
+ candidate = value
140
+ if isinstance(candidate, np.ndarray) and candidate.ndim == 1:
141
+ data_expr = Data(candidate)
142
+ if isinstance(data_expr, Expr):
143
+ return data_expr
144
+ return lift_expr(value)
145
+
146
+
147
+ # -- Deterministic counter-based noise streams --------------------------------
148
+
149
+
150
+ def sample_noise_array(
151
+ source: Noise, rng: np.random.Generator, count: int
152
+ ) -> np.ndarray:
153
+ """Draw `count` samples for `source` from `rng`."""
154
+ if source.kind == "normal":
155
+ return rng.standard_normal(count)
156
+ if source.kind == "uniform":
157
+ return rng.random(count)
158
+ num_rows = source.num_rows or 0
159
+ if count == num_rows:
160
+ return np.arange(count)
161
+ return rng.integers(num_rows, size=count)
162
+
163
+
164
+ def make_noise_drawer(
165
+ values: dict[Any, Any],
166
+ batch_size: int,
167
+ active_indices: np.ndarray | None,
168
+ root_seed: Any,
169
+ batch_index: int,
170
+ ) -> Callable[[BoundNoise], np.ndarray]:
171
+ """
172
+ Build a demand-driven noise drawer for one simulation batch.
173
+
174
+ Each `BoundNoise` term derives its own 128-bit Philox key from
175
+ `blake2b(repr((root_seed, batch_index, stream_id)))`, making draws independent
176
+ of evaluation order, graph pruning, and Python's randomised `HASHSEED`.
177
+ """
178
+
179
+ def draw(node: BoundNoise) -> np.ndarray:
180
+ if node.key not in values:
181
+ payload = repr((root_seed, batch_index, node.key.stream_id)).encode("utf-8")
182
+ digest = blake2b(payload, digest_size=16).digest()
183
+ bit_generator = np.random.Philox(key=int.from_bytes(digest, "little"))
184
+ raw = sample_noise_array(
185
+ node.source, np.random.Generator(bit_generator), batch_size
186
+ )
187
+ values[node.key] = raw if active_indices is None else raw[active_indices]
188
+ return values[node.key]
189
+
190
+ return draw