ergodic 0.1.0__tar.gz

ergodic-0.1.0/.gitignore

@@ -0,0 +1,50 @@
+plans/
+.devcontainer/
+
+# ---- Python ----
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution / packaging
+.Python
+build/
+dist/
+wheels/
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Test / type / lint caches
+.pytest_cache/
+.mypy_cache/
+.dmypy.json
+.ruff_cache/
+.cache/
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+
+# Docs build
+site/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# Environments / secrets
+.env
+
+# OS / editor
+.DS_Store
+*.swp
+.idea/
+.vscode/
+
+# Claude Code local config
+.claude/

ergodic-0.1.0/CHANGELOG.md

@@ -0,0 +1,394 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial project scaffolding: the `ergodic` package with `discovery`, `inference`,
+  and `process` subpackages (placeholders).
+- Tooling: uv project layout, ruff (lint + format), mypy (strict), pytest.
+- MkDocs Material documentation skeleton, pre-commit hooks, and a Makefile.
+- Causal graph objects (`ergodic.graph`): a mixed-graph core with typed endpoint
+  marks covering DAG, ADMG, MAG, CPDAG, and PAG; immutable value semantics; d- and
+  m-separation; the do-operator and subgraphs; networkx, adjacency, and dict interop.
+- Domain knowledge (`ergodic.knowledge`): hard prior constraints (required and
+  forbidden edges, tiers, roots, sinks, confounded pairs) with composition, conflict
+  detection, and projections (`permits_edge`, `is_consistent`, `apply_to`, `edge_mask`).
+- Identification (`ergodic.identification`): `identify_effect` plus the complete
+  adjustment criterion, the front-door criterion, and conditional instruments, turning a
+  graph and a treatment/outcome into an estimand.
+- Typed data objects (`ergodic.data`): a `Dataset` base with a column `Schema`
+  (continuous, categorical, ordinal, datetime, excluded) across five shapes,
+  `tabular`, `timeseries`, `panel`, `hts` (with a `Hierarchy` aggregation tree),
+  and `event_log`. Immutable, with type inference and overrides, codes and a float
+  matrix, missing-value handling, and `aligns_with(graph)`. A dataframe builds it
+  and stays at the boundary; pandas native, polars and arrow through `to_pandas`.
+- Effect estimation (`ergodic.inference`): `estimate_effect` identifies an effect
+  and estimates it over `TabularData`, returning a distribution-shaped
+  `EffectEstimate` (a point with an analytic or bootstrap standard error, or
+  draws). A `CausalEstimator` is the strategy and a `Learner` is the model in each
+  nuisance slot; the learner is structurally a sklearn estimator. Adjustment:
+  `OutcomeRegression` (S- and T-learner), `IPW`, `Stratification`, `AIPW`, and the
+  cross-fit `DML`, `DRLearner`, `RLearner`, and `XLearner`; front-door:
+  `TwoStageRegression`; instruments: `TwoStageLeastSquares`, `Wald`, and `PLIV`.
+  Heterogeneous effects (CATE) through `cate`, binary or continuous treatment for
+  `DML` and `PLIV`, and native `OLS`, `LogisticRegression`, and `KNN` learners.
+- Bayesian learners (`ergodic.inference`): a `BayesianLearner` carries a posterior
+  over its mean function (detected by `predict_draws`), and a `PyMCLearner` /
+  `PyMCClassifier` wraps a user-written PyMC model (pymc optional, `ergodic[bayes]`).
+  `OutcomeRegression` (the Bayesian g-formula) and `AIPW` (doubly robust, with a
+  Dirichlet Bayesian bootstrap) return a posterior `EffectEstimate` through the same
+  accessors, and the T-learner reports per-unit CATE credible intervals via
+  `cate_draws` and `cate_interval`.
+- Explicit treatment coding: `estimate_effect(..., treated=...)` picks which level
+  counts as treated, and an implicit non-numeric coding now warns with the chosen
+  levels (a string treatment used to be coded by alphabetical order, silently).
+- The `"null"` identification strategy and `NullEffect` estimator: a graph with no
+  directed path from treatment to outcome identifies trivially as a zero effect.
+- `as_kind` accepts the kind name as a string (`g.as_kind("admg")`).
+- Stratified cross-fitting folds for binary treatments, bootstrap shortfall
+  diagnostics, and a clear error when a treatment arm is empty.
+- Causal discovery (`ergodic.discovery`), the first build: a conditional
+  independence test is a class constructed with data (the stateful oracle:
+  encoding once, sufficient statistics, cached alpha-independent queries),
+  with `Linear` (partial correlation), `Discrete` (G squared, natively
+  categorical), `Mixed` (degenerate Gaussian for mixed columns), and a
+  `DSeparationOracle` ground truth; a decomposable `Score` answers
+  `local(node, parents)` with `BIC` (Gaussian); PC-stable orients through
+  v-structures and the Meek rules and returns a CPDAG with separating sets;
+  `AStar` is exact search over the order lattice; `discover(data, method=...)`
+  is the facade and `discover` re-exports at the top level. Background
+  knowledge enters in four modes (prune, protect, orient, validate), and
+  `DomainKnowledge.restrict_to(skeleton)` confines any search to an adjacency
+  support. The Meek rules, `cpdag_of_dag`, and the Dor-Tarsi extension check
+  live in `ergodic.graph`, which makes `is_cpdag` a real validator.
+- Causal discovery, the score stack: `GES` (Chickering's greedy equivalence
+  search, held to the A* optimum in the tests) and `HillClimb` (steepest
+  ascent with a tabu list) consume the same `Score` contract as `AStar`;
+  `DiscreteBIC` (multinomial), `BDeu`, and `MixedBIC` (degenerate Gaussian,
+  no edge restriction) join the Gaussian `BIC`, with executable
+  score-equivalence tests; the `Score` base gains a native-categorical codes
+  form (`local_from_codes`); `score="auto"` picks the score from the column
+  schema the way `test="auto"` picks the test; and `GCM` (Shah and Peters)
+  turns any regression `Learner`, native or sklearn, into a conditional
+  independence test that catches nonlinear dependence the partial correlation
+  misses. `DSeparationOracle` now answers about the observed margin (latent
+  nodes are not query-able variables).
+- Causal discovery with latent confounders: `FCI` returns a PAG (stable
+  skeleton, the possible-d-sep phase, Zhang's complete rule closure, no
+  selection bias), held in the tests to the canonical PAG of the truth under
+  a perfect oracle. The graph layer grew the toolkit underneath:
+  m-separation now reads circle marks through definite-status paths (the
+  class-invariant answer on a complete PAG), `mag_of_dag` is the latent
+  projection, `pag_of_mag`/`mag_of_pag` convert between a MAG and its
+  equivalence class, `fci_closure` joins `meek_closure`, `set_mark` edits one
+  endpoint, and `is_pag` became a real complete-PAG validator by round trip,
+  exactly as `is_cpdag` did. Domain knowledge translates to PAGs through
+  ancestry: tiers pin an arrowhead at the later end, `confound(a, b)` orients
+  a bidirected edge, directional forbids and roots/sinks validate only.
+- Skeleton screening and stability: `MMPC` (max-min parents-children, AND
+  rule) returns an undirected support for `restrict_to`, recovering the MMHC
+  hybrid as a composition; `bootstrap` reruns any method on row resamples and
+  returns adjacency and orientation frequencies with a thresholded
+  `summary()` graph, the first soft output. `Dataset.take(rows)` resamples
+  rows, and `discover` dispatches on each algorithm's declared ingredient.
+- Identification on equivalence classes: `identify_effect`, `adjustment_set`,
+  `minimal_adjustment_set`, and `is_valid_adjustment_set` accept a CPDAG,
+  MAG, or PAG and answer through the generalized adjustment criterion
+  (Perkovic et al., 2018), so a success holds in every graph the class
+  represents and `estimate_effect` runs straight off a discovery result.
+  Held executably to the all-members definition: exhaustive over candidate
+  sets against the enumerated members of small random classes. The graph
+  layer grew the toolkit underneath: `possible_descendants` and
+  `possible_ancestors` (possibly directed reachability), `visible_edges`
+  (Zhang's no-hidden-confounding certificate), and the member enumerators
+  `dags_of_cpdag` and `mags_of_pag` (deterministic, capped without silent
+  truncation). The front-door and instruments raise on a class and point at
+  the enumerators (the per-member IDA pattern); mixed graphs raise.
+- Quasi-experimental designs (`ergodic.inference`): estimators that read the
+  panel structure instead of a graph, each stating its identification in a
+  `Design` record and returning the same `EffectEstimate` surface. `did` over
+  a `PanelData` runs the canonical two-period collapse for a single adoption
+  date and Callaway-Sant'Anna group-time ATTs for staggered adoption (with
+  `comparison="never_treated"` or `"not_yet_treated"` and unit-bootstrap
+  inference); static two-way fixed effects ships as an explicit strategy with
+  its staggered-adoption caveat and is never auto-picked. `event_study`
+  reports ATT by event time with leads as the visible pre-trend check.
+  `synthetic_control` fits simplex weights on the pre-period by projected
+  gradient and reports per-period gaps with Abadie's in-space placebo
+  inference (the RMSPE-ratio rank p-value; intervals come from the placebo
+  band on purpose). `interrupted_time_series` over a `TimeSeriesData` is
+  segmented regression with level and slope changes, optional seasonal terms,
+  and Newey-West standard errors. All four re-export at the top level.
+- Temporal causal discovery (`ergodic.discovery`): `discover(data,
+  method="pcmci", max_lag=...)` accepts a `TimeSeriesData` or `PanelData`
+  (panels pool windows within entities) and returns a
+  `TimeSeriesDiscoveryResult` holding a window graph over lagged nodes like
+  `X[t-1]`, per-link p-values, and a variable-level `summary_edges()`. The
+  algorithm is PCMCI-shaped: a PC1 lagged-parent screen, momentary
+  conditional independence tests for lagged links (conditioning sets drawn
+  from a deeper lagged frame), a PC-stable contemporaneous phase conditioned
+  on lagged parents, and collider plus within-slice Meek orientation. It
+  reuses the existing `CITest` stack through `lagged_tabular`, so
+  `test="auto"` and the cache come free. `granger` is the predictive
+  baseline and returns a pair-level table rather than a graph (feedback
+  across lags is normal; the docstring says what Granger does not claim).
+  Shape guards keep the methods honest: iid methods reject temporal data
+  (rows are not exchangeable), `pcmci` rejects tabular data, and `bootstrap`
+  refuses temporal methods until a moving-block variant exists.
+- The learn series: six beginner notebook guides (`docs/learn/`) that teach
+  causal inference from zero on commercial examples, confounding and Simpson's
+  paradox, good and bad controls, estimation with doubly robust and cross-fit
+  estimators, heterogeneous effects and uplift targeting, instruments and the
+  front door, and structure discovery ending at the discover-then-estimate
+  bridge. Each guide is a py:percent script that mkdocs-jupyter executes at
+  build time with fixed seeds, so the outputs and figures on the site are real
+  and a broken example fails `make docs`. Docs review alongside: the API
+  reference gains the discovery section (guide pages no longer inline `:::`
+  blocks), stale forward references brought current, and the index routes
+  beginners to the series.
+- Learn guide 7, quasi-experiments: a staggered promo rollout recovered with
+  difference-in-differences and an event study, and a flagship market's price
+  change measured against its synthetic control, with the naive comparisons
+  failing first. A new "Panel and time-series designs" guide page documents
+  the design family, and the discovery guide gains its time-series section.
+- Process intelligence (`ergodic.process`), the first build. The descriptive
+  layer recovers the daily workflow over an `EventLog`: `process_map` (the
+  directly-follows map as a value object with frequency and gap statistics
+  and a `simplify` that records exactly what it dropped), `performance`
+  (cycle times, and a waiting/service split when a lifecycle column carries
+  start/complete pairs; with one timestamp per activity the split is honestly
+  impossible and the result says so), `variant_table`, and six composable
+  filters (time, variants, endpoints, activities, follows, performance), each
+  declaring whether it drops events or whole cases and refusing to return an
+  empty log. The causal layer is the point: `case_table` encodes a log into
+  one row per case with timestamp-gated features (case-start features in
+  `when="anytime"`; landmark modes `("after_events", k)` and
+  `("after_elapsed", x)` measure prefix features at the landmark, drop
+  already-treated cases with counts, and state their population), the named
+  process confounders (open-case workload, calendar features), and an
+  auto-built `DomainKnowledge` whose tiers forbid post-treatment adjustment
+  mechanically, feeding `discover`, `identify_effect`, and `estimate_effect`
+  unchanged; `kpi_panel` aggregates a log into a `PanelData` (or a single
+  `TimeSeriesData`) so a process change becomes a natural experiment for the
+  quasi-experimental designs. Learn guide 8 walks the whole arc: the process
+  map convicts a review step of double its true cost, the case table acquits
+  it, and a routing rollout is measured with `kpi_panel` into `did`.
+- The process model layer (`ergodic.process`, second build). `discover_model`
+  is the Inductive Miner implemented from the papers (pm4py is AGPL and is not
+  used): recursive cuts of the directly-follows graph (exclusive choice,
+  sequence, parallel, loop) into a block-structured `ProcessTree` (build one
+  by hand with `seq`, `xor`, `par`, `loop`, and `TAU`; structural equality,
+  canonical child order), with the infrequent variant behind `noise=` and
+  provenance on the returned `ProcessModel` (flower fall-through paths,
+  filtered arcs, dropped events). `ProcessTree.to_net()` converts to a
+  `WorkflowNet` that is sound by construction, and `is_sound` verifies any
+  net for real by reachability (option to complete, proper completion, no
+  dead transitions; capped, raising past the cap rather than guessing).
+  `conformance` checks a log against a model by token replay (the standard
+  missing/remaining/consumed/produced fitness) and by optimal alignments
+  (Dijkstra over the synchronous product with deterministic tie-breaking;
+  per-variant costs and sync/log/model moves). `decision_points` and
+  `decision_table` read an exclusive split causally: the branch taken is the
+  treatment, the landmark is the moment the case reveals its branch, every
+  covariate is measured strictly before it (workload, calendar, prefix
+  features, case attributes), the auto-built `DomainKnowledge` tiers order
+  covariates before branch before outcome, the default outcome is the
+  remaining time from the decision, and a first-class `PositivityReport`
+  (per-branch counts and shares, propensity overlap for two-way splits)
+  warns when the branches barely overlap. Splits with a silent branch are
+  refused with the reason. Learn guide 9 walks the arc: the miner finds the
+  routing split, conformance separates deviation from structure, the naive
+  lane comparison overstates the cost of review by a factor of three, and
+  the decision table recovers the planted effect.
+- Learn guide 8, process mining: the descriptive workflow on its own, in
+  three steps on a simulated fulfillment flow, with the process maps drawn
+  as real graphs (traffic-scaled arrows, counts and median gaps on every
+  arc): see the process, measure it (the waiting-versus-service split finds
+  the planted pick queue, eight hours of waiting in front of 26 minutes of
+  work), and drill into the slice that hurts, with `simplify` declaring what
+  it dropped. The process guides renumber to make room: process intelligence
+  is guide 9 and decision points is guide 10.
+- Selection bias end to end in the graph layer: `is_mag` reads the full
+  Richardson-Spirtes ancestral conditions (undirected endpoints carry no
+  arrowheads), `mag_of_dag` projects latent and selection nodes together
+  through the one-witness-set theorem, `fci_closure` runs Zhang's complete
+  ten rules (R5 to R7 are the selection rules), `mag_of_pag` resolves
+  circle-tail edges by arrowhead augmentation, and `mags_of_pag` enumerates
+  the selection members behind an explicit `selection=` switch. The
+  d-separation oracle conditions every query on `graph.selection`, so FCI
+  needs no algorithmic change and lands exactly on the canonical PAG of
+  random latent-plus-selection worlds, held executably (Richardson-Spirtes
+  Theorem 4.18, round trips, and the chordless-cycle world only R5 can
+  orient). Identification raises on selection marks instead of silently
+  misreading them.
+- Discovery D4, the iid completion. PC gains `colliders="conservative"`
+  and `"majority"` (Ramsey 2006; Colombo-Maathuis 2014): unshielded triples
+  are voted across both neighborhoods' subsets, ambiguous triples are never
+  oriented and gate Meek R1/R3 through `meek_closure`'s new `ambiguous=`
+  parameter, and the face stays honest. RFCI (`method="rfci"`) skips FCI's
+  possible-d-sep phase, re-tests triples and discriminating paths instead,
+  and returns an RFCI-PAG whose marks stay sound (held executably against
+  random latent, confounded, and selection worlds, with exact FCI agreement
+  wherever possible-d-sep has nothing to do). BOSS and GRaSP (`method=
+  "boss"`, `"grasp"`) search permutations through a grow-shrink projection,
+  BOSS with a BES pass reusing GES's backward phase, both held to the A*
+  optimum. DirectLiNGAM (`method="lingam"`) fully orients a DAG from
+  non-Gaussian data with the Hyvarinen-Smith pairwise likelihood ratio and
+  native backward-BIC pruning. A graphical-lasso screen (`method="glasso"`)
+  estimates a sparse precision by block coordinate descent (matching
+  sklearn entry for entry), picks the penalty by EBIC at the
+  support-restricted refit MLE, and feeds `restrict_to` like MMPC. The
+  facade learns methods that consume neither a test nor a score.
+- Temporal unblockers: `bootstrap` accepts `method="pcmci"` through a
+  moving-block design (a series resamples blocks that become entities of a
+  panel, so no lag window ever crosses a block seam; a panel resamples
+  whole entities; `block_length` overrides the default), and PCMCI reads
+  `DomainKnowledge` with variables as processes: forbids, tiers, roots, and
+  sinks prune at every lag, tiers orient contemporaneous edges, self-memory
+  survives, `require` validates after the run, and `confound` raises.
+- Real-world datasets (`ergodic.datasets`), the first set: sklearn-style loaders
+  that return a `Bunch` carrying the typed dataset under `data` plus its causal
+  question (treatment, outcome, confounders or instrument, and the `target` the
+  literature already measured). `load_birthweight` (maternal smoking, backdoor
+  adjustment), `load_berkeley` (the 1973 admissions table, Simpson's paradox),
+  `load_pension401k` (401(k) eligibility, double machine learning), `load_smoking`
+  (Proposition 99, synthetic control) and `load_germany` (reunification), and
+  `load_asia` / `load_earthquake` (small networks written from their papers and
+  sampled, for discovery). The bundled data ships in the wheel; provenance and
+  citations are in the NOTICE. Example scripts in `examples/` run each analysis
+  next to its known answer, and the tests check the recovery (smoking lands within
+  the placebo band at -21 packs, double ML moves the pension gap from $19.5k to
+  about $9k, the Berkeley gap reverses under department).
+- Refutation (`ergodic.inference`): `refute_effect(graph, data, treatment, outcome,
+  method=...)` stress-tests an estimate by re-running it under a perturbation and
+  returns a `Refutation`. The model-agnostic checks: `"placebo_treatment"` scrambles
+  the treatment and the effect should vanish, `"random_common_cause"` adds an
+  irrelevant covariate and the effect should hold, `"data_subset"` re-estimates on a
+  random slice. None proves an estimate right; a failure is a real warning. The
+  sharper confounder-specific sensitivity (partial R-squared, the E-value) comes
+  later. `refute_effect` and `Refutation` re-export at the top level.
+- Case studies (`docs/case-studies/`): five narrative pages that apply the tools to
+  a famous dataset and recover the number the original study published. Smoking and
+  birthweight (backdoor adjustment), the 1973 Berkeley admissions paradox (Simpson's
+  paradox), 401(k) eligibility (double machine learning), Proposition 99 (synthetic
+  control), and structure discovery on a known network. Each opens with a causal
+  balance table, shows the naive answer failing, recovers the published figure, and
+  ends with a refutation check. They execute on every docs build, so the prose and
+  the code stay in step.
+- The general do-calculus ID algorithm (`ergodic.identification`):
+  `identify_distribution(graph, outcome, do, given=...)` runs Shpitser-Pearl ID
+  (and IDC when `given` is set) on a single DAG or ADMG, deciding whether
+  `P(outcome | do(do), given)` is identifiable and returning the estimand as a
+  typed `Functional` (the `Prob` / `Product` / `Marginal` / `Ratio` algebra, with
+  `render`, `free_vars`, and `simplify`; public but marked provisional) or the
+  `Hedge` witness when it is not. An empty `do` is the observational query.
+  `identify_effect` now falls through to general ID after its named ladder misses
+  on a single graph, so a graph that is do-calculus identifiable but outside
+  adjustment, the front-door, and instruments (the Verma graph and its kin)
+  returns `strategy="id"` with the functional set; a non-identifiable graph
+  returns `strategy="none"` with the hedge. The `Identification` record gained
+  `functional` and `hedge` fields. `ida(graph, treatment, outcome)` identifies
+  across an equivalence class: it enumerates the members of a CPDAG and runs
+  `identify_effect` per member, returning an `IDA` record (`members`,
+  `n_identifiable`, `all_identifiable`, `agree`, `strategies`, `estimands`); PAG
+  and MAG members need a DAG realization and raise a clear "not built" for the
+  general case. Held executably to the soundness-against-truth anchor (the
+  functional evaluated on random discrete worlds matches the truth) and the
+  identifiability catalog.
+- The discrete plug-in estimator (`ergodic.inference`): `estimate_effect` on a
+  discrete `strategy="id"` graph estimates the general functional directly,
+  evaluating the empirical sum-product with a bootstrap standard error. Discrete-
+  only and binary-treatment guarded, with a positivity check that raises on an
+  empty stratum the formula divides by (the discrete analog of the overlap check);
+  a continuous variable raises and points at the SCM path (not built).
+- Mediation (`ergodic.identification`, `ergodic.inference`):
+  `identify_mediation(graph, treatment, outcome, mediators)` decides the natural
+  direct and indirect effects (NDE, NIE) via a covariate set that blocks the X-Y,
+  X-M, and M-Y back-doors (the three adjustment conditions), stating the cross-
+  world assumption (no mediator-outcome confounder affected by treatment) in words
+  since no data can test it, and returns a `MediationID`. The controlled direct
+  effect (CDE) routes through the general ID engine as a plain interventional
+  contrast and can identify even when NDE and NIE do not.
+  `estimate_mediation(graph, data, treatment, outcome, mediators, ...)` is the
+  g-computation estimator: NDE, NIE, and the total effect (each a distribution-
+  shaped `EffectEstimate`), the per-level CDE, a `Design` record naming the
+  assumptions, and `proportion_mediated` (flagged when the total effect is near
+  zero). Binary treatment and a discrete mediator; held to a planted linear world
+  where NDE and NIE recover the structural coefficients.
+- Forecasting (`ergodic.forecast`), v1: `forecast(data, horizon)` fits a Bayesian
+  `TemporalMechanism` per series and returns a distribution-shaped `ForecastResult`
+  (per-node draws, `median`, `interval`, `to_frame`, provenance, and per-node
+  sampler diagnostics). The mechanism zoo is `StructuralMechanism` (a damped local
+  linear trend times a season plus a regression on graph parents, composed from
+  those pieces rather than fused), `CausalOU` (drivers move the long-run attractor,
+  so the transient answers "when" and not just "how much"), `Bass` (the diffusion
+  S-curve), and `ScenarioMechanism`; mechanisms are auto-assigned from the schema
+  with the seasonal period read off the time index, and count or categorical
+  columns raise at a named seam. Hierarchies reconcile without refitting through
+  `reconcile(result, hierarchy, method=...)`: `bottom_up`, `top_down` (historical or
+  per-draw forecast proportions), `middle_out`, and the `mint` projection (diagonal
+  posterior weights or `mint_shrink`, with `trust={node: w}`), each coherent to
+  machine epsilon read relative to the size of each parent. Drivers ride a window
+  graph over lagged names, exactly what `discover(..., method="pcmci")` returns:
+  staged fitting walks the `TrainingSchedule` and hands each node's whole forecast
+  posterior down to its children by injecting it into the child's trace, joint
+  fitting puts every node in one model and keeps the cross-node correlation, and
+  `fit="auto"` picks between them. `scenario=` pins a known future (an array, a
+  scalar, or `"hold"`) and states that it makes no causal claim; pinning an
+  endogenous node is refused by name and points at the `do=` that waits for
+  identification on window graphs. `backtest(model, data, ...)` scores anything that
+  fits a series and forecasts a horizon at rolling origins, with `Naive`,
+  `SeasonalNaive`, and `Drift` baselines, fifteen metrics including MASE and CRPS,
+  per-fold seeds, and the sampler's own report aggregated per fold;
+  `forecast_model(**options)` wraps the facade as a backtestable model.
+  `ForecastResult.explain()` returns the attribution waterfall: a baseline bar, a
+  seasonality bar, and one bar per driver over any `Window` of the horizon, each
+  carrying posterior draws and a credible interval, summing to the total with a
+  reported `closure_error`. The structural engine recomposes the mechanism's own
+  recorded pieces and costs no sampling; the replay engine (for a mechanism that
+  does not expose them) zeroes the factor's sites in a copy of the trace and
+  forecasts again on the stored seed. pymc is optional, `pip install
+  ergodic[forecast]`, and the bare install never imports it.
+
+### Fixed
+- Instruments: descendants of the treatment are no longer certified as instruments
+  (the exclusion test was unsound); latent nodes are excluded from adjustment sets,
+  front-door sets, instruments, and conditioning sets; identification validates its
+  inputs (unknown names and overlapping treatment/outcome raise); multi-treatment
+  adjustment validity follows proper causal paths exactly.
+- Graph construction: conflicting duplicate edges on one node pair raise instead of
+  silently keeping the last one (also through `add_edge`, `from_networkx`, and
+  `from_dict`); write a bow as an explicit latent confounder with `latent=`.
+  Separation queries reject unknown node names instead of returning a wrong answer.
+- Domain knowledge: `forbid_adjacency` covers bidirected and undirected edges;
+  `conflicts` catches cycles spanning required edges and tier order together;
+  precedence is transitively closed; `confound(a, a)` raises; the cycle checks no
+  longer recurse (deep graphs build fine).
+- Data: datasets copy their columns at the boundary, so mutating the source
+  dataframe or array no longer mutates the dataset; tz-aware datetimes infer as
+  datetime; missing categoricals and NaT reach `matrix()` as NaN instead of
+  sentinel numbers; values outside declared categories raise; HTS mean coherence
+  and `aggregate` share one definition.
+- Inference: learner cloning works for sklearn pipelines and meta-estimators; the
+  KNN zero-feature fallback averages the whole training set; the AIPW ATT posterior
+  reweights the treated share consistently with the Bayesian bootstrap; the
+  R-learner names its final slot when a learner lacks `sample_weight`.
+- Docs: repaired the broken examples (`as_kind("admg")`, a single learner alias on
+  AIPW, the phantom `"gbm"` alias) and refreshed stale passages.
+
+### Changed
+- `effect()` lost its unused `level` parameter; pick the interval level on the
+  result (`estimate.interval(0.99)`).
+- IV estimands now state the linear (parametric) modeling assumption.
+- `m_separated` on a CPDAG-kind graph now answers for the equivalence class:
+  undirected edges read as circle marks and paths need definite status,
+  matching the PAG reading (a literal tail-tail walk could claim connection
+  where every member of the class is separated). Spell marks with `mixed(...)`
+  to walk them literally. `identify_effect` on a CPDAG or MAG used to run
+  silently with single-graph semantics; it now dispatches on the face, and
+  mixed graphs raise instead of being misread.

ergodic-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.