PEtab-aligned config redesign: explicit experiments/conditions/data (retire filename→suffix linkage)

[wshlavacek]

Design captured in ADR-0028 (docs/adr/0028-petab-aligned-config-explicit-experiments.md, Status: Proposed, commit c1279e3). This is the config-language sibling of the PEtab exporter work (#407 umbrella, #422 exporter chunk, #420 BnglModel oracle).

Problem

PyBNF links a dataset to the simulation it scores against implicitly, through filenames: every .exp stem must equal a BNGL action's Suffix or PyBNF errors (config.py:764, "Action not specified for X.exp"). Consequences:

• Replicates are impossible without surgery — N replicate files for one simulation would all need the same <suffix>.exp name and collide; users must pre-average/splice.
• A data file's name is load-bearing, not descriptive.
• The suffix convention is opaque, even to experienced users.
• It doesn't match PEtab, so the exporter (PEtab v2 exporter: conditions/experiments chunk (mutants→conditions, suffix→experiments, dose-response) #422) reverse-engineers the suffix out of filenames to synthesize experimentId.

Proposed design (1:1 with PEtab v2)

Four explicit label: concepts in the .conf, each mapping to a PEtab v2 object, with links stated rather than filename-derived:

conf keyword	meaning	PEtab v2
model:	one or more model files (multi-model OK)	Model(s)
condition: (+ perturbations:)	a named set of parameter overrides (= today's Mutant)	Condition
experiment:	a named simulation; applies a condition: (default wildtype); carries its data:	Experiment
the experiment's data: files	measured points; multiple files = replicates	Measurements

Example:

model: egfr.bngl
condition: dimer_dead, perturbations: kdimer = 0
experiment: egf_high,    data: high_wt_r1.exp, high_wt_r2.exp
experiment: egf_high_dd, condition: dimer_dead, data: high_dd.exp

Key decisions

• Simulation times/doses are derived from the data (PEtab-style). A consequence: the BNGL begin actions block is no longer needed for fitting — PyBNF synthesizes the simulate/parameter_scan/bifurcate from the experiment options + the data's independent-variable values; the experiment name replaces the Suffix as the simulation's identity.
• Observables still inferred from .exp column headers, with an optional observable: x, column: y override.
• Omissions allowed wherever unambiguous (model: on a condition/experiment when there's one model; condition: on a wildtype experiment; type: when inferable from the indep-var header).
• Backward compatible: the legacy syntax (model = … : …, mutant = …, filename→suffix) is syntactically distinct and keeps its current meaning; a job uses one style or the other.

Implementation outline

1. Parser grammar for the new label: lines (pyparsing), alongside the legacy grammar.
2. Config loading: build conditions/experiments/data from the new keys.
3. Action synthesis: generate the BNG action from experiment options + data-derived times/doses.
4. Teach the exporter (PEtab v2 exporter: conditions/experiments chunk (mutants→conditions, suffix→experiments, dose-response) #422) the new syntax (turns export into transcription).

Loose ends to settle (parked in the ADR)

• _SD / per-observable noise (noise_model, Per-observable noise models: lift the single global objfunc to per-observable selection (PEtab v2 prerequisite) #410/ADR-0021) routing — tackle first, it's the one that could complicate the clean picture.
• Smooth-curve output (data-derived times give a ragged grid) — an explicit opt-in.
• Observables as a first-class table vs header-inference + overrides.
• Multi-model condition: model: semantics (needs the multi-model exporter, deferred in PEtab v2 exporter: conditions/experiments chunk (mutants→conditions, suffix→experiments, dose-response) #422).

See ADR-0028 for full detail and the considered/rejected alternatives.

[wshlavacek]

Survey of examples/*.conf — oddball features the new conventions must reckon with

Reviewed all 441 example .conf files. Most are templated duplicates (Mallela 50 states + ~380 MSAs, COVID metros), so the real structural diversity is ~20 archetypes. Findings below are grounded in counts across the whole corpus, ordered roughly by how much they block the PEtab arc. TL;DR: the clean single-BNGL-model + chi_sq + uniform-prior + .exp job that ADR-0027/0028 target is a small minority of the corpus.

A. Data / objectives with no PEtab-core representation (the real blockers)

1. Qualitative constraints (.prop) dominate the variant use-case. 288 .prop files in use (247 as mutant data, 41 as model data) vs the .exp we handle. Every single mutant in the corpus pairs with .prop, never .exp (all 247 mutants live in yeast_cell_cycle). So the mutant→condition path we built for quantitative mutant data describes a case that does not occur in the wild — real mutants carry inequality/temporal constraints, which have no PEtab measurement-table form (would need a PEtab extension; see the earlier .prop discussion). A data: line pointing at .con/.prop is the gating question for the whole condition story.

2. neg_bin_dynamic is the dominant objective: 357 of 441. PEtab v2 removed neg_bin (ADR-0023). Full spread: neg_bin_dynamic 357, sos 22, chi_sq 19, ave_norm_sos 19, direct_pass 14, chi_sq_dynamic 10. Only plain chi_sq (19) maps to a PEtab noiseDistribution today. The _dynamic variants carry a cumulative→incident _Cum transform (Generalize the _Cum cumulative→incident transform: decouple it from neg_bin, make it explicit #418) and direct_pass is likelihood-free — neither has a PEtab analog. So >95% of jobs can't express their objective yet.

B. Structural patterns the four-concept model doesn't cover yet

3. Multi-model jobs are common and central, and "variant" is expressed two contradictory ways. MEK_Isoforms = 5 separate model files (MEK1_WT/KO/N78G/T292A/T292D.bngl), one per genetic variant; yeast = 1 model + 117 mutants. ADR-0028's condition: model: and the exporter both currently assume/handle a single model. The conventions need a multi-model story and guidance on variant-as-condition vs variant-as-model.

4. Mixed data types on one model. model = MEK1_WT.bngl: WT.prop, WT.exp — qualitative + quantitative bound to the same model. The data: list must tolerate heterogeneous types (and route each appropriately).

5. Dose-response exists, but its parameter_scan lives in the BNGL begin actions block, never in the conf. 6 genuine dose-response datasets (tlbr LTconc, egfr_nf LT_nM, egfr_ode LT, igf1r IGF1_cold_conc, constraint_raf I); param_scan as a config key has ZERO uses corpus-wide. ADR-0028 (and the ADR-0027 exporter) read the scan time from a conf param_scan and raise otherwise — so none of the real dose-response examples would export. Either parse the BNGL actions block for the scan, or require migration. (This also means the dose-response path I shipped is, like the mutant path, validated only against synthetic fixtures.)

C. Preprocessing / semantics with no PEtab home

6. normalization (9 uses): two forms — init and peak:(alpha.exp: 1-10), (cdc15.exp: 1-10) (per-file, per-column-range peak normalization, used by yeast/HIV). PEtab has no data-normalization preprocessing. Unresolved where this goes.
7. constraint_scale (weights constraint penalty vs data; tied to .prop).
8. smoothing (2/3 — stochastic replicate averaging): simulation-side replicates, distinct from the data-side replicates the new data: list introduces. The two "replicate" notions need disambiguating in the conventions.
9. ind_var_rounding (rounds the independent variable to match data↔sim grid): directly relevant to "derive times from data" — with exact-data-time sampling this float-matching wart may change or vanish; worth an explicit decision.
10. _Cum cumulative observables + output_trajectory / output_noise_trajectory: observable transforms (cumulative→incident, lnV log outputs) and output directives with no PEtab analog; relevant to the parked _SD/noise and smooth-curve loose ends.

D. Prior coverage

11. loguniform_var is the 2nd-most-common keyword in the entire corpus (1327 uses) — the dominant non-trivial prior — followed by lognormal_var (81), logvar (15), normal_var/var (1 each). The exporter handles only uniform_var today. Log-uniform/log-normal export is essentially required for any real job (the import mapping is ADR-0019/0020; the export side needs the reverse).

E. Model types beyond BNGL

12. SBML .xml (13) — export deferred (known). .target (14) — analytical target distributions for the sampler benchmarks (Banana/Gaussian/Multimodal): no model/observable/data structure at all, entirely outside PEtab's scope. Worth an explicit "not applicable" boundary so they don't look like a gap.

What this means for #423

The new conventions are sound for the quantitative, single-model, Gaussian slice — but that slice is a minority here. The highest-leverage unresolved items, in order: (1) .prop/constraint data (gates the whole real mutant/condition corpus), (2) the neg_bin/_dynamic/_Cum objective family (gates ~95% of jobs), (3) multi-model + variant-as-model-vs-condition, and (4) where parameter_scan is read from (conf vs BNGL actions). These should be explicit "Open/deferred" entries (with a representable-subset boundary) before the new config is built, so we're not surprised later. Items 6–10 (normalization, constraint_scale, the two replicate notions, ind_var_rounding, _Cum/output directives) are the second tier.

[wshlavacek]

Correction / sharpening of finding #1 above (.prop is data, not a condition)

My survey wording above was imprecise about the mutant case. After reading a full .prop and the BPSL (Biological Property Specification Language) grammar (docs/config.rst:140), the accurate split is:

A mutant line decomposes into two different slots:

mutant = yeast V1WT  mdt=150 f=0.48  :  constraints/rV1WT.prop
                     └─ perturbations ─┘   └──── .prop data ────┘

• mdt=150 f=0.48 — the perturbations (parameter overrides; the input). These do map to a PEtab Condition — the mutant→condition path is sound and matches reality.
• rV1WT.prop — the data the mutant is scored against (the output side; the analog of an .exp, just qualitative). This is the half with no PEtab representation.

Framed biologically: perturbation = genotype (the imposed change); .prop = phenotype (the observed qualitative behavior the simulation must reproduce). .prop belongs in the data: slot next to .exp, never in perturbations:.

What BPSL is (so the unrepresentability is concrete): each .prop line is (1) an inequality on observables/constants — and it may be between two observables (A >= B), not just value-vs-bound; (2) an enforcement condition — when it applies: always / once / at B=6 (at an output crossing) / between, with everytime/first/before; (3) a scoring mode — weight (static penalty w·(A−B)) or confidence (a likelihood, −log P of satisfaction).

Why PEtab can't take it: a PEtab measurement is a number at (observable, experiment, time) with a likelihood. BPSL differs on three axes PEtab has no column for — it's an inequality, often inter-observable, enforced by temporal logic / event crossings. The only sliver that could ever map is a single-observable threshold (A < 5 at t) in confidence mode ≈ censored data in the PEtab censored/ordinal extension; everything else (A>=B, at B=6, before/everytime, between, split, altpenalty) has no PEtab home. BPSL is a genuine PyBNF superset.

Net effect on the design: so finding #1's blocker is not the condition mapping — it's that data: must be heterogeneous (.exp exportable, .prop PyBNF-native and explicitly not exportable). The new config must carry .prop cleanly in the data: slot and have the exporter mark it "no PEtab representation" — a clean boundary, not a failure. The conventions must not force everything through a PEtab lens; BPSL is precisely the thing that stays PyBNF-only.

[wshlavacek]

Boundary note: .target analytical models are out of PEtab scope by category (a non-gap)

Item E/12 in the survey flagged .target (14 uses) as "outside PEtab's scope." Pinning it down so it's recorded as an explicit non-applicable boundary, not a missing feature:

A .target file is a JSON-defined analytical target distribution read by pybnf/analytical_model.py (types: gaussian, rotated_gaussian, rotated_quartic, banana, multimodal). It is used only in sampler_benchmarking/ (Banana, Gaussian_d10, Multimodal) to benchmark the samplers (am/dream/p_dream) against a known posterior — not to fit a biological system. The whole idiom is three pieces that travel together:

model = banana.target : target.exp      # an analytical distribution, not a dynamical model
objfunc = direct_pass                    # the model returns its log-density directly as the objective
# target.exp is a placeholder:  "# index  score \n 0  0"   (no real measurements)

So a .target job has no dynamical model, no observables, no simulation, and no measurements — it is pure posterior-exploration. PEtab is, by definition, parameter estimation of a (simulated) model against measurement data, so an analytical target distribution has nothing to map onto: no model_files entity, no observableFormula, no measurements. This also explains the direct_pass objfunc (14 uses) surfaced earlier — it's the analytical-benchmark companion, not a fitting objective in any PEtab sense.

Recommendation: the exporter should treat a .target model (and/or objfunc = direct_pass) as an explicit, documented "not applicable — sampler benchmark, no PEtab analog" boundary that it declines up front — distinct from the deferred-but-representable boundaries (SBML, multi-model) and the unrepresentable-data boundaries (BPSL/.prop). Recording it as a deliberate non-gap keeps it from later reading like missing coverage.