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.
@@ -0,0 +1,283 @@
1
+ """
2
+ background_knowledge.py — Background-knowledge sampling and initialisation.
3
+
4
+ All functions in this module are part of the **b-LOAD** algorithm introduced
5
+ in this work. They handle the construction of prior causal constraints
6
+ (required and forbidden directed edges) from a ground-truth DAG, and their
7
+ translation into the adjacency-matrix format consumed by the b-LOAD and b-PC
8
+ learners.
9
+
10
+ Background knowledge encoding
11
+ ------------------------------
12
+ Throughout this codebase, background knowledge is represented as an
13
+ ``(n, n)`` integer adjacency matrix ``g`` where:
14
+
15
+ * ``g[i, j] == -1`` and ``g[j, i] == 1`` → required edge i → j
16
+ * ``g[i, j] == 0`` → no constraint on edge (i, j)
17
+
18
+ Forbidden edges are currently represented only as Python sets of tuples
19
+ (not encoded into the matrix directly); the matrix stores only *required*
20
+ edges.
21
+ """
22
+
23
+ import math
24
+ import random
25
+ from typing import Any, Optional
26
+
27
+ import networkx as nx
28
+ import numpy as np
29
+
30
+
31
+ def sample_background_knowledge_v2(
32
+ true_dag: nx.DiGraph,
33
+ fraction_required: float = 0.1,
34
+ fraction_forbidden: float = 0.1,
35
+ seed: int = 42,
36
+ ) -> dict[str, set]:
37
+ """
38
+ Sample required and forbidden edge sets from the ground-truth DAG,
39
+ uniformly at random from the global edge and non-edge pools.
40
+
41
+ Required edges are drawn from edges that **exist** in ``true_dag``.
42
+ Forbidden edges are drawn from directed pairs that do **not** exist in
43
+ ``true_dag`` (including reverse directions of true edges).
44
+
45
+ .. note::
46
+ Part of the **b-LOAD** algorithm introduced in this work.
47
+
48
+ Args:
49
+ true_dag (nx.DiGraph): Ground-truth directed acyclic graph. Nodes
50
+ are expected to be integer indices.
51
+ fraction_required (float): Fraction of true edges to include as
52
+ required knowledge. E.g. ``0.3`` means 30 % of true edges are
53
+ revealed.
54
+ fraction_forbidden (float): Fraction of non-edges to mark as
55
+ forbidden.
56
+ seed (int): Random seed for reproducibility.
57
+
58
+ Returns:
59
+ dict with keys:
60
+
61
+ * ``"required"`` (set of (int, int)): Required directed edges i → j.
62
+ * ``"forbidden"`` (set of (int, int)): Forbidden directed edges i → j.
63
+ """
64
+ random.seed(seed)
65
+ nodes = list(true_dag.nodes())
66
+ all_possible_edges = [(u, v) for u in nodes for v in nodes if u != v]
67
+ true_edges = set(true_dag.edges())
68
+
69
+ num_required = int(len(true_edges) * fraction_required)
70
+ required = set(random.sample(list(true_edges), num_required))
71
+
72
+ non_edges = [edge for edge in all_possible_edges if edge not in true_edges]
73
+ num_forbidden = int(len(non_edges) * fraction_forbidden)
74
+ forbidden = set(random.sample(non_edges, num_forbidden))
75
+
76
+ return {"forbidden": forbidden, "required": required}
77
+
78
+
79
+ def sample_local_background_knowledge(
80
+ true_dag: nx.DiGraph,
81
+ targets: np.ndarray,
82
+ fraction_required: float = 0.1,
83
+ fraction_forbidden: float = 0.1,
84
+ seed: int = 42,
85
+ ) -> dict[str, set]:
86
+ """
87
+ Sample required and forbidden edges restricted to the *local neighbourhood*
88
+ of the target nodes (edges incident on at least one target).
89
+
90
+ This is the **local** background-knowledge sampling strategy used in the
91
+ b-LOAD experiments: instead of revealing global graph structure, only edges
92
+ that touch the treatment or outcome are made available.
93
+
94
+ .. note::
95
+ Part of the **b-LOAD** algorithm introduced in this work.
96
+
97
+ Args:
98
+ true_dag (nx.DiGraph): Ground-truth DAG.
99
+ targets (np.ndarray): Array of target node indices (typically the
100
+ treatment–outcome pair).
101
+ fraction_required (float): Fraction of local true edges to include as
102
+ required knowledge. A minimum of 1 edge is sampled if the
103
+ fraction is positive and the pool is non-empty.
104
+ fraction_forbidden (float): Fraction of local non-edges to mark as
105
+ forbidden.
106
+ seed (int): Random seed for reproducibility.
107
+
108
+ Returns:
109
+ dict with keys:
110
+
111
+ * ``"required"`` (set of (int, int)): Required directed edges.
112
+ * ``"forbidden"`` (set of (int, int)): Forbidden directed edges.
113
+ """
114
+ random.seed(seed)
115
+ nodes = list(true_dag.nodes())
116
+ target_set = set(targets)
117
+ true_edges = list(true_dag.edges())
118
+
119
+ local_true_edges = [
120
+ (u, v) for u, v in true_edges
121
+ if u in target_set or v in target_set
122
+ ]
123
+
124
+ all_possible_local = [
125
+ (u, v) for u in nodes for v in nodes
126
+ if u != v and (u in target_set or v in target_set)
127
+ ]
128
+ local_non_edges = [e for e in all_possible_local if e not in set(true_edges)]
129
+
130
+ def get_sample_count(pool: list, fraction: float) -> int:
131
+ if fraction <= 0 or not pool:
132
+ return 0
133
+ return max(1, math.ceil(len(pool) * fraction))
134
+
135
+ num_req = get_sample_count(local_true_edges, fraction_required)
136
+ num_forb = get_sample_count(local_non_edges, fraction_forbidden)
137
+
138
+ required = set(random.sample(local_true_edges, num_req)) if num_req > 0 else set()
139
+ forbidden = set(random.sample(local_non_edges, num_forb)) if num_forb > 0 else set()
140
+
141
+ return {"forbidden": forbidden, "required": required}
142
+
143
+
144
+ def initialize_background_knowledge(num_nodes: int, bk_dict: dict) -> np.ndarray:
145
+ """
146
+ Convert a background-knowledge dictionary into an MPDAG adjacency matrix.
147
+
148
+ Required edges from ``bk_dict["required"]`` are encoded as directed edges
149
+ in the output matrix. Forbidden edges (``bk_dict["forbidden"]``) are
150
+ **not** encoded in the matrix — their enforcement is handled externally
151
+ (e.g. by preventing the skeleton search from drawing those edges).
152
+
153
+ The returned matrix is used to initialise ``g`` in
154
+ :func:`~src.mb_by_mb.mb_by_mb_in_mpdag_alg` and as the ``background_knowledge``
155
+ mask in :func:`~src.mb_by_mb.update_graph_mpdag`.
156
+
157
+ .. note::
158
+ Part of the **b-LOAD** algorithm introduced in this work.
159
+
160
+ Args:
161
+ num_nodes (int): Total number of variables / nodes in the dataset.
162
+ bk_dict (dict): Background-knowledge dictionary with optional keys:
163
+
164
+ * ``"required"`` (set of (int, int)): Each tuple ``(i, j)``
165
+ encodes the required directed edge i → j.
166
+ * ``"forbidden"`` (set of (int, int)): Currently unused in the
167
+ matrix encoding.
168
+
169
+ Returns:
170
+ np.ndarray: Integer matrix of shape ``(num_nodes, num_nodes)`` where
171
+ ``g[i,j] == -1`` and ``g[j,i] == 1`` for every required edge i→j,
172
+ and all other entries are ``0``.
173
+ """
174
+ g = np.zeros((num_nodes, num_nodes), dtype=int)
175
+
176
+ if "required" in bk_dict:
177
+ for i, j in bk_dict["required"]:
178
+ g[i, j] = -1 # tail at i
179
+ g[j, i] = 1 # arrowhead at j
180
+
181
+ return g
182
+
183
+
184
+ def sample_local_background_knowledge_noised(
185
+ true_dag: nx.DiGraph,
186
+ targets: np.ndarray,
187
+ fraction_required: float = 0.1,
188
+ fraction_forbidden: float = 0.1,
189
+ noise_mu: float = 0.2,
190
+ seed: int = 42,
191
+ ) -> dict[str, set]:
192
+ """
193
+ Sample local background knowledge with Gaussian noise applied to the
194
+ required edge set.
195
+
196
+ This is the **noised** variant of :func:`sample_local_background_knowledge`,
197
+ used to study the robustness of b-LOAD to incorrect prior information.
198
+ After sampling the required and forbidden sets as usual, a fraction of the
199
+ required edges are replaced by randomly selected non-edges (false positives
200
+ in the required-edge set).
201
+
202
+ The noise rate is itself drawn from a Gaussian distribution
203
+ ``N(noise_mu, (noise_mu/3)²)`` clipped to ``[0, 1]``, so that the
204
+ experiments reflect real-world uncertainty about how reliable the prior
205
+ information is.
206
+
207
+ .. note::
208
+ Part of the **b-LOAD** algorithm introduced in this work.
209
+
210
+ Args:
211
+ true_dag (nx.DiGraph): Ground-truth DAG.
212
+ targets (np.ndarray): Target node indices.
213
+ fraction_required (float): Fraction of local true edges to sample as
214
+ required knowledge (before corruption).
215
+ fraction_forbidden (float): Fraction of local non-edges to sample as
216
+ forbidden.
217
+ noise_mu (float): Mean of the Gaussian noise distribution controlling
218
+ what fraction of required edges are corrupted with false positives.
219
+ ``0.0`` means no noise; ``1.0`` means all required edges are
220
+ replaced.
221
+ seed (int): Random seed for reproducibility (both ``random`` and
222
+ ``numpy.random``).
223
+
224
+ Returns:
225
+ dict with keys:
226
+
227
+ * ``"required"`` (set of (int, int)): Required edges (possibly
228
+ containing some incorrect entries due to noise).
229
+ * ``"forbidden"`` (set of (int, int)): Forbidden edges (unaffected by
230
+ noise).
231
+ """
232
+ random.seed(seed)
233
+ np.random.seed(seed)
234
+
235
+ noise_sigma = noise_mu / 3
236
+
237
+ nodes = list(true_dag.nodes())
238
+ target_set = set(targets)
239
+ true_edges = set(true_dag.edges())
240
+
241
+ local_true_edges = [
242
+ (u, v) for u, v in true_edges
243
+ if u in target_set or v in target_set
244
+ ]
245
+
246
+ all_possible_local = [
247
+ (u, v) for u in nodes for v in nodes
248
+ if u != v and (u in target_set or v in target_set)
249
+ ]
250
+ local_non_edges = [e for e in all_possible_local if e not in true_edges]
251
+
252
+ def get_sample_count(pool: list, fraction: float) -> int:
253
+ if fraction <= 0 or not pool:
254
+ return 0
255
+ return max(1, math.ceil(len(pool) * fraction))
256
+
257
+ num_req = get_sample_count(local_true_edges, fraction_required)
258
+ num_forb = get_sample_count(local_non_edges, fraction_forbidden)
259
+
260
+ required = set(random.sample(local_true_edges, num_req)) if num_req > 0 else set()
261
+ forbidden = set(random.sample(local_non_edges, num_forb)) if num_forb > 0 else set()
262
+
263
+ # Draw noise rate from Gaussian, clipped to [0, 1]
264
+ noise_rate = float(
265
+ np.clip(np.random.normal(loc=noise_mu, scale=noise_sigma), 0.0, 1.0)
266
+ )
267
+
268
+ # Corrupt required edges: replace k edges with random non-edges
269
+ n = len(required)
270
+ if n == 0 or noise_rate == 0.0 or not local_non_edges:
271
+ return {"required": required, "forbidden": forbidden}
272
+
273
+ if n == 1:
274
+ if random.random() < noise_rate:
275
+ required = set(random.sample(local_non_edges, 1))
276
+ else:
277
+ k = min(round(noise_rate * n), len(local_non_edges))
278
+ if k > 0:
279
+ to_corrupt = set(random.sample(list(required), k))
280
+ false_edges = set(random.sample(local_non_edges, k))
281
+ required = (required - to_corrupt) | false_edges
282
+
283
+ return {"required": required, "forbidden": forbidden}
@@ -0,0 +1,101 @@
1
+ """
2
+ counting_ci_tests.py — Instrumented CI test wrapper that counts tests by order.
3
+
4
+ Provides :class:`CountingTest`, a thin wrapper around ``causallearn``'s
5
+ :class:`~causallearn.utils.cit.CIT` that tracks every conditional independence
6
+ test performed, keyed by the pair (X, Y) and the conditioning-set size (order).
7
+ This instrumentation is used to report the number of CI tests consumed per
8
+ algorithm run, broken down by conditioning-set order.
9
+ """
10
+
11
+ from collections import defaultdict
12
+ from typing import Optional
13
+
14
+ import numpy as np
15
+ from causallearn.utils.cit import CIT
16
+
17
+
18
+ class CountingTest:
19
+ """
20
+ Wrapper around a ``causallearn`` CI test that counts every test performed.
21
+
22
+ The count is accumulated in :attr:`tests_done`, a dict mapping each
23
+ ``frozenset({X, Y})`` pair to the set of conditioning-set tuples that have
24
+ been tested for that pair (deduplicating repeated calls with the same
25
+ conditioning set).
26
+
27
+ Use :meth:`get_tests_per_order` to retrieve a summary array indexed by
28
+ conditioning-set size.
29
+
30
+ Args:
31
+ data (np.ndarray): Data matrix of shape (n_samples, n_nodes), passed
32
+ directly to the underlying :class:`~causallearn.utils.cit.CIT`.
33
+ ci_test (str): Name of the CI test to use (e.g. ``"fisherz"``,
34
+ ``"chisq"``). Must be a test supported by ``causallearn``.
35
+ **kwargs: Additional keyword arguments forwarded to
36
+ :class:`~causallearn.utils.cit.CIT`.
37
+ """
38
+
39
+ def __init__(
40
+ self,
41
+ data: np.ndarray,
42
+ ci_test: str,
43
+ **kwargs,
44
+ ):
45
+ self.cit = CIT(data, ci_test, **kwargs)
46
+ # Pre-compute the precision matrix for Fisher-Z to avoid repeated
47
+ # matrix inversions during the experiment.
48
+ if ci_test == "fisherz":
49
+ self.cit.precision_matrix = np.linalg.inv(self.cit.correlation_matrix)
50
+
51
+ self.method = self.cit.method
52
+ # tests_done[frozenset({X, Y})] = set of conditioning-set tuples tested
53
+ self.tests_done: dict[frozenset, set] = defaultdict(set)
54
+
55
+ def __call__(
56
+ self,
57
+ X: int,
58
+ Y: int,
59
+ condition_set: Optional[list[int]] = [],
60
+ *args,
61
+ **kwargs,
62
+ ) -> float:
63
+ """
64
+ Perform a conditional independence test of X ⊥ Y | condition_set and
65
+ record it in :attr:`tests_done`.
66
+
67
+ Args:
68
+ X (int): Index of the first variable.
69
+ Y (int): Index of the second variable.
70
+ condition_set (Optional[list[int]]): Indices of the conditioning
71
+ variables. ``None`` is treated as the empty set.
72
+
73
+ Returns:
74
+ float: p-value returned by the underlying CI test. A p-value ≥ α
75
+ indicates (conditional) independence.
76
+ """
77
+ if condition_set is None:
78
+ condition_set = []
79
+ self.tests_done[frozenset((X, Y))] |= {tuple(condition_set)}
80
+ return self.cit(X, Y, condition_set)
81
+
82
+ def get_tests_per_order(self) -> np.ndarray:
83
+ """
84
+ Summarise the CI tests performed, counted per conditioning-set order.
85
+
86
+ Returns:
87
+ np.ndarray: Integer array of length ``n_nodes`` where entry ``k``
88
+ is the total number of CI tests performed with a conditioning
89
+ set of size ``k``.
90
+ """
91
+ num_nodes = self.cit.data.shape[1]
92
+ cond_sets = self.tests_done.values()
93
+ if not cond_sets:
94
+ return np.zeros(num_nodes, dtype=int)
95
+ orders, test_num = np.unique(
96
+ [len(cond) for conds in cond_sets for cond in conds],
97
+ return_counts=True,
98
+ )
99
+ tests_per_order = np.zeros(num_nodes, dtype=int)
100
+ tests_per_order[orders] = test_num
101
+ return tests_per_order
src/data_generation.py ADDED
@@ -0,0 +1,185 @@
1
+ """
2
+ data_generation.py — Synthetic experiment data generation via R.
3
+
4
+ Experimental datasets (DAGs + linear SEM samples) are generated by calling R
5
+ helper functions defined in ``generate_data.R`` at the project root, via
6
+ ``rpy2``. Results are cached to disk so that the same seed/parameter
7
+ combination always reproduces the same dataset.
8
+
9
+ The R script is sourced automatically when this module is imported. If
10
+ ``generate_data.R`` is not found, an :class:`FileNotFoundError` is raised at
11
+ import time.
12
+ """
13
+
14
+ import json
15
+ import pickle
16
+ from pathlib import Path
17
+
18
+ import networkx as nx
19
+ import numpy as np
20
+ from rpy2 import robjects
21
+ from rpy2.robjects import r
22
+
23
+
24
+ def save_data(data: dict, seed: int, **kwargs) -> None:
25
+ """
26
+ Persist an experiment dictionary to disk under a path derived from the
27
+ generation parameters.
28
+
29
+ The file is saved at ``experiments/<json_kwargs>/<seed>.pkl``. Parent
30
+ directories are created automatically.
31
+
32
+ Args:
33
+ data (dict): Experiment dictionary to serialise (must be picklable).
34
+ seed (int): Random seed used to generate the data.
35
+ **kwargs: All other generation parameters (used to build the directory
36
+ name).
37
+ """
38
+ file_path = Path("experiments/{}/{}.pkl".format(json.dumps(kwargs), seed))
39
+ file_path.parent.mkdir(parents=True, exist_ok=True)
40
+ with file_path.open("wb") as file:
41
+ pickle.dump(data, file)
42
+
43
+
44
+ def load_data(seed: int, **kwargs) -> dict:
45
+ """
46
+ Load a previously cached experiment dictionary from disk.
47
+
48
+ Raises :class:`FileNotFoundError` if no cached file exists for the given
49
+ seed/parameter combination (the caller should then generate fresh data).
50
+
51
+ Args:
52
+ seed (int): Random seed used to generate the data.
53
+ **kwargs: Generation parameters (used to reconstruct the file path).
54
+
55
+ Returns:
56
+ dict: The loaded experiment dictionary.
57
+ """
58
+ file_path = Path("experiments/{}/{}.pkl".format(json.dumps(kwargs), seed))
59
+ with file_path.open("rb") as file:
60
+ return pickle.load(file)
61
+
62
+
63
+ def generate_data(
64
+ seed: int,
65
+ observed: int,
66
+ exp_degree: float,
67
+ max_degree: int,
68
+ targets: int,
69
+ latent: int = 0,
70
+ connected: bool = True,
71
+ expl_anc: bool = False,
72
+ identifiable: bool = False,
73
+ min_adj_size: int = 0,
74
+ samples_num: int = 0,
75
+ discrete: bool = False,
76
+ max_classes: int = 2,
77
+ file: Optional[str] = None,
78
+ save: bool = True,
79
+ ) -> dict:
80
+ """
81
+ Generate (or load from cache) a synthetic experiment dataset.
82
+
83
+ If a cached file exists for the given parameters, it is loaded and returned
84
+ immediately. Otherwise, the R helper function ``generate_data`` (or
85
+ ``generate_data_from_file`` when ``file`` is given) is called via ``rpy2``
86
+ to produce a random linear Gaussian SEM, a DAG sample, and observations.
87
+
88
+ Args:
89
+ seed (int): Random seed for the R and Python RNGs.
90
+ observed (int): Number of observed (non-latent) nodes.
91
+ exp_degree (float): Expected degree of the generated random graph.
92
+ max_degree (int): Maximum node degree allowed in the graph.
93
+ targets (int): Number of treatment–outcome target pairs to sample.
94
+ latent (int): Number of latent (hidden) nodes.
95
+ connected (bool): If ``True``, only accept connected graphs.
96
+ expl_anc (bool): If ``True``, require the targets to form an explicit
97
+ ancestor–descendant pair in the generated DAG.
98
+ identifiable (bool): If ``True``, require the causal effect to be
99
+ identifiable from the generated CPDAG.
100
+ min_adj_size (int): Minimum size of the true optimal adjustment set.
101
+ samples_num (int): Number of i.i.d. observations to draw.
102
+ discrete (bool): If ``True``, generate discrete (binary/categorical)
103
+ data instead of continuous Gaussian data.
104
+ max_classes (int): Maximum number of categories per discrete variable
105
+ (only used when ``discrete=True``).
106
+ file (Optional[str]): Path to an existing R model file. When provided,
107
+ the graph structure is loaded from that file and only new samples
108
+ are drawn (``generate_data_from_file`` is called).
109
+ save (bool): If ``True``, cache the generated dataset to disk.
110
+
111
+ Returns:
112
+ dict with keys:
113
+
114
+ * ``"id"`` — experiment identifier.
115
+ * ``"data"`` (np.ndarray) — observation matrix (n_samples × n_nodes).
116
+ * ``"targets"`` (np.ndarray) — 0-based indices of the target nodes.
117
+ * ``"true_dag"`` (nx.DiGraph) — ground-truth DAG with edge weights
118
+ equal to the linear SEM coefficients.
119
+ * ``"cpt"`` — R conditional-probability table object (for binary data).
120
+ * ``"treatment"`` (int) — 0-based index of the treatment node.
121
+ * ``"outcome"`` (int) — 0-based index of the outcome node.
122
+ """
123
+ if file is None:
124
+ gen_func = r["generate_data"]
125
+ kwargs = {
126
+ "seed": seed,
127
+ "observed": observed,
128
+ "latent": latent,
129
+ "exp_degree": exp_degree,
130
+ "max_degree": max_degree,
131
+ "targets": targets,
132
+ "connected": connected,
133
+ "expl_anc": expl_anc,
134
+ "identifiable": identifiable,
135
+ "min_adj_size": min_adj_size,
136
+ "samples_num": samples_num,
137
+ "discrete": discrete,
138
+ "max_classes": max_classes,
139
+ }
140
+ else:
141
+ gen_func = r["generate_data_from_file"]
142
+ kwargs = {
143
+ "file": file,
144
+ "seed": seed,
145
+ "targets": targets,
146
+ "identifiable": identifiable,
147
+ "min_adj_size": min_adj_size,
148
+ "samples_num": samples_num,
149
+ }
150
+
151
+ try:
152
+ return load_data(**kwargs)
153
+ except FileNotFoundError:
154
+ r_data = gen_func(**kwargs)
155
+ true_dag = r_data.rx2("suffStat").rx2("g")
156
+ true_dag = nx.from_numpy_array(
157
+ np.array(r["as"](true_dag, "matrix")),
158
+ create_using=nx.DiGraph,
159
+ )
160
+ dm = np.array(r_data.rx2("suffStat").rx2("dm"))
161
+ data = {
162
+ "id": r_data.rx2("id")[0],
163
+ "data": dm,
164
+ "targets": np.array(r_data.rx2("targets")).astype(np.int32) - 1,
165
+ "true_dag": true_dag,
166
+ "cpt": r_data.rx2("cpt"),
167
+ "treatment": np.array(r_data.rx2("treatment")).astype(np.int32)[0] - 1,
168
+ "outcome": np.array(r_data.rx2("outcome")).astype(np.int32)[0] - 1,
169
+ }
170
+ if save:
171
+ save_data(data, **kwargs)
172
+ return data
173
+
174
+
175
+ # ---------------------------------------------------------------------------
176
+ # Module initialisation — source the R data-generation script
177
+ # ---------------------------------------------------------------------------
178
+
179
+ _r_script = Path(__file__).resolve().parent.parent / "generate_data.R"
180
+
181
+ if _r_script.exists():
182
+ robjects.r.source(str(_r_script))
183
+ print(f"Successfully sourced: {_r_script}")
184
+ else:
185
+ raise FileNotFoundError(f"R data generation script not found at {_r_script}")