0.4.0: transformation syntax, no backward compat, radical simplification

[MArpogaus]

Everything on dev-marcel since the 0.3 baseline, plus the framework/research split
from #42 (that branch is not merged into dev-marcel yet — the numbers below are
measured on it).

Nothing here is speculative: every number quoted was measured in this repository, and
where a claim did not survive measurement it is marked as corrected.

The one line that explains the diff

src/tramdag/ is framework code and nothing else. Research code — the SCM
generators, frozen datasets, paper replications and benchmarks — lives in
experiments/, in three areas. The wheel drops from 13 modules to 7 and loses its
simulations subpackage.

Anything deleted is recoverable at the annotated tag pre-experiments-cut:
git checkout pre-experiments-cut -- <path>.

Breaking changes

change	migration
fit(epochs=) is required	pass a budget, or a generous one with schedule="plateau" + freeze_patience=; raises with the reason
fit(plateau_patience=) default 15 → 30	the value docs/training-speed.md measured; no caller used the default
tramdag.simulations removed from the wheel	generators are in experiments/paper/simulations/
env.py merged into utils.py	tramdag.machine_info unchanged; tramdag.utils.config_section is new
transform_kwargs= gone	I("x1", transform="spline", bins=6) — raises with the replacement named
two parented intercept terms rejected	CI("a","b", allow_interaction=False)
Intercept/LinShift/CShift/term()/Term.slot gone	SI/CI/LS/CS/VC, or the pythonic long names
fit(schedule=) keeps None/"plateau"	onecycle/cosine lost to plateau on every workload
single-value knobs no caller set are now constants	StandardLogistic.sample/icdf(eps=), marginal_init_theta(q=), ordinal_marginal_init_theta(eps=), sup_bb_pvalue(terms=)
pre-0.4 checkpoints do not load	refit; the loader now says so instead of raising KeyError

terms= is not removed — it is the first parameter's name, so
ContinuousNode(terms=[...]) and ContinuousNode([...]) are the same call. An
earlier CHANGELOG entry claimed otherwise and has been corrected.

Bugs fixed

ls_coefficients() crashed on any node mixing LS and CS — it read .weight
off every shift module, and a CS shift is a network. Verified present on main
too. On main the experiments never hit it because their ls_weight helper read the
module directly; on dev-marcel the helper was rewritten to use the method, which is
what broke triangle atan-cs there. Fixed at the root, with regression tests.

A load-bearing hyperparameter was dropped by the restructure. main fits the
VACA and CAREFL benchmarks in chunks of 50 epochs; each fit call starts a fresh
Adam, so the chunk size acts as a warm-restart schedule. The restructure ran those
two as one long call, and the ground truth then enshrined the degraded result.
chunk_epochs is an explicit key now.

Two replications used the wrong reference architecture. The reference
implementation has two, and the configs cited one while replicating the other: the
triangle scripts use hidden_features_I = hidden_features_CS = c(2,25,25,2) with
sigmoid, while its own CAREFL and VACA comparisons use comparison/utils.R::make_model
— one net per node, dense(10, tanh) -> dense(100, tanh) -> dense(len_theta), with
M = 30. Error against the analytic interventional mean, do(x2=a):

protocol	do(x2=−3)	do(x2=−1)	do(x2=0)
one call of 400 epochs (what this branch first shipped)	0.355	0.141	0.090
eight chunks of 50 (chunk_epochs restored)	0.120	0.064	0.060
main	0.015	0.014	0.012
+ the reference's own comparison net	0.037	0.012	0.010

The residual gap in row 2 was not a code difference: running main's protocol
verbatim on this branch's framework reproduces main's numbers exactly (−1.0146 /
−0.4864 / −0.2379). What differed was the minibatch stream, because the restructure
seeds it explicitly — and that workload spans 0.19 across shuffle seeds 0–3, so the
old tolerance of 0.10 around a single draw was wrong regardless. With the correct
architecture the question is moot: two of the three queries now beat main.

CAREFL improves on every previously committed number: counterfactual MAE for x4
0.078 / 0.059 / 0.086 against bounds of 0.216 / 0.174 / 0.219, val NLL 1.345 against
1.351, Fig. 6 max error 0.377 against a bound of 1.003.

Numbers, this branch against main

Same protocol, same data seed, same init seed; the only deliberate difference is
explicit minibatch seeding.

experiment	metric	main	branch	|diff|
triangle linear-ls	β12 / β13 / β23	1.9807 / −0.1464 / 0.2854	1.9825 / −0.1450 / 0.2847	≤ 0.0018
triangle atan-cs	β12 / β13	1.9850 / −0.1464	1.9825 / −0.1486	≤ 0.0025
triangle-mixed linear-ls	β12 / β13 / β23	1.9807 / −0.2666 / 0.3208	1.9825 / −0.2684 / 0.3218	≤ 0.0018
triangle-mixed linear-ls	App. C.4 odds ratio	7.2477	7.2609	0.0132
validate_ls (classical)	Age / NIHSSa / T	0.0526 / 0.1630 / −0.9424	0.0539 / 0.1638 / −0.9398	≤ 0.0026

Paper truth for reference: β12 = 2, β13 = −0.2, β23 = 0.3, odds ratio e² ≈ 7.39. The
validate_ls row is the external anchor: flow vs statsmodels vs R polr, ATE
+0.1416 against +0.1428 with true ATE +0.132.

Hyperparameters against the paper

The paper (arXiv:2503.16206) states exactly four: 40000 samples, 500 epochs, Adam
at lr 0.001, Bernstein order 20. The triangle configs match all four. Batch size,
the 90/10 split, the chunk size, the VACA/CAREFL protocols and every seed are this
repository's choices, now labelled as such at the top of each config.

Three documentation claims did not survive the check:

• CLAUDE.md presented the mixed-data cutpoints as the paper's; the paper does not
  state them (they are the reference implementation's).
• n_coeffs was documented as the paper's order M. zuko constrains n unconstrained
  coefficients into n + 2 control points, so n_coeffs=20 is degree 21 where the
  reference's len_theta=20 is degree 19; the free-parameter count is what matches.
• conditioners.py, README, CLAUDE.md and docs/code-map.md all sourced the default
  architectures to "the original Keras implementation (tram_models.py in
  tensorchiefs/tram-dag)". That repository is pure R and has no Python in it; the
  defaults come from the PyTorch reference this package grew out of
  (buehlpa/TramDag).

Every default has a reason, or it is gone

An audit of all 34 defaults in src/ found exactly one indefensible: epochs=500.
This repo's own benchmark measures fixed budgets going wrong in both directions
(stroke over-spends by 2.5×, vaca under-spends by 0.03 nats), and 50 of 51 fit
calls already passed it, so it is required now. Everything else was documented with
what justifies it — including activation=, which was missing from the numpydoc of
all six public entry points that accept it.

Paper coverage

experiments/paper/PAPER_COVERAGE.md maps all 20 figures. Every figure that is a
result is reproduced. The check found one genuine gap — App. C.3.3 / Fig. 17, the
misspecified case — now the triangle linear-cs variant. Fig. 10's argument about
discretized counterfactuals is measured: an observed ordinal level pins the
latent to an interval, so the generator states the exact counterfactual law and the
flow is scored against it — P(true level) 0.924 for the flow, 0.921 for the analytic
law itself, against an attainable maximum of 0.954. That the flow sits above the
analytic law is the point of the new third number: this score is maximized by naming
the modal level, not by reporting the true distribution, so it was never a ceiling —
the review of this branch caught the claim that it was. Deliberate non-goals: Fig. 4's CNF panel and Fig. 12's NSF are
competing methods from other libraries.

One finding worth keeping: the reference's triangle net has a 2-unit input
bottleneck, and on sin — two turning points on the grid — it tracks −f(x₂) through
the middle and saturates at both ends. That is the architecture's capacity, not a fit
failure, and it is why the paper makes its Fig. 7 claim with atan.

New CI

.github/workflows/experiments.yaml runs every replication on each push, derives its
matrix from the YAML configs so the two cannot disagree, compares each run against
committed ground truth, and posts the report — metrics table plus figures — as a
commit comment through CML. Verified end to end: ten jobs, ten checks passed, ten
comments with figures on asset.cml.dev.

check.py takes two ground-truth forms: {value, atol} two-sided, and {max} for
error measures — previously a better fit failed the run. A {max} bound is now
kept in a band, 1.5–4× its measurement, and check.py says so when one is not:
below 1.5× it fails on another machine for no reason (this branch's own CI hit that,
at 1.7×), above 4× it cannot catch a regression. An entry meant to sit outside the
band carries a "why" string that is printed in its place.

Centers are re-pinned whenever the code moves them. That had been done for two files
and not the other six, so triangle-atan-cs — the headline Fig. 7 variant — was
passing while describing a net that no longer runs, having consumed 62% of its
tolerance.

Verification

• 161 fast tests pass, 166 including the slow fits, in an environment synced with the
  test group alone.
• CI now actually runs the per-area experiment tests; it passed tests/ explicitly
  before, so testpaths never applied and a bare pytest failed at collection.
• All 7 frozen datasets regenerate within 1e-9 (measured 2.2e-16).
• All 8 paper variants and validate_ls run and pass check.py.
• All four notebooks execute headless.
• Zero broken relative links across the tracked markdown files.

🤖 Generated with Claude Code

---

Addendum: the quality pass on #42 (2026-08-24)

Since the body above was written, feat/experiments-restructure gained a full
quality pass (commits 39d4be5..94a2f40) that rolls up into this PR once #42
merges. The long-form description lives in #42; the merge-relevant facts:

• Lint and complexity now gate everything. ruff runs its default set plus
  I,E,D,UP,B,C4,C90,NPY,PERF,PT,RUF,SIM and nine measured-clean guards;
  complexipy enforces cognitive complexity at 15 for src/ and 10 for
  experiments//notebooks//tests/. There are zero suppression markers in
  the repo — the 13 grandfathered hotspots were refactored for real
  (fit 103 → 10, bench_training.main 83 → 6, validate_and_sort 65 → 1,
  _Node.__init__ 38 → 12, check.compare 36 → 5, eight more all ≤ gate).
• Behavior-identity is measured, not asserted: a fixed-seed harness (two-phase
  plateau/freeze/restore_best/marginal_init fit; centered VC with the OOF stage;
  joint + additive CI) compares state dicts, history and samples bit-equal
  before and after; error messages and the topological tie-breaking moved
  verbatim. Two verification agents re-derived every extracted helper.
• A four-perspective review against main (semantics, frozen contracts,
  docs, hygiene) found no critical issue. Notables: the ordinal log-likelihood
  rewrite was proven bit-identical to main in values and gradients; all
  surviving measurement CSVs are byte-identical to main; the found nits
  (aliasing _tensorize, unhashable node specs, a KeyError where a helpful
  ValueError belonged, stale paths/notation) are fixed on the branch.
• Every module follows one section layout (# %% imports / global variables / private functions / public functions / private classes / public classes / alias / main, dashes to column 88).
• Coverage is gated: CI runs pytest --cov with fail_under = 95; the fast
  suite measures 97% of src/. The sdist ships src/ only; the CI matrix has
  its 120-minute timeout back.
• Verification at the tip (94a2f40): full suite 178 passed including the
  slow fits; pre-commit run --all-files fully green; all ten experiment
  variants' ground-truth checks unaffected (no measured number changed anywhere
  in the pass).

Still open for the release, unchanged from above: the version = 0.4.0 bump
(CHANGELOG section is written) and, until it ships, the Colab demo's
pip install tramdag cell intentionally installs the incompatible 0.3.0.