dag.BuildModelFromDAG

Build a probabilistic model directly from a causal DAG and a dataset.

Usage

dag.BuildModelFromDAG(
    *,
    dag,
    df,
    target,
    dims=None,
    coords=None,
    model_config=None,
    time_dim="date",
    style="digraph",
    families=None,
    priors=None,
    latent=None
)

The DAG is read as a structural model: each node is a column in df and each edge A -> B contributes a slope from A into the mean of B. Two build styles are available:

style="digraph" (default) — a fully linear Gaussian model built directly in PyMC. Every node gets an intercept, a slope per parent, and a likelihood; observed data is aligned to dims/coords via xarray. dims and coords are required.
style="native" — the DAG is translated to pathmc’s DSL (see dag_to_spec()) and compiled with pathmc.model(), so the richer pathmc machinery (families, transforms, latent variables, custom priors) becomes available. dims/coords/model_config do not apply; pass families/priors/latent instead.

Parameters

dag: str | networkx.DiGraph: DAG in DOT format ("digraph { A -> B; }"), an "A->B" edge list, or a networkx.DiGraph.
df: pandas.DataFrame: DataFrame containing a column for every DAG node (and, for the digraph style, every column named in dims).
target: str: Name of the target node; validated to exist in the DAG.
dims: tuple[str, …] | None = None: (digraph style) Dims for the observed/likelihood variables, e.g. ("date",) or ("date", "country"). Required when style="digraph".
coords: dict | None = None: (digraph style) Coordinate values for dims (and any prior dims). All keys must be columns of df. Required when style="digraph".
model_config: dict | None = None: (digraph style) Optional Prior objects for "intercept", "slope" and "likelihood"; missing keys fall back to :pyattr:default_model_config.
time_dim: str = "date": (digraph style) Name of the time dimension within dims. It is the one dim that slope/intercept priors are not broadcast over (slopes vary across the remaining, cross-sectional dims but are shared across time). Defaults to "date"; set it to match your own time column ("week", "t", …) so slopes are not accidentally given a per-timestep dimension.
style: ("digraph", "native") = "digraph": Which builder to use (see above). Defaults to "digraph".
families: dict[str, str] | None = None: (native style) Per-variable distribution families forwarded to pathmc.model().
priors: dict[str, Any] | None = None: (native style) Custom priors forwarded to pathmc.model().
latent: list[str] | None = None: (native style) Latent variables forwarded to pathmc.model().

Examples

Digraph style (fully linear)::

import numpy as np, pandas as pd
from pathmc import BuildModelFromDAG

dates = pd.date_range("2024-01-01", periods=5, freq="D")
df = pd.DataFrame({
    "date": dates,
    "X": np.random.normal(size=5),
    "Y": np.random.normal(size=5),
})
builder = BuildModelFromDAG(
    dag="X->Y", df=df, target="Y", dims=("date",), coords={"date": dates}
)
pymc_model = builder.build()

Native style (full pathmc flexibility)::

builder = BuildModelFromDAG(
    dag="X->Y", df=df, target="Y", style="native", families={"Y": "gaussian"}
)
path_model = builder.to_pathmodel()
path_model.fit(draws=500, tune=500)

Attributes

Name	Description
default_model_config	Default `Prior` objects for intercepts, slopes and likelihood.

default_model_config

Default Prior objects for intercepts, slopes and likelihood.

default_model_config: dict[str, Prior]

Methods

Name	Description
build()	Construct and return the PyMC model implied by the DAG and data.
dag_graph()	Return a copy of the parsed DAG as a `networkx.DiGraph`.
model_graph()	Return a Graphviz visualization of the built model.
to_pathmodel()	Return the native `pathmc.PathModel` for this DAG.

build()

Construct and return the PyMC model implied by the DAG and data.

Usage

build()

For style="digraph" this builds the fully linear Gaussian model directly. For style="native" it compiles via pathmc.model() and returns the underlying PyMC model (use to_pathmodel() for the richer pathmc object).

Returns

pymc.Model: The compiled PyMC model. For style="digraph" this is a fully linear Gaussian model with a slope per edge and a likelihood for every node. For style="native" it is the model produced by pathmc.model(), whose families and latent nodes determine the parametrization (latent nodes have no likelihood).

dag_graph()

Return a copy of the parsed DAG as a networkx.DiGraph.

Usage

dag_graph()

Returns

networkx.DiGraph: A directed acyclic graph with the same nodes and edges as input.

model_graph()

Return a Graphviz visualization of the built model.

Usage

model_graph()

Returns

graphviz.Source | graphviz.Digraph: Graphviz object representing the model graph.

Raises

RuntimeError: If called before build() (digraph style).

to_pathmodel()

Return the native pathmc.PathModel for this DAG.

Usage

to_pathmodel()

Only available for style="native". The returned model exposes the full pathmc API (fit, do, ate, falsify, …).

Returns

PathModel: The compiled pathmc model.

Raises

RuntimeError: If called on a style="digraph" builder.