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 +10 -0
- agoutis-0.1.0/README.md +0 -0
- agoutis-0.1.0/pyproject.toml +41 -0
- agoutis-0.1.0/src/agoutis/__init__.py +88 -0
- agoutis-0.1.0/src/agoutis/causal.py +209 -0
- agoutis-0.1.0/src/agoutis/distributions.py +190 -0
- agoutis-0.1.0/src/agoutis/execution.py +501 -0
- agoutis-0.1.0/src/agoutis/expressions.py +785 -0
- agoutis-0.1.0/src/agoutis/model.py +908 -0
- agoutis-0.1.0/src/agoutis/unroll.py +640 -0
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
|
+
|
agoutis-0.1.0/README.md
ADDED
|
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
|