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.
src/pc.py ADDED
@@ -0,0 +1,341 @@
1
+ """
2
+ pc.py — PC and b-PC global causal structure learning.
3
+
4
+ Two algorithms are provided:
5
+
6
+ 1. **PC** — standard PC algorithm producing a CPDAG via skeleton search,
7
+ v-structure orientation, and three-rule Meek propagation.
8
+ Functions: ``_meek``, ``pc``.
9
+
10
+ 2. **b-PC** — PC extended with background knowledge, producing an MPDAG.
11
+ Required edges from the background-knowledge matrix are injected into the
12
+ CPDAG after the standard PC run, and a four-rule Meek procedure (R1–R3
13
+ structural + R4 using the sep-set) propagates the induced orientations.
14
+ Part of the b-LOAD algorithm introduced in this work.
15
+ Functions: ``_meek4``, ``pc_with_bk``.
16
+
17
+ Graph encoding
18
+ --------------
19
+ ``g[i, j] == -1`` → tail at i (i — j or i → j)
20
+ ``g[i, j] == 1`` → head at i (j → i)
21
+ ``g[i, j] == 0`` → no edge
22
+
23
+ An undirected edge i — j satisfies g[i,j] == g[j,i] == -1.
24
+ A directed edge i → j satisfies g[i,j] == -1 and g[j,i] == 1.
25
+
26
+ The final ``"amat"`` output follows a different convention (used by the
27
+ evaluation code): ``amat[i][j] == 1`` indicates a tail at i (i.e., an edge
28
+ from i toward j, directed or undirected).
29
+ """
30
+
31
+ from collections import defaultdict
32
+ from typing import Callable, Optional
33
+
34
+ import numpy as np
35
+
36
+ from src.mb_by_mb import skeleton_step, v_struc_pc
37
+
38
+
39
+ # ---------------------------------------------------------------------------
40
+ # PC (base)
41
+ # ---------------------------------------------------------------------------
42
+
43
+
44
+ def _meek(pdag: np.ndarray) -> np.ndarray:
45
+ """
46
+ Apply the standard three-rule Meek orientation rules (R1–R3) to a PDAG.
47
+
48
+ Rules operate on graph *structure alone* (no sep-set conditioning), which
49
+ matches the original PC algorithm specification. All matching patterns are
50
+ oriented simultaneously per rule before re-checking (vectorised).
51
+
52
+ * **R1** — i → j — k, i not adjacent to k ⟹ j → k
53
+ * **R2** — i → j → k — i ⟹ i → k (acyclicity)
54
+ * **R3** — i — k -/- j, i — l -/- j, k → i, l → i, i — j ⟹ i → j
55
+
56
+ Args:
57
+ pdag (np.ndarray): Partially directed graph (copied internally; input
58
+ is not mutated).
59
+
60
+ Returns:
61
+ np.ndarray: CPDAG with all Meek-propagatable orientations resolved.
62
+ """
63
+
64
+ def rule1(pdag: np.ndarray) -> bool:
65
+ """R1: i → j — k, i -/- k ⟹ j → k."""
66
+ i, j = np.where((pdag == -1) & (pdag.T == 1)) # i -> j
67
+ k = np.where(
68
+ ((pdag[j] == -1) & (pdag.T[j] == -1)) # j - k
69
+ & (pdag[i] == 0) # i -/- k
70
+ )
71
+ i, j, k = i[k[0]], j[k[0]], k[1]
72
+ pdag[k, j] = 1
73
+ return len(i) > 0
74
+
75
+ def rule2(pdag: np.ndarray) -> bool:
76
+ """R2: i → j → k — i ⟹ i → k (closing a directed cycle)."""
77
+ i, j = np.where((pdag == -1) & (pdag.T == 1)) # i -> j
78
+ k = np.where(
79
+ ((pdag[j] == -1) & (pdag.T[j] == 1)) # j -> k
80
+ & ((pdag[i] == -1) & (pdag.T[i] == -1)) # i - k
81
+ )
82
+ i, j, k = i[k[0]], j[k[0]], k[1]
83
+ pdag[k, i] = 1
84
+ return len(i) > 0
85
+
86
+ def rule3(pdag: np.ndarray) -> bool:
87
+ """R3: i — k -/- j, i — l -/- j, k → i, l → i, i — j ⟹ i → j."""
88
+ i, j = np.where((pdag == -1) & (pdag.T == -1)) # i - j
89
+ k = np.where(
90
+ ((pdag[i] == -1) & (pdag.T[i] == -1)) # k - i
91
+ & (pdag[j] == 0) # k -/- j
92
+ )
93
+ i, j, k = i[k[0]], j[k[0]], k[1]
94
+ mask = j < k
95
+ i, j, k = i[mask], j[mask], k[mask]
96
+ l = np.where(
97
+ ((pdag[i] == -1) & (pdag.T[i] == -1)) # i - l
98
+ & ((pdag[j] == -1) & (pdag.T[j] == 1)) # j -> l
99
+ & ((pdag[k] == -1) & (pdag.T[k] == 1)) # k -> l
100
+ )
101
+ i, j, k, l = i[l[0]], j[l[0]], k[l[0]], l[1]
102
+ pdag[l, i] = 1
103
+ return len(i) > 0
104
+
105
+ pdag = pdag.copy()
106
+ while rule1(pdag) or rule2(pdag) or rule3(pdag):
107
+ continue
108
+ return pdag
109
+
110
+
111
+ def pc(
112
+ data: np.ndarray,
113
+ ci_test: Callable[[int, int, list[int]], float],
114
+ alpha: float,
115
+ **kwargs,
116
+ ) -> dict:
117
+ """
118
+ PC algorithm for global causal structure learning.
119
+
120
+ Learns a CPDAG (completed partially directed acyclic graph) representing
121
+ the Markov equivalence class of the underlying DAG.
122
+
123
+ Pipeline:
124
+
125
+ 1. **Skeleton search**: iteratively remove edges using CI tests (growing
126
+ conditioning-set size).
127
+ 2. **V-structure orientation**: orient unshielded colliders from the
128
+ skeleton and separating sets.
129
+ 3. **Meek propagation**: apply three-rule Meek (R1–R3) to orient as many
130
+ remaining edges as possible.
131
+
132
+ Args:
133
+ data (np.ndarray): Data matrix of shape (n_samples, n_nodes).
134
+ ci_test (Callable[[int, int, list[int]], float]): CI test returning a
135
+ p-value given (X, Y, conditioning_set).
136
+ alpha (float): Significance level — edges whose CI test p-value ≥
137
+ alpha are removed from the skeleton.
138
+ **kwargs: Additional keyword arguments are silently ignored (for
139
+ interface compatibility).
140
+
141
+ Returns:
142
+ dict with key ``"amat"``: CPDAG adjacency matrix as a nested list.
143
+ ``amat[i][j] == 1`` means there is an edge with tail at i
144
+ (i → j for a directed edge, or i — j for undirected).
145
+ Undirected edges satisfy ``amat[i][j] == amat[j][i] == 1``.
146
+ """
147
+ n = data.shape[1]
148
+ skeleton = np.full((n, n), -1, dtype=int)
149
+ np.fill_diagonal(skeleton, 0)
150
+ sep_set = defaultdict(list)
151
+
152
+ order = 0
153
+ while np.amax(np.sum(skeleton != 0, axis=1)) > order:
154
+ skeleton = skeleton_step(order, skeleton, ci_test, alpha, sep_set)
155
+ order += 1
156
+
157
+ pdag = v_struc_pc(skeleton, sep_set)
158
+ cpdag = _meek(pdag)
159
+
160
+ # Convert internal encoding (tail at i = -1) to output encoding (tail at i = 1)
161
+ amat = np.zeros((n, n), dtype=int)
162
+ amat[cpdag == -1] = 1
163
+ return {"amat": amat.tolist()}
164
+
165
+
166
+ # ---------------------------------------------------------------------------
167
+ # b-PC — background-knowledge extension (part of the b-LOAD algorithm)
168
+ # ---------------------------------------------------------------------------
169
+
170
+
171
+ def _meek4(pdag: np.ndarray, sep_set: dict) -> np.ndarray:
172
+ """
173
+ Four-rule Meek for b-PC: R1–R3 structural rules plus R4 using the sep-set.
174
+
175
+ R1–R3 are the same purely structural rules as :func:`_meek`.
176
+ R4 additionally consults the sep-set from the PC skeleton search:
177
+
178
+ * **R4** — undirected a — b; a — c (undir), b → c; a — d (undir), d → c;
179
+ b not adjacent to d; and a in every Sep(b, d) ⟹ orient a → b.
180
+
181
+ R4 propagates orientations introduced by injected background-knowledge
182
+ edges that R1–R3 alone cannot deduce from graph topology.
183
+
184
+ .. note::
185
+ Part of the **b-LOAD / b-PC** algorithm introduced in this work.
186
+
187
+ Args:
188
+ pdag (np.ndarray): Partially directed graph (copied internally).
189
+ sep_set (dict): Separating sets from the skeleton search, keyed by
190
+ ``frozenset({i, k})``. Each value is a list of conditioning sets
191
+ that d-separated i and k.
192
+
193
+ Returns:
194
+ np.ndarray: Graph with all four-rule Meek propagatable orientations
195
+ resolved.
196
+ """
197
+
198
+ def rule1(pdag: np.ndarray) -> bool:
199
+ """R1: i → j — k, i -/- k ⟹ j → k."""
200
+ i, j = np.where((pdag == -1) & (pdag.T == 1))
201
+ k = np.where(
202
+ ((pdag[j] == -1) & (pdag.T[j] == -1))
203
+ & (pdag[i] == 0)
204
+ )
205
+ i, j, k = i[k[0]], j[k[0]], k[1]
206
+ pdag[k, j] = 1
207
+ return len(i) > 0
208
+
209
+ def rule2(pdag: np.ndarray) -> bool:
210
+ """R2: i → j → k — i ⟹ i → k."""
211
+ i, j = np.where((pdag == -1) & (pdag.T == 1))
212
+ k = np.where(
213
+ ((pdag[j] == -1) & (pdag.T[j] == 1))
214
+ & ((pdag[i] == -1) & (pdag.T[i] == -1))
215
+ )
216
+ i, j, k = i[k[0]], j[k[0]], k[1]
217
+ pdag[k, i] = 1
218
+ return len(i) > 0
219
+
220
+ def rule3(pdag: np.ndarray) -> bool:
221
+ """R3: i — k -/- j, i — l -/- j, k → i, l → i, i — j ⟹ i → j."""
222
+ i, j = np.where((pdag == -1) & (pdag.T == -1))
223
+ k = np.where(
224
+ ((pdag[i] == -1) & (pdag.T[i] == -1))
225
+ & (pdag[j] == 0)
226
+ )
227
+ i, j, k = i[k[0]], j[k[0]], k[1]
228
+ mask = j < k
229
+ i, j, k = i[mask], j[mask], k[mask]
230
+ l = np.where(
231
+ ((pdag[i] == -1) & (pdag.T[i] == -1))
232
+ & ((pdag[j] == -1) & (pdag.T[j] == 1))
233
+ & ((pdag[k] == -1) & (pdag.T[k] == 1))
234
+ )
235
+ i, j, k, l = i[l[0]], j[l[0]], k[l[0]], l[1]
236
+ pdag[l, i] = 1
237
+ return len(i) > 0
238
+
239
+ def rule4(pdag: np.ndarray, sep_set: dict) -> bool:
240
+ """
241
+ R4: a — b (undir); a — c (undir), b → c; a — d (undir), d → c;
242
+ b -/- d; a ∈ Sep(b, d) ⟹ a → b.
243
+
244
+ a being in every Sep(b, d) certifies it is a non-collider on
245
+ b — a — d, so the only consistent orientation of a — b is a → b.
246
+ This handles BK-induced directed edges that R1–R3 cannot propagate.
247
+ """
248
+ a, b = np.where((pdag == -1) & (pdag.T == -1))
249
+ changed = False
250
+ for a_, b_ in zip(a, b):
251
+ c_list = np.where(
252
+ ((pdag[a_] == -1) & (pdag.T[a_] == -1)) # a - c
253
+ & ((pdag[b_] == -1) & (pdag.T[b_] == 1)) # b -> c
254
+ )[0]
255
+ for c_ in c_list:
256
+ d_list = np.where(
257
+ ((pdag[a_] == -1) & (pdag.T[a_] == -1)) # a - d
258
+ & ((pdag[c_] == -1) & (pdag.T[c_] == 1)) # d -> c
259
+ & (pdag[b_] == 0) # b -/- d
260
+ )[0]
261
+ for d_ in d_list:
262
+ if frozenset((b_, d_)) in sep_set and all(
263
+ a_ in S for S in sep_set[frozenset((b_, d_))]
264
+ ):
265
+ pdag[b_, a_] = 1 # a -> b
266
+ changed = True
267
+ break
268
+ if changed:
269
+ break
270
+ return changed
271
+
272
+ pdag = pdag.copy()
273
+ while rule1(pdag) or rule2(pdag) or rule3(pdag) or rule4(pdag, sep_set):
274
+ continue
275
+ return pdag
276
+
277
+
278
+ def pc_with_bk(
279
+ data: np.ndarray,
280
+ ci_test: Callable[[int, int, list[int]], float],
281
+ alpha: float,
282
+ background_knowledge: Optional[np.ndarray] = None,
283
+ **kwargs,
284
+ ) -> dict:
285
+ """
286
+ b-PC: PC algorithm with background-knowledge injection and four-rule Meek.
287
+
288
+ Extends the standard :func:`pc` pipeline with two additional steps:
289
+
290
+ 1. After the CPDAG is built by standard PC, **required edges** from
291
+ ``background_knowledge`` are overlaid directly onto the CPDAG.
292
+ 2. A **four-rule Meek** sweep (R1–R3 structural + R4 with sep-set) is run
293
+ to propagate orientations induced by the injected edges.
294
+
295
+ Forbidden edges in ``background_knowledge`` are ignored; only required
296
+ edges (non-zero entries in the matrix) are injected.
297
+
298
+ .. note::
299
+ Part of the **b-LOAD / b-PC** algorithm introduced in this work.
300
+
301
+ Args:
302
+ data (np.ndarray): Data matrix of shape (n_samples, n_nodes).
303
+ ci_test (Callable[[int, int, list[int]], float]): CI test returning a
304
+ p-value given (X, Y, conditioning_set).
305
+ alpha (float): Significance level.
306
+ background_knowledge (np.Optional[ndarray]): Adjacency matrix where
307
+ ``bk[i,j] == -1`` and ``bk[j,i] == 1`` encodes the required
308
+ directed edge i → j. If ``None``, the function behaves
309
+ identically to :func:`pc`.
310
+ **kwargs: Additional keyword arguments are silently ignored.
311
+
312
+ Returns:
313
+ dict with key ``"amat"``: MPDAG adjacency matrix as a nested list
314
+ (same convention as :func:`pc`).
315
+ """
316
+ n = data.shape[1]
317
+ skeleton = np.full((n, n), -1, dtype=int)
318
+ np.fill_diagonal(skeleton, 0)
319
+ sep_set = defaultdict(list)
320
+
321
+ order = 0
322
+ while np.amax(np.sum(skeleton != 0, axis=1)) > order:
323
+ skeleton = skeleton_step(order, skeleton, ci_test, alpha, sep_set)
324
+ order += 1
325
+
326
+ pdag = v_struc_pc(skeleton, sep_set)
327
+
328
+ # Standard three-rule Meek (PC step)
329
+ cpdag = _meek(pdag)
330
+
331
+ # Inject required background-knowledge edges
332
+ if background_knowledge is not None:
333
+ mask = background_knowledge != 0
334
+ cpdag[mask] = background_knowledge[mask]
335
+
336
+ # Four-rule Meek to propagate BK-induced orientations
337
+ cpdag = _meek4(cpdag, sep_set)
338
+
339
+ amat = np.zeros((n, n), dtype=int)
340
+ amat[cpdag == -1] = 1
341
+ return {"amat": amat.tolist()}
@@ -0,0 +1 @@
1
+ """Real-data benchmark applications for b-LOAD."""
@@ -0,0 +1,306 @@
1
+ """
2
+ dream.py — DREAM4 and DREAM5 real-data experiment runners.
3
+
4
+ Provides helpers for loading the DREAM4 In Silico Size-100 benchmark datasets
5
+ and the DREAM5 network inference challenge data, constructing ground-truth DAGs
6
+ from the accompanying gold-standard files, fitting oracle linear SEM weights,
7
+ and running b-LOAD experiments via :func:`~src.running.run_experiment_mpdag_real`.
8
+
9
+ Usage (DREAM4)::
10
+
11
+ result_dict, details_dict = run_experiment_dream4(
12
+ subset_number=1, sampling_strategy="local", frac_req=0.3
13
+ )
14
+
15
+ Usage (DREAM5)::
16
+
17
+ result_dict, details_dict = run_experiment_dream5(
18
+ subset_number=2, sampling_strategy="global", frac_req=0.2
19
+ )
20
+
21
+ Expected file layout::
22
+
23
+ experiments/dream4/
24
+ insilico_size100_<N>_multifactorial.tsv
25
+ DREAM4_GoldStandard_InSilico_Size100_multifactorial_<N>.tsv
26
+
27
+ experiments/dream5/
28
+ net<N>_expression_data.tsv
29
+ DREAM5_NetworkInference_GoldStandard_Network<N>.tsv
30
+ """
31
+
32
+ import networkx as nx
33
+ import numpy as np
34
+ import pandas as pd
35
+
36
+ from src.real_data_applications.sachs import fit_oracle_weights
37
+ from src.running import run_experiment_mpdag_real
38
+
39
+
40
+ # ---------------------------------------------------------------------------
41
+ # Shared utilities
42
+ # ---------------------------------------------------------------------------
43
+
44
+
45
+ def sanitize_to_dag(graph: nx.DiGraph) -> nx.DiGraph:
46
+ """
47
+ Iteratively break cycles in a directed graph until it is a strict DAG.
48
+
49
+ Cycles are broken by removing the first edge reported by
50
+ :func:`networkx.find_cycle` at each iteration. A warning is printed for
51
+ each removed edge so the user can assess the magnitude of the correction.
52
+
53
+ Args:
54
+ graph (nx.DiGraph): Input graph, potentially containing directed cycles
55
+ (e.g. because the biological ground-truth network has feedback loops
56
+ that are not representable as a DAG).
57
+
58
+ Returns:
59
+ nx.DiGraph: A copy of ``graph`` with enough edges removed to guarantee
60
+ acyclicity.
61
+ """
62
+ safe_dag = graph.copy()
63
+ cycle_count = 0
64
+ while True:
65
+ try:
66
+ cycle = nx.find_cycle(safe_dag)
67
+ edge_to_remove = cycle[0]
68
+ safe_dag.remove_edge(*edge_to_remove)
69
+ cycle_count += 1
70
+ print(f"Broke cycle by removing edge: {edge_to_remove}")
71
+ except nx.NetworkXNoCycle:
72
+ break
73
+ print(f"Sanitization complete. Removed {cycle_count} edges to ensure acyclicity.")
74
+ return safe_dag
75
+
76
+
77
+ # ---------------------------------------------------------------------------
78
+ # DREAM4 In Silico Size-100
79
+ # ---------------------------------------------------------------------------
80
+
81
+
82
+ def get_dream4_ground_truth_dag(
83
+ gs_dataframe: pd.DataFrame, node_order: list
84
+ ) -> nx.DiGraph:
85
+ """
86
+ Build the ground-truth DAG for a DREAM4 In Silico Size-100 network.
87
+
88
+ Nodes in the returned graph are integer indices (0-based) corresponding to
89
+ the column order of the multifactorial expression dataset.
90
+
91
+ Args:
92
+ gs_dataframe (pd.DataFrame): Gold-standard file loaded with columns
93
+ ``['cause', 'outcome', 'edge']``. Rows where ``edge == 1`` encode
94
+ true directed edges; rows where ``edge == 0`` are ignored.
95
+ node_order (list[str]): Ordered list of gene names matching the columns
96
+ of the multifactorial data matrix (e.g. ``list(df.columns)``).
97
+
98
+ Returns:
99
+ nx.DiGraph: DAG whose nodes are integer indices 0…(n−1) and whose
100
+ edges correspond to the true causal connections in the gold
101
+ standard. Disconnected genes are included as isolated nodes.
102
+ """
103
+ name_to_idx = {name: idx for idx, name in enumerate(node_order)}
104
+
105
+ true_dag = nx.DiGraph()
106
+ true_dag.add_nodes_from(range(len(node_order)))
107
+
108
+ edges_by_index = []
109
+ for _, row in gs_dataframe.iterrows():
110
+ cause_name = row["cause"]
111
+ outcome_name = row["outcome"]
112
+ edge_exists = row["edge"]
113
+
114
+ if edge_exists == 1:
115
+ if cause_name in name_to_idx and outcome_name in name_to_idx:
116
+ u = name_to_idx[cause_name]
117
+ v = name_to_idx[outcome_name]
118
+ edges_by_index.append((u, v))
119
+
120
+ true_dag.add_edges_from(edges_by_index)
121
+ return true_dag
122
+
123
+
124
+ def run_experiment_dream4(
125
+ subset_number: int,
126
+ sampling_strategy: str = "local",
127
+ frac_req: float = 0.3,
128
+ ) -> tuple[dict, dict]:
129
+ """
130
+ Run a b-LOAD experiment on a DREAM4 In Silico Size-100 network.
131
+
132
+ Pipeline:
133
+
134
+ 1. Load multifactorial expression data and gold-standard edge list.
135
+ 2. Construct the binary ground-truth DAG and sanitize it to a strict DAG.
136
+ 3. Fit oracle linear SEM weights onto the binary DAG structure.
137
+ 4. Enumerate all ancestor–descendant pairs as candidate targets.
138
+ 5. Run :func:`~src.running.run_experiment_mpdag_real` with the specified
139
+ background-knowledge fraction and sampling strategy.
140
+
141
+ Data files are expected at::
142
+
143
+ experiments/dream4/insilico_size100_<subset_number>_multifactorial.tsv
144
+ experiments/dream4/DREAM4_GoldStandard_InSilico_Size100_multifactorial_<subset_number>.tsv
145
+
146
+ Args:
147
+ subset_number (int): DREAM4 network index (1–5).
148
+ sampling_strategy (str): Background-knowledge sampling strategy —
149
+ ``"local"`` (edges incident on targets) or ``"global"`` (all edges).
150
+ frac_req (float): Fraction of true edges to reveal as required
151
+ background knowledge.
152
+
153
+ Returns:
154
+ tuple[dict, dict]: ``(result_dict, details_dict)`` as returned by
155
+ :func:`~src.running.run_experiment_mpdag_real`.
156
+ """
157
+ multifactorial_df = pd.read_csv(
158
+ f"experiments/dream4/insilico_size100_{subset_number}_multifactorial.tsv",
159
+ sep="\t",
160
+ )
161
+ node_order = list(multifactorial_df.columns)
162
+
163
+ dream4_gs = pd.read_csv(
164
+ f"experiments/dream4/DREAM4_GoldStandard_InSilico_Size100_multifactorial_{subset_number}.tsv",
165
+ sep="\t",
166
+ header=None,
167
+ names=["cause", "outcome", "edge"],
168
+ )
169
+
170
+ binary_dag = sanitize_to_dag(get_dream4_ground_truth_dag(dream4_gs, node_order))
171
+
172
+ dream4_data_array = multifactorial_df.to_numpy()
173
+ oracle_dag = fit_oracle_weights(binary_dag, dream4_data_array)
174
+
175
+ forward_pairs_idx = [
176
+ [node, descendant]
177
+ for node in binary_dag.nodes()
178
+ for descendant in nx.descendants(binary_dag, node)
179
+ ]
180
+
181
+ base_args = {
182
+ "data_name": f"dream4_net{subset_number}",
183
+ "real_data": dream4_data_array,
184
+ "true_dag": oracle_dag,
185
+ "observed": dream4_data_array.shape[1],
186
+ "alpha": 0.01,
187
+ "ci_test": "fisherz",
188
+ "sampling_strategy": sampling_strategy,
189
+ "fraction_forbidden": 0,
190
+ "fraction_required": frac_req,
191
+ }
192
+
193
+ result_dict, details_dict = run_experiment_mpdag_real(base_args, 42, forward_pairs_idx)
194
+ return result_dict, details_dict
195
+
196
+
197
+ # ---------------------------------------------------------------------------
198
+ # DREAM5 Network Inference
199
+ # ---------------------------------------------------------------------------
200
+
201
+
202
+ def get_dream5_tf_ground_truth_dag(
203
+ gs_dataframe: pd.DataFrame, tf_order: list
204
+ ) -> nx.DiGraph:
205
+ """
206
+ Build the ground-truth DAG for a DREAM5 sub-network restricted to a list
207
+ of transcription factors (TFs).
208
+
209
+ Only edges where *both* the cause and the outcome are in ``tf_order`` are
210
+ included; all other gold-standard edges are ignored.
211
+
212
+ Args:
213
+ gs_dataframe (pd.DataFrame): Gold-standard file with at least columns
214
+ ``['cause', 'outcome']``. All rows are assumed to be true edges
215
+ (unlike DREAM4, there is no ``edge`` column).
216
+ tf_order (list[str]): Ordered list of TF gene names matching the
217
+ columns of the filtered expression dataset.
218
+
219
+ Returns:
220
+ nx.DiGraph: DAG whose nodes are integer indices 0…(len(tf_order)−1).
221
+ Disconnected TFs are included as isolated nodes.
222
+ """
223
+ name_to_idx = {name: idx for idx, name in enumerate(tf_order)}
224
+
225
+ true_dag = nx.DiGraph()
226
+ true_dag.add_nodes_from(range(len(tf_order)))
227
+
228
+ edges_by_index = []
229
+ for _, row in gs_dataframe.iterrows():
230
+ cause_name = row["cause"]
231
+ outcome_name = row["outcome"]
232
+ if cause_name in name_to_idx and outcome_name in name_to_idx:
233
+ u = name_to_idx[cause_name]
234
+ v = name_to_idx[outcome_name]
235
+ edges_by_index.append((u, v))
236
+
237
+ true_dag.add_edges_from(edges_by_index)
238
+ return true_dag
239
+
240
+
241
+ def run_experiment_dream5(
242
+ subset_number: int,
243
+ sampling_strategy: str = "local",
244
+ frac_req: float = 0.3,
245
+ ) -> tuple[dict, dict]:
246
+ """
247
+ Run a b-LOAD experiment on a DREAM5 network inference sub-network.
248
+
249
+ Pipeline:
250
+
251
+ 1. Load the filtered expression dataset and gold-standard edge list for
252
+ the specified network.
253
+ 2. Construct the ground-truth DAG over TFs and sanitize it.
254
+ 3. Fit oracle linear SEM weights.
255
+ 4. Enumerate ancestor–descendant pairs as candidate targets.
256
+ 5. Run :func:`~src.running.run_experiment_mpdag_real`.
257
+
258
+ Data files are expected at::
259
+
260
+ experiments/dream5/net<subset_number>_expression_data.tsv
261
+ experiments/dream5/DREAM5_NetworkInference_GoldStandard_Network<subset_number>.tsv
262
+
263
+ Args:
264
+ subset_number (int): DREAM5 network index (1–4).
265
+ sampling_strategy (str): ``"local"`` or ``"global"``.
266
+ frac_req (float): Fraction of true edges to reveal as required BK.
267
+
268
+ Returns:
269
+ tuple[dict, dict]: ``(result_dict, details_dict)``.
270
+ """
271
+ expression_df = pd.read_csv(
272
+ f"experiments/dream5/net{subset_number}_expression_data.tsv", sep="\t"
273
+ )
274
+ tf_order = list(expression_df.columns)
275
+ expression_array = expression_df.to_numpy()
276
+
277
+ dream5_gs = pd.read_csv(
278
+ f"experiments/dream5/DREAM5_NetworkInference_GoldStandard_Network{subset_number}.tsv",
279
+ sep="\t",
280
+ header=None,
281
+ names=["cause", "outcome"],
282
+ )
283
+
284
+ binary_dag = sanitize_to_dag(get_dream5_tf_ground_truth_dag(dream5_gs, tf_order))
285
+ oracle_dag = fit_oracle_weights(binary_dag, expression_array)
286
+
287
+ forward_pairs_idx = [
288
+ [node, descendant]
289
+ for node in binary_dag.nodes()
290
+ for descendant in nx.descendants(binary_dag, node)
291
+ ]
292
+
293
+ base_args = {
294
+ "data_name": f"dream5_net{subset_number}",
295
+ "real_data": expression_array,
296
+ "true_dag": oracle_dag,
297
+ "observed": expression_array.shape[1],
298
+ "alpha": 0.01,
299
+ "ci_test": "fisherz",
300
+ "sampling_strategy": sampling_strategy,
301
+ "fraction_forbidden": 0,
302
+ "fraction_required": frac_req,
303
+ }
304
+
305
+ result_dict, details_dict = run_experiment_mpdag_real(base_args, 42, forward_pairs_idx)
306
+ return result_dict, details_dict