protocol
Backend-agnostic protocol for a data generation process (DGP).
A DGP is a bundle of per-node mechanisms: each node's mechanism is
fitted independently from (data, its parents) — the modularity assumption,
the same one DoWhy's gcm fitting states explicitly. Everything above this
protocol (interventions, cascades, joint sampling) is generic algebra
written once in badgers.core.dgp.base;
backends never implement cascades and never learn about deficits.
DGP
Bases: Protocol
Protocol for a per-node data generation process.
Source code in badgers/core/dgp/protocol.py
20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 | |
draw_noise(node, rng, n)
Draw n shocks from the node's own (fitted) noise.
Representation-free by design: parametric backends draw from their fitted scale, empirical backends resample their residuals.
Source code in badgers/core/dgp/protocol.py
66 67 68 69 70 71 72 73 | |
fit(X)
Fit every node's mechanism in topological order; return self.
DGPMixin provides the default topological walk over
fit_node; backends that do not inherit it must implement
fit themselves. Generators call fit on any backend passed
via fit(dgp=...).
Source code in badgers/core/dgp/protocol.py
28 29 30 31 32 33 34 35 36 | |
fit_node(node, parents, data)
Fit ONE node's mechanism from (data, parents).
This is the only backend-specific operation. For a root node (no parents) the mechanism is a distribution (fitted mean + spread).
Source code in badgers/core/dgp/protocol.py
48 49 50 51 52 53 54 55 | |
intervene(rows, nodes, values=None, *, rng=None)
Pearl surgery applied to GIVEN rows: fix the nodes at values,
recompute all their descendants (topological order, fresh noise).
DGPMixin provides the generic implementation; backends may
override it natively, preserving the same semantics (upstream and
non-descendant columns and rows untouched; intervened nodes keep
their fixed values even if they are descendants of other
intervened nodes).
NOTE: structure edits are intentionally NOT part of this protocol.
The DGP is an immutable, fitted world; structural modifications
live in badgers.core.dgp.edits (free functions returning a new
world: scale_edge/remove_edge/add_edge_contribution/
exogenize/set_form).
Source code in badgers/core/dgp/protocol.py
109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 | |
is_fitted()
True iff every structural node has a fitted mechanism.
Generator-side convenience: lets a generator fit an UNFITTED DGP lazily on the generate-time data while leaving a fitted one untouched. Backend-specific storage means backends implement this; read-only views delegate to the DGP they wrap.
Source code in badgers/core/dgp/protocol.py
38 39 40 41 42 43 44 45 46 | |
pick_parameters(rng=None)
Hook called ONCE at the top of sample/intervene: return
the DGP instance whose mechanisms drive this cascade.
Generic default (DGPMixin): self — deterministic backends
fit exactly one parameter set. Uncertainty-carrying backends
override it: they select ONE coherent parameter draw from rng
and return a read-only view of themselves evaluating it. The DGP
keeps every draw from fit; the choice is made at the top of
each cascade from the caller's rng — never inside response
and never by mutating the fitted DGP.
Source code in badgers/core/dgp/protocol.py
93 94 95 96 97 98 99 100 101 102 103 104 105 | |
response(node, parent_values)
Evaluate the fitted response of node for given parent values.
parent_values has shape (n_rows, len(parents)); for a root
node it must have shape (n_rows, 0). Returns shape (n_rows,).
Source code in badgers/core/dgp/protocol.py
57 58 59 60 61 62 63 64 | |
sample(rng, n)
Tier 2: sample n joint rows from the fitted graph.
Source code in badgers/core/dgp/protocol.py
89 90 91 | |
structural(node, parent_values, rng, n)
Compose ONE node's values for a cascade: deterministic part + noise.
Default (DGPMixin): the additive composition
response(parent_values) + draw_noise(node, rng, n). Backends
whose mechanisms are not additive override it — e.g. the gcm
backend delegates the composition to the mechanism's own
evaluate(parents, noise) (rounded discrete predictions, class
CDFs) while still drawing the noise with rng.
Source code in badgers/core/dgp/protocol.py
75 76 77 78 79 80 81 82 83 84 85 86 87 | |