b-load 0.1.2__py3-none-any.whl
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.
- b_load-0.1.2.dist-info/METADATA +266 -0
- b_load-0.1.2.dist-info/RECORD +33 -0
- b_load-0.1.2.dist-info/WHEEL +5 -0
- b_load-0.1.2.dist-info/licenses/LICENSE +21 -0
- b_load-0.1.2.dist-info/top_level.txt +2 -0
- bload/__init__.py +10 -0
- bload/analysis.py +1 -0
- bload/background_knowledge.py +1 -0
- bload/counting_ci_tests.py +1 -0
- bload/data_generation.py +1 -0
- bload/evaluation.py +1 -0
- bload/load.py +1 -0
- bload/mb_by_mb.py +1 -0
- bload/pc.py +1 -0
- bload/real_data_applications/__init__.py +1 -0
- bload/real_data_applications/dream.py +1 -0
- bload/real_data_applications/sachs.py +1 -0
- bload/running.py +1 -0
- bload/utils.py +1 -0
- src/__init__.py +5 -0
- src/analysis.py +805 -0
- src/background_knowledge.py +283 -0
- src/counting_ci_tests.py +101 -0
- src/data_generation.py +185 -0
- src/evaluation.py +642 -0
- src/load.py +553 -0
- src/mb_by_mb.py +930 -0
- src/pc.py +341 -0
- src/real_data_applications/__init__.py +1 -0
- src/real_data_applications/dream.py +306 -0
- src/real_data_applications/sachs.py +202 -0
- src/running.py +1194 -0
- src/utils.py +106 -0
src/load.py
ADDED
|
@@ -0,0 +1,553 @@
|
|
|
1
|
+
"""
|
|
2
|
+
load.py — LOAD and b-LOAD causal effect estimation via local adjustment sets.
|
|
3
|
+
|
|
4
|
+
This module contains two groups of functions:
|
|
5
|
+
|
|
6
|
+
1. **LOAD (base)** — adapted from Shubert et al.'s implementation of the
|
|
7
|
+
Local Optimal Adjustment-set Discovery (LOAD) algorithm:
|
|
8
|
+
https://github.com/[shubert-et-al-repo]
|
|
9
|
+
Functions: ``Neighbors``, ``get_neighbors``, ``is_explicit_ancestor``,
|
|
10
|
+
``is_possible_ancestor``, ``is_amenable``, ``get_locally_valid_parent_sets``,
|
|
11
|
+
``load``.
|
|
12
|
+
|
|
13
|
+
2. **b-LOAD** — extension of LOAD that incorporates background knowledge so
|
|
14
|
+
that the graph used for adjustment-set identification is an MPDAG consistent
|
|
15
|
+
with prior causal constraints. Part of the b-LOAD algorithm introduced in
|
|
16
|
+
this work:
|
|
17
|
+
``load_in_mpdag``.
|
|
18
|
+
|
|
19
|
+
Graph encoding (shared throughout this module)
|
|
20
|
+
----------------------------------------------
|
|
21
|
+
``g[i, j] == -1`` → tail at i (i — j or i → j)
|
|
22
|
+
``g[i, j] == 1`` → head at i (j → i)
|
|
23
|
+
``g[i, j] == 0`` → no edge
|
|
24
|
+
|
|
25
|
+
An undirected edge i — j satisfies g[i,j] == g[j,i] == -1.
|
|
26
|
+
A directed edge i → j satisfies g[i,j] == -1 and g[j,i] == 1.
|
|
27
|
+
"""
|
|
28
|
+
|
|
29
|
+
from collections import defaultdict
|
|
30
|
+
from itertools import chain, combinations
|
|
31
|
+
from typing import Callable, NamedTuple, Optional, Sequence
|
|
32
|
+
|
|
33
|
+
import numpy as np
|
|
34
|
+
|
|
35
|
+
from src.mb_by_mb import mb_by_mb_alg, mb_by_mb_in_mpdag_alg
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
# ---------------------------------------------------------------------------
|
|
39
|
+
# LOAD (base) — adapted from Shubert et al.
|
|
40
|
+
# ---------------------------------------------------------------------------
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
class Neighbors(NamedTuple):
|
|
44
|
+
"""
|
|
45
|
+
Typed container for the three classes of neighbours a node can have in a
|
|
46
|
+
partially directed graph (PDAG / MPDAG).
|
|
47
|
+
|
|
48
|
+
.. note::
|
|
49
|
+
Part of the **LOAD** base implementation (Shubert et al.).
|
|
50
|
+
|
|
51
|
+
Attributes:
|
|
52
|
+
parents (set[int]): Nodes with a directed edge *into* the target
|
|
53
|
+
(parent → target).
|
|
54
|
+
children (set[int]): Nodes with a directed edge *out of* the target
|
|
55
|
+
(target → child).
|
|
56
|
+
unoriented (set[int]): Nodes connected by an undirected edge
|
|
57
|
+
(target — neighbour).
|
|
58
|
+
"""
|
|
59
|
+
|
|
60
|
+
parents: set[int]
|
|
61
|
+
children: set[int]
|
|
62
|
+
unoriented: set[int]
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
def get_neighbors(g: np.ndarray, x: int) -> Neighbors:
|
|
66
|
+
"""
|
|
67
|
+
Extract the parents, children, and undirected neighbours of node ``x``
|
|
68
|
+
from the local PDAG / MPDAG ``g``.
|
|
69
|
+
|
|
70
|
+
.. note::
|
|
71
|
+
Adapted from Shubert et al.'s LOAD implementation.
|
|
72
|
+
|
|
73
|
+
Args:
|
|
74
|
+
g (np.ndarray): Local graph adjacency matrix (full node-index space).
|
|
75
|
+
x (int): Index of the node whose neighbourhood is to be retrieved.
|
|
76
|
+
|
|
77
|
+
Returns:
|
|
78
|
+
Neighbors: Named tuple with three sets — ``parents``, ``children``,
|
|
79
|
+
and ``unoriented``.
|
|
80
|
+
"""
|
|
81
|
+
parents = set(np.where((g[x] == 1) & (g[:, x] == -1))[0])
|
|
82
|
+
children = set(np.where((g[x] == -1) & (g[:, x] == 1))[0])
|
|
83
|
+
unoriented = set(np.where((g[x] == -1) & (g[:, x] == -1))[0])
|
|
84
|
+
return Neighbors(parents, children, unoriented)
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
def is_explicit_ancestor(
|
|
88
|
+
x: int,
|
|
89
|
+
y: int,
|
|
90
|
+
g: np.ndarray,
|
|
91
|
+
ci_test: Callable[[int, int, Sequence[int]], float],
|
|
92
|
+
alpha: float,
|
|
93
|
+
) -> bool:
|
|
94
|
+
"""
|
|
95
|
+
Test whether ``x`` is an *explicit* ancestor of ``y`` in the local graph
|
|
96
|
+
``g``.
|
|
97
|
+
|
|
98
|
+
A node ``x`` is an explicit ancestor of ``y`` if:
|
|
99
|
+
|
|
100
|
+
* ``y`` is a *child* of ``x`` in ``g`` (direct directed edge x → y), or
|
|
101
|
+
* ``y`` is not adjacent to ``x`` in ``g`` AND the CI test rejects
|
|
102
|
+
independence of ``x`` and ``y`` given all parents and undirected
|
|
103
|
+
neighbours of ``x`` (i.e., the parents/unoriented set is not a
|
|
104
|
+
d-separating set, suggesting a directed path from x to y).
|
|
105
|
+
|
|
106
|
+
If ``y`` is a parent or undirected neighbour of ``x``, the function
|
|
107
|
+
returns ``False`` immediately (no directed path from x to y is implied).
|
|
108
|
+
|
|
109
|
+
.. note::
|
|
110
|
+
Adapted from Shubert et al.'s LOAD implementation.
|
|
111
|
+
|
|
112
|
+
Args:
|
|
113
|
+
x (int): Candidate ancestor node.
|
|
114
|
+
y (int): Candidate descendant node.
|
|
115
|
+
g (np.ndarray): Local PDAG / MPDAG around ``x``.
|
|
116
|
+
ci_test (Callable[[int, int, Sequence[int]], float]): CI test returning
|
|
117
|
+
a p-value given (X, Y, conditioning_set).
|
|
118
|
+
alpha (float): Significance level.
|
|
119
|
+
|
|
120
|
+
Returns:
|
|
121
|
+
bool: ``True`` if ``x`` is identified as an explicit ancestor of ``y``.
|
|
122
|
+
"""
|
|
123
|
+
neighbors = get_neighbors(g, x)
|
|
124
|
+
if y in neighbors.children:
|
|
125
|
+
return True
|
|
126
|
+
elif y in neighbors.parents | neighbors.unoriented:
|
|
127
|
+
return False
|
|
128
|
+
return ci_test(x, y, neighbors.parents | neighbors.unoriented) < alpha
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
def is_possible_ancestor(
|
|
132
|
+
x: int,
|
|
133
|
+
y: int,
|
|
134
|
+
g: np.ndarray,
|
|
135
|
+
ci_test: Callable[[int, int, Sequence[int]], float],
|
|
136
|
+
alpha: float,
|
|
137
|
+
) -> bool:
|
|
138
|
+
"""
|
|
139
|
+
Test whether ``x`` is a *possible* ancestor of ``y`` in the local graph
|
|
140
|
+
``g``.
|
|
141
|
+
|
|
142
|
+
A node ``x`` is a possible ancestor of ``y`` if:
|
|
143
|
+
|
|
144
|
+
* ``y`` is a child or undirected neighbour of ``x`` (a directed path
|
|
145
|
+
x → y is possible), or
|
|
146
|
+
* ``y`` is not adjacent to ``x`` AND the CI test rejects independence of
|
|
147
|
+
``x`` and ``y`` given only the *parents* of ``x`` (the more conservative
|
|
148
|
+
conditioning set, compared to :func:`is_explicit_ancestor`).
|
|
149
|
+
|
|
150
|
+
If ``y`` is a parent of ``x``, the function returns ``False`` (``x``
|
|
151
|
+
cannot be an ancestor of its own parent in a DAG).
|
|
152
|
+
|
|
153
|
+
.. note::
|
|
154
|
+
Adapted from Shubert et al.'s LOAD implementation.
|
|
155
|
+
|
|
156
|
+
Args:
|
|
157
|
+
x (int): Candidate ancestor node.
|
|
158
|
+
y (int): Candidate descendant node.
|
|
159
|
+
g (np.ndarray): Local PDAG / MPDAG around ``x``.
|
|
160
|
+
ci_test (Callable[[int, int, Sequence[int]], float]): CI test returning
|
|
161
|
+
a p-value.
|
|
162
|
+
alpha (float): Significance level.
|
|
163
|
+
|
|
164
|
+
Returns:
|
|
165
|
+
bool: ``True`` if ``x`` cannot be ruled out as an ancestor of ``y``.
|
|
166
|
+
"""
|
|
167
|
+
neighbors = get_neighbors(g, x)
|
|
168
|
+
if y in neighbors.children | neighbors.unoriented:
|
|
169
|
+
return True
|
|
170
|
+
elif y in neighbors.parents:
|
|
171
|
+
return False
|
|
172
|
+
return ci_test(x, y, neighbors.parents) < alpha
|
|
173
|
+
|
|
174
|
+
|
|
175
|
+
def is_amenable(
|
|
176
|
+
x: int,
|
|
177
|
+
y: int,
|
|
178
|
+
v: int,
|
|
179
|
+
g: np.ndarray,
|
|
180
|
+
ci_test: Callable[[int, int, Sequence[int]], float],
|
|
181
|
+
alpha: float,
|
|
182
|
+
) -> bool:
|
|
183
|
+
"""
|
|
184
|
+
Test the *local amenability* condition for an undirected neighbour ``v``
|
|
185
|
+
of the treatment node ``x`` with respect to outcome ``y``.
|
|
186
|
+
|
|
187
|
+
A graph is amenable for the adjustment formula (x → y) if no undirected
|
|
188
|
+
neighbour of ``x`` has an undirected or directed path to ``y`` that does
|
|
189
|
+
not pass through ``x``. This function checks this condition locally for a
|
|
190
|
+
single candidate ``v``:
|
|
191
|
+
|
|
192
|
+
* If ``y`` is adjacent to ``v`` in ``g[v]``, the condition fails (``v``
|
|
193
|
+
has a direct path to ``y`` not through ``x``).
|
|
194
|
+
* Otherwise, the CI test checks whether ``v`` and ``y`` are independent
|
|
195
|
+
given parents(v) ∪ {x}. If they are independent (p-value ≥ alpha),
|
|
196
|
+
``v`` does not contradict amenability.
|
|
197
|
+
|
|
198
|
+
.. note::
|
|
199
|
+
Adapted from Shubert et al.'s LOAD implementation.
|
|
200
|
+
|
|
201
|
+
Args:
|
|
202
|
+
x (int): Treatment node index.
|
|
203
|
+
y (int): Outcome node index.
|
|
204
|
+
v (int): An undirected neighbour of ``x`` to be checked.
|
|
205
|
+
g (np.ndarray): Local PDAG / MPDAG around ``v``.
|
|
206
|
+
ci_test (Callable[[int, int, Sequence[int]], float]): CI test returning
|
|
207
|
+
a p-value.
|
|
208
|
+
alpha (float): Significance level.
|
|
209
|
+
|
|
210
|
+
Returns:
|
|
211
|
+
bool: ``True`` if ``v`` does *not* violate the amenability condition
|
|
212
|
+
(i.e., ``v`` is "safe" for adjustment through ``x``).
|
|
213
|
+
"""
|
|
214
|
+
neighbors = get_neighbors(g, v)
|
|
215
|
+
if y in neighbors.children | neighbors.unoriented | neighbors.parents:
|
|
216
|
+
return False
|
|
217
|
+
return ci_test(v, y, neighbors.parents | {x}) >= alpha
|
|
218
|
+
|
|
219
|
+
|
|
220
|
+
def get_locally_valid_parent_sets(g: np.ndarray, x: int) -> Sequence[set[int]]:
|
|
221
|
+
"""
|
|
222
|
+
Enumerate all locally valid parent sets of node ``x`` in the local PDAG
|
|
223
|
+
``g``, as required by the local IDA algorithm.
|
|
224
|
+
|
|
225
|
+
A parent set is *locally valid* if it does not introduce a new v-structure:
|
|
226
|
+
every undirected neighbour promoted to a parent must be adjacent to every
|
|
227
|
+
other candidate parent.
|
|
228
|
+
|
|
229
|
+
Implements Algorithm 3 from:
|
|
230
|
+
Maathuis, Kalisch & Bühlmann (2009). "Estimating high-dimensional
|
|
231
|
+
intervention effects from observational data." *Annals of Statistics*.
|
|
232
|
+
|
|
233
|
+
.. note::
|
|
234
|
+
Adapted from Shubert et al.'s LOAD implementation.
|
|
235
|
+
|
|
236
|
+
Args:
|
|
237
|
+
g (np.ndarray): Local PDAG / MPDAG containing node ``x``.
|
|
238
|
+
x (int): Index of the node whose valid parent sets are enumerated.
|
|
239
|
+
|
|
240
|
+
Returns:
|
|
241
|
+
Sequence[set[int]]: List of valid parent sets (each a set of indices).
|
|
242
|
+
"""
|
|
243
|
+
neighbors = get_neighbors(g, x)
|
|
244
|
+
skeleton = g != 0
|
|
245
|
+
np.fill_diagonal(skeleton, True)
|
|
246
|
+
|
|
247
|
+
valid_sets = []
|
|
248
|
+
for new_parents in chain.from_iterable(
|
|
249
|
+
combinations(neighbors.unoriented, r)
|
|
250
|
+
for r in range(len(neighbors.unoriented) + 1)
|
|
251
|
+
):
|
|
252
|
+
candidate_set = neighbors.parents.union(new_parents)
|
|
253
|
+
if np.all(skeleton[new_parents, :][:, list(candidate_set)]):
|
|
254
|
+
valid_sets.append(candidate_set)
|
|
255
|
+
return valid_sets
|
|
256
|
+
|
|
257
|
+
|
|
258
|
+
def load(
|
|
259
|
+
data: np.ndarray,
|
|
260
|
+
ci_test: Callable[[int, int, Sequence[int]], float],
|
|
261
|
+
alpha: float,
|
|
262
|
+
targets: Sequence[int],
|
|
263
|
+
mb_algorithm: str = "grow_shrink",
|
|
264
|
+
ignore: Sequence[int] = [],
|
|
265
|
+
logging: bool = False,
|
|
266
|
+
**kwargs,
|
|
267
|
+
) -> dict:
|
|
268
|
+
"""
|
|
269
|
+
LOAD: Local Optimal Adjustment-set Discovery for a pair of target nodes.
|
|
270
|
+
|
|
271
|
+
Estimates the optimal adjustment set (o-set) for the causal effect of a
|
|
272
|
+
treatment on an outcome using only *local* CI tests and MB-by-MB structure
|
|
273
|
+
learning, without reconstructing the full global causal graph.
|
|
274
|
+
|
|
275
|
+
Pipeline:
|
|
276
|
+
|
|
277
|
+
1. Learn local MDAGs around both targets using :func:`~src.mb_by_mb.mb_by_mb_alg`.
|
|
278
|
+
2. Determine the causal direction (treatment → outcome) via
|
|
279
|
+
:func:`is_explicit_ancestor`. If direction is ambiguous, fall back to
|
|
280
|
+
:func:`is_possible_ancestor` and return all locally valid parent sets
|
|
281
|
+
with ``identifiable=False``.
|
|
282
|
+
3. Verify *amenability*: check that no undirected neighbour of the
|
|
283
|
+
treatment has an undirected path to the outcome outside the treatment.
|
|
284
|
+
4. Identify explicit mediators between treatment and outcome.
|
|
285
|
+
5. Compute the o-set as the union of parent sets of all mediators and the
|
|
286
|
+
outcome, minus mediators and the treatment itself.
|
|
287
|
+
|
|
288
|
+
.. note::
|
|
289
|
+
Adapted from Shubert et al.'s LOAD implementation.
|
|
290
|
+
|
|
291
|
+
Args:
|
|
292
|
+
data (np.ndarray): Data matrix of shape (n_samples, n_nodes).
|
|
293
|
+
ci_test (Callable[[int, int, Sequence[int]], float]): CI test returning
|
|
294
|
+
a p-value given (X, Y, conditioning_set).
|
|
295
|
+
alpha (float): Significance level for CI tests.
|
|
296
|
+
targets (Sequence[int]): Pair of node indices ``[t1, t2]`` whose causal
|
|
297
|
+
effect is to be estimated.
|
|
298
|
+
mb_algorithm (str): MB discovery algorithm — ``"grow_shrink"``
|
|
299
|
+
(default) or ``"total_conditioning"``.
|
|
300
|
+
ignore (Sequence[int]): Node indices to exclude from MB searches.
|
|
301
|
+
logging (bool): If ``True``, print verbose progress information.
|
|
302
|
+
**kwargs: Additional keyword arguments are silently ignored (for
|
|
303
|
+
interface compatibility with other algorithms).
|
|
304
|
+
|
|
305
|
+
Returns:
|
|
306
|
+
dict with keys:
|
|
307
|
+
|
|
308
|
+
* ``"adj_sets"`` (str): String representation of a dict mapping
|
|
309
|
+
``(treatment, outcome)`` to a list of adjustment sets.
|
|
310
|
+
* ``"identifiable"`` (bool): ``True`` if a unique o-set was found.
|
|
311
|
+
* ``"id_tests"`` (list): CI test counts per conditioning-set order.
|
|
312
|
+
"""
|
|
313
|
+
MB = dict()
|
|
314
|
+
L = dict()
|
|
315
|
+
G = dict()
|
|
316
|
+
sep_set = defaultdict(list)
|
|
317
|
+
adj_sets = dict()
|
|
318
|
+
|
|
319
|
+
t1, t2 = targets
|
|
320
|
+
|
|
321
|
+
if logging:
|
|
322
|
+
print("========================")
|
|
323
|
+
print(f"Running mb-by-mb for {t1}")
|
|
324
|
+
G[t1] = mb_by_mb_alg(
|
|
325
|
+
data, ci_test, alpha, t1, mb_algorithm, MB, L, sep_set, ignore=ignore
|
|
326
|
+
)
|
|
327
|
+
|
|
328
|
+
if logging:
|
|
329
|
+
print("========================")
|
|
330
|
+
print(f"Running mb-by-mb for {t2}")
|
|
331
|
+
G[t2] = mb_by_mb_alg(
|
|
332
|
+
data, ci_test, alpha, t2, mb_algorithm, MB, L, sep_set, ignore=ignore
|
|
333
|
+
)
|
|
334
|
+
|
|
335
|
+
# Determine causal direction
|
|
336
|
+
if is_explicit_ancestor(t1, t2, G[t1], ci_test, alpha):
|
|
337
|
+
treatment, outcome = t1, t2
|
|
338
|
+
elif is_explicit_ancestor(t2, t1, G[t2], ci_test, alpha):
|
|
339
|
+
treatment, outcome = t2, t1
|
|
340
|
+
else:
|
|
341
|
+
if is_possible_ancestor(t1, t2, G[t1], ci_test, alpha):
|
|
342
|
+
adj_sets[(t1, t2)] = get_locally_valid_parent_sets(G[t1], t1)
|
|
343
|
+
if is_possible_ancestor(t2, t1, G[t2], ci_test, alpha):
|
|
344
|
+
adj_sets[(t2, t1)] = get_locally_valid_parent_sets(G[t2], t2)
|
|
345
|
+
return {
|
|
346
|
+
"adj_sets": str(adj_sets),
|
|
347
|
+
"identifiable": False,
|
|
348
|
+
"id_tests": ci_test.get_tests_per_order().tolist(),
|
|
349
|
+
}
|
|
350
|
+
|
|
351
|
+
# Check amenability of undirected neighbours of treatment
|
|
352
|
+
unoriented = get_neighbors(G[treatment], treatment).unoriented
|
|
353
|
+
for v in unoriented:
|
|
354
|
+
G[v] = mb_by_mb_alg(data, ci_test, alpha, v, mb_algorithm, MB, L, sep_set)
|
|
355
|
+
if not is_amenable(treatment, outcome, v, G[v], ci_test, alpha):
|
|
356
|
+
adj_sets[(treatment, outcome)] = get_locally_valid_parent_sets(
|
|
357
|
+
G[treatment], treatment
|
|
358
|
+
)
|
|
359
|
+
return {
|
|
360
|
+
"adj_sets": str(adj_sets),
|
|
361
|
+
"identifiable": False,
|
|
362
|
+
"id_tests": ci_test.get_tests_per_order().tolist(),
|
|
363
|
+
}
|
|
364
|
+
id_tests = ci_test.get_tests_per_order().tolist()
|
|
365
|
+
|
|
366
|
+
# Identify explicit descendants of treatment (candidates for mediators)
|
|
367
|
+
desc = set()
|
|
368
|
+
for v in set(range(data.shape[1])) - {treatment, outcome}:
|
|
369
|
+
if is_explicit_ancestor(treatment, v, G[treatment], ci_test, alpha):
|
|
370
|
+
if logging:
|
|
371
|
+
print(f"Adding {v} to descendants of treatment")
|
|
372
|
+
desc.add(v)
|
|
373
|
+
G[v] = mb_by_mb_alg(data, ci_test, alpha, v, mb_algorithm, MB, L, sep_set)
|
|
374
|
+
|
|
375
|
+
# Identify explicit mediators (descendants that are ancestors of the outcome)
|
|
376
|
+
meds = set()
|
|
377
|
+
for v in desc:
|
|
378
|
+
if is_explicit_ancestor(v, outcome, G[v], ci_test, alpha):
|
|
379
|
+
meds.add(v)
|
|
380
|
+
if logging:
|
|
381
|
+
print(f"Adding {v} to mediators")
|
|
382
|
+
|
|
383
|
+
# Compute the optimal adjustment set (o-set)
|
|
384
|
+
oset = set()
|
|
385
|
+
for med in meds | {outcome}:
|
|
386
|
+
oset |= get_neighbors(G[med], med).parents
|
|
387
|
+
if logging:
|
|
388
|
+
print(f"Parents of {med}: {get_neighbors(G[med], med).parents}")
|
|
389
|
+
|
|
390
|
+
oset -= meds | {treatment}
|
|
391
|
+
|
|
392
|
+
if logging:
|
|
393
|
+
print(f"Final o-set: {oset}")
|
|
394
|
+
|
|
395
|
+
adj_sets[(treatment, outcome)] = [oset]
|
|
396
|
+
return {"adj_sets": str(adj_sets), "identifiable": True, "id_tests": id_tests}
|
|
397
|
+
|
|
398
|
+
|
|
399
|
+
# ---------------------------------------------------------------------------
|
|
400
|
+
# b-LOAD — background-knowledge extension (part of the b-LOAD algorithm)
|
|
401
|
+
# ---------------------------------------------------------------------------
|
|
402
|
+
|
|
403
|
+
|
|
404
|
+
def load_in_mpdag(
|
|
405
|
+
data: np.ndarray,
|
|
406
|
+
ci_test: Callable[[int, int, Sequence[int]], float],
|
|
407
|
+
alpha: float,
|
|
408
|
+
targets: Sequence[int],
|
|
409
|
+
background_knowledge: Optional[np.ndarray] = None,
|
|
410
|
+
mb_algorithm: str = "grow_shrink",
|
|
411
|
+
ignore: Sequence[int] = [],
|
|
412
|
+
logging: bool = False,
|
|
413
|
+
**kwargs,
|
|
414
|
+
) -> dict:
|
|
415
|
+
"""
|
|
416
|
+
b-LOAD: Background-knowledge-augmented LOAD for causal effect estimation
|
|
417
|
+
in MPDAGs.
|
|
418
|
+
|
|
419
|
+
This is the **b-LOAD** counterpart of :func:`load`. The pipeline is
|
|
420
|
+
identical, with one key difference: all calls to the MB-by-MB structure
|
|
421
|
+
learner use :func:`~src.mb_by_mb.mb_by_mb_in_mpdag_alg` instead of
|
|
422
|
+
:func:`~src.mb_by_mb.mb_by_mb_alg`. That variant:
|
|
423
|
+
|
|
424
|
+
* Seeds the growing graph ``g`` with the provided ``background_knowledge``
|
|
425
|
+
so that known edges are present from the first iteration.
|
|
426
|
+
* Re-enforces required edges after every local structure merge
|
|
427
|
+
(preventing CI-test errors from erasing prior constraints).
|
|
428
|
+
* Uses the four-rule MPDAG Meek procedure to propagate orientations
|
|
429
|
+
introduced by background-knowledge edges.
|
|
430
|
+
|
|
431
|
+
Everything downstream (ancestor tests, amenability checks, o-set
|
|
432
|
+
computation) is identical to :func:`load` and operates on the resulting
|
|
433
|
+
MPDAG.
|
|
434
|
+
|
|
435
|
+
.. note::
|
|
436
|
+
Part of the **b-LOAD** algorithm introduced in this work.
|
|
437
|
+
|
|
438
|
+
Args:
|
|
439
|
+
data (np.ndarray): Data matrix of shape (n_samples, n_nodes).
|
|
440
|
+
ci_test (Callable[[int, int, Sequence[int]], float]): CI test returning
|
|
441
|
+
a p-value given (X, Y, conditioning_set).
|
|
442
|
+
alpha (float): Significance level for CI tests.
|
|
443
|
+
targets (Sequence[int]): Pair of node indices ``[t1, t2]`` whose causal
|
|
444
|
+
effect is to be estimated.
|
|
445
|
+
background_knowledge (np.Optional[ndarray]): Prior edge constraints in the
|
|
446
|
+
standard adjacency format (``bk[i,j] == -1`` and ``bk[j,i] == 1``
|
|
447
|
+
↔ required edge i→j). If ``None``, the function behaves
|
|
448
|
+
identically to :func:`load`.
|
|
449
|
+
mb_algorithm (str): MB discovery algorithm — ``"grow_shrink"``
|
|
450
|
+
(default) or ``"total_conditioning"``.
|
|
451
|
+
ignore (Sequence[int]): Node indices excluded from all MB searches.
|
|
452
|
+
logging (bool): If ``True``, print verbose progress information.
|
|
453
|
+
**kwargs: Additional keyword arguments are silently ignored.
|
|
454
|
+
|
|
455
|
+
Returns:
|
|
456
|
+
dict with keys:
|
|
457
|
+
|
|
458
|
+
* ``"adj_sets"`` (str): String representation of a dict mapping
|
|
459
|
+
``(treatment, outcome)`` to a list of adjustment sets.
|
|
460
|
+
* ``"identifiable"`` (bool): ``True`` if a unique o-set was found.
|
|
461
|
+
* ``"id_tests"`` (list): CI test counts per conditioning-set order.
|
|
462
|
+
"""
|
|
463
|
+
MB = dict()
|
|
464
|
+
L = dict()
|
|
465
|
+
G = dict()
|
|
466
|
+
sep_set = defaultdict(list)
|
|
467
|
+
adj_sets = dict()
|
|
468
|
+
|
|
469
|
+
t1, t2 = targets
|
|
470
|
+
|
|
471
|
+
if logging:
|
|
472
|
+
print("========================")
|
|
473
|
+
print(f"Running b-LOAD mb-by-mb for {t1}")
|
|
474
|
+
G[t1] = mb_by_mb_in_mpdag_alg(
|
|
475
|
+
data, ci_test, alpha, t1, background_knowledge, mb_algorithm, MB, L, sep_set,
|
|
476
|
+
ignore=ignore,
|
|
477
|
+
)
|
|
478
|
+
|
|
479
|
+
if logging:
|
|
480
|
+
print("========================")
|
|
481
|
+
print(f"Running b-LOAD mb-by-mb for {t2}")
|
|
482
|
+
G[t2] = mb_by_mb_in_mpdag_alg(
|
|
483
|
+
data, ci_test, alpha, t2, background_knowledge, mb_algorithm, MB, L, sep_set,
|
|
484
|
+
ignore=ignore,
|
|
485
|
+
)
|
|
486
|
+
|
|
487
|
+
# Determine causal direction
|
|
488
|
+
if is_explicit_ancestor(t1, t2, G[t1], ci_test, alpha):
|
|
489
|
+
treatment, outcome = t1, t2
|
|
490
|
+
elif is_explicit_ancestor(t2, t1, G[t2], ci_test, alpha):
|
|
491
|
+
treatment, outcome = t2, t1
|
|
492
|
+
else:
|
|
493
|
+
if is_possible_ancestor(t1, t2, G[t1], ci_test, alpha):
|
|
494
|
+
adj_sets[(t1, t2)] = get_locally_valid_parent_sets(G[t1], t1)
|
|
495
|
+
if is_possible_ancestor(t2, t1, G[t2], ci_test, alpha):
|
|
496
|
+
adj_sets[(t2, t1)] = get_locally_valid_parent_sets(G[t2], t2)
|
|
497
|
+
return {
|
|
498
|
+
"adj_sets": str(adj_sets),
|
|
499
|
+
"identifiable": False,
|
|
500
|
+
"id_tests": ci_test.get_tests_per_order().tolist(),
|
|
501
|
+
}
|
|
502
|
+
|
|
503
|
+
# Check amenability of undirected neighbours of treatment
|
|
504
|
+
unoriented = get_neighbors(G[treatment], treatment).unoriented
|
|
505
|
+
for v in unoriented:
|
|
506
|
+
G[v] = mb_by_mb_in_mpdag_alg(
|
|
507
|
+
data, ci_test, alpha, v, background_knowledge, mb_algorithm, MB, L, sep_set
|
|
508
|
+
)
|
|
509
|
+
if not is_amenable(treatment, outcome, v, G[v], ci_test, alpha):
|
|
510
|
+
adj_sets[(treatment, outcome)] = get_locally_valid_parent_sets(
|
|
511
|
+
G[treatment], treatment
|
|
512
|
+
)
|
|
513
|
+
return {
|
|
514
|
+
"adj_sets": str(adj_sets),
|
|
515
|
+
"identifiable": False,
|
|
516
|
+
"id_tests": ci_test.get_tests_per_order().tolist(),
|
|
517
|
+
}
|
|
518
|
+
id_tests = ci_test.get_tests_per_order().tolist()
|
|
519
|
+
|
|
520
|
+
# Identify explicit descendants of treatment (candidates for mediators)
|
|
521
|
+
desc = set()
|
|
522
|
+
for v in set(range(data.shape[1])) - {treatment, outcome}:
|
|
523
|
+
if is_explicit_ancestor(treatment, v, G[treatment], ci_test, alpha):
|
|
524
|
+
if logging:
|
|
525
|
+
print(f"Adding {v} to descendants of treatment")
|
|
526
|
+
desc.add(v)
|
|
527
|
+
G[v] = mb_by_mb_in_mpdag_alg(
|
|
528
|
+
data, ci_test, alpha, v, background_knowledge, mb_algorithm, MB, L,
|
|
529
|
+
sep_set,
|
|
530
|
+
)
|
|
531
|
+
|
|
532
|
+
# Identify explicit mediators (descendants that are ancestors of the outcome)
|
|
533
|
+
meds = set()
|
|
534
|
+
for v in desc:
|
|
535
|
+
if is_explicit_ancestor(v, outcome, G[v], ci_test, alpha):
|
|
536
|
+
meds.add(v)
|
|
537
|
+
if logging:
|
|
538
|
+
print(f"Adding {v} to mediators")
|
|
539
|
+
|
|
540
|
+
# Compute the optimal adjustment set (o-set)
|
|
541
|
+
oset = set()
|
|
542
|
+
for med in meds | {outcome}:
|
|
543
|
+
oset |= get_neighbors(G[med], med).parents
|
|
544
|
+
if logging:
|
|
545
|
+
print(f"Parents of {med}: {get_neighbors(G[med], med).parents}")
|
|
546
|
+
|
|
547
|
+
oset -= meds | {treatment}
|
|
548
|
+
|
|
549
|
+
if logging:
|
|
550
|
+
print(f"Final o-set: {oset}")
|
|
551
|
+
|
|
552
|
+
adj_sets[(treatment, outcome)] = [oset]
|
|
553
|
+
return {"adj_sets": str(adj_sets), "identifiable": True, "id_tests": id_tests}
|