Edition-2 experiment: can't express a pre-equilibration → intervention → dose-scan protocol (parameter_scan+preequil refused; no species setConcentration) — a published fit (Erickson 2019 IGF1R) is legacy-only

[wshlavacek]

Summary

The edition-2 experiment: surface can synthesize a pre-equilibration protocol (ADR-0052:
equilibrate unmeasured → perturb → measure a time course), but it cannot express the next step
up — equilibrate → intervene → measure a parameter_scan — which a real, published fit requires.
Two specific restrictions block it:

1. parameter_scan + pre-equilibration is refused. A pre-equilibration experiment whose
   measured phase is a dose-response scan raises immediately.
2. Only absolute setParameter perturbations are supported (no species-level
   setConcentration), so an intervention like a ligand wash (zero the free-ligand pool
   mid-protocol while retaining bound ligand) cannot be expressed.

The consequence: the IGF1-IGF1R binding fit from Erickson et al. 2019 (PLoS Comput Biol
15(1):e1006706) — whose SI ships the exact BioNetFit model+conf that produced the paper's Table 1 —
can only be ported to edition-2 as a reduced, single-phase F5B-only distillation. The paper's
actual fit (7 rate constants fit jointly to three datasets, two of which use a
preincubate→wash→scan protocol) must stay in legacy (edition-1) mode with an in-model actions
block. That defeats the edition-2/PEtab-round-trip goal for this model.

The ask

Please add the edition-2 capability needed to express this protocol, so the full Erickson-2019
IGF1R fit runs in edition = 2 (not legacy). Concretely, the goal is a conf like

edition = 2
bngl_backend = bngsim
model = igf1r.bngl
objective = chi_sq
normalization = init
# ...the 7 loguniform_var free params...
# three experiments, two of them a preincubate -> wash -> dose-scan protocol:
experiment: F5B,       type: parameter_scan, t_end: 14400, data: F5B.exp
experiment: F5D_20min, preequilibrate: incubate, condition: wash, type: parameter_scan, t_end: 1200,  data: F5D_20min.exp
experiment: F5D_60min, preequilibrate: incubate, condition: wash, type: parameter_scan, t_end: 3600,  data: F5D_60min.exp

that fits all three datasets jointly with no in-model actions block — i.e. retire the
legacy-mode requirement for this (and any other preincubate→intervene→dose-response) job, and keep
it PEtab-round-trippable. The two edition-2 gaps below (parameter_scan-with-pre-equilibration and
species setConcentration interventions) are what stand between the current surface and that conf.

The protocol edition-2 can't express

The paper's two "F5D" datasets (Kiselyov 2009 Fig 5D, 20- and 60-min dissociation) are, in the
authors' own BNGL actions block:

saveConcentrations("t=0")
setConcentration("IGF1(ds,hs,label~hot)",30350)   # 24 pM hot ligand
simulate({method=>"ode",t_start=>0,t_end=>7200,n_steps=>10,suffix=>"incubate"})  # 2 h preincubation
setConcentration("IGF1(ds,hs,label~hot)",0.0)     # WASH: zero *free* hot (bound hot remains)
setConcentration("IGF1(ds,hs,label~cold)","IGF1_cold_conc*(NA*Vecf)")
saveConcentrations("start_competition")
parameter_scan({suffix=>"F5D_20min",parameter=>"IGF1_cold_conc",par_scan_vals=>[...],
    method=>"ode",t_start=>0,t_end=>1200,n_steps=>120,reset_conc=>1})   # measured dose-response

i.e. (phase 1) a fixed-duration equilibration, (intervention) a species wash + set the
scan variable, (phase 2) a parameter_scan measured at a late time, with each scan point reset
to the post-wash saved state. Edition-2 can express phase 1 (preequilibrate: with equil_t_end:)
but neither the species wash nor the scan-as-measured-phase.

Where it happens (v1.6.0)

• parameter_scan refused — pybnf/config.py:1487 (_build_preequilibration_action):

  if action_type != 'time_course':
      raise PybnfError(... "a parameter_scan with pre-equilibration is not supported (ADR-0052).")

• setParameter-only — pybnf/config.py:1455 (_preequilibration_perturbations) rejects any
  non-= op and emits each perturbation as setParameter (pybnf/pset.py _append_preequilibration_actions, ~:1092). There is no path to emit a species setConcentration.

Why this maps cleanly to the existing design (and to PEtab v2)

This is not a new paradigm — ADR-0052 already frames pre-equilibration as "Phase 1 of a
three-phase arc" and maps it bidirectionally to PEtab v2 multi-period experiments
(Experiment.periods = [(-inf, preequil), (0, measurement)]). The two gaps above are the natural
continuation of that mapping:

• A dose-response with pre-equilibration is a standard PEtab v2 shape (a shared
  pre-equilibration condition across the scanned experiments) — the parameter_scan is PyBNF's
  compact form of it.
• A species wash is a PEtab v2 condition that targets a species amount (not just a
  parameter). Emitting setConcentration("<pattern>",<value>) alongside setParameter covers it.

So extending edition-2 here keeps the PEtab round-trip goal reachable for multi-phase protocols,
rather than stranding them in legacy mode.

Proposed directions (sketch — not prescriptive)

• (A) Allow parameter_scan as the measured phase of a pre-equilibration experiment. Lift the
  time_course-only restriction and emit the two-phase block with a parameter_scan measured
  phase. Implementation note: each scan point must reset to the carried-over post-intervention
  state (the saveConcentrations("start_competition") + reset_conc=>1 idiom), not to the seed —
  so the synthesizer would saveConcentrations after the intervention and drive the scan with
  reset_conc=>1. (Needs the edition-2 backend, bngsim, to honor save/reset-to-a-named-state.)
• (B) Support species-concentration perturbations in preequilibrate:/condition:, emitting
  setConcentration("<species pattern>", <value>) for a species target (vs. setParameter for a
  parameter). This expresses a wash / bolus / removal between phases.
• (C) Longer arc: generalize experiment: to an N-phase protocol (mirroring PEtab v2
  periods), of which (A)+(B) are the two-/three-phase special cases.

(A)+(B) together are the minimum to express the incubate→wash→dose-scan pattern above.

Minimal repro

Model: the Erickson 2019 SI IGF1R_fit.bngl (or any model with a preincubate→wash→scan protocol).
An edition-2 conf that tries to express the F5D phase as a pre-equilibrated scan:

edition = 2
bngl_backend = bngsim
model = igf1r.bngl
condition: incubate,  perturbations: IGF1_hot_conc = 24e-12
condition: wash,      perturbations: <no way to say setConcentration(IGF1(...label~hot), 0)>
experiment: F5D_20min, preequilibrate: incubate, condition: wash,
            type: parameter_scan, t_end: 1200, data: F5D_20min.exp

fails at config.py:1487 ("a parameter_scan with pre-equilibration is not supported"), and even a
time_course variant has no way to express the species wash (config.py:1455, setParameter-only).

Workaround today

Run the job in legacy (edition-1) mode: keep the full actions block in the model and list the
datasets on the model= line (model = igf1r.bngl : F5B.exp, F5D_20min.exp, F5D_60min.exp). This
works and reproduces the paper, but it is NATIVE-ONLY (no PEtab export) and cannot use the edition-2
experiment:/condition: surface — which is exactly the limitation this issue asks to remove so
the job can run in edition = 2.

[wshlavacek]

Fixed in ea5923c (feat(config): edition-2 preincubate→wash→dose-scan protocol …).

The edition-2 surface now expresses the full equilibrate → intervene → dose-response protocol, so the Erickson-2019 IGF1R fit (7 rate constants, 3 datasets, two of them the F5D preincubate→wash→cold-competition scan) runs in edition = 2 with no in-model actions block — retiring the legacy-mode requirement this issue asked about.

What was added (both gaps the issue named, plus the backend work they turned out to need):

• (A) parameter_scan as a pre-equilibration measured phase. The time_course-only restriction is lifted; the synthesizer emits a two-/three-phase block (reset → perturbations → equilibration → intervention → saveConcentrations → parameter_scan reset_conc=>1), each dose reset to the carried post-intervention state.
• (B) Species setConcentration interventions. A condition:'s perturbations: accepts a quoted BNGL species pattern LHS with a number or a param-expression RHS — a wash ("IGF1(ds,hs,label~hot)" = 0) or a dose-tracking bolus ("IGF1(ds,hs,label~cold)" = IGF1_cold_conc*(NA*Vecf)). A ( in the target routes it to setConcentration (vs. setParameter).
• Backend. The critical de-risk finding was that this is not a pure front-end change: PyBNF's bngsim bridge re-derived each scan point from the .net seed, discarding the pre-equilibrated state (BNG2.pl gave a proper dissociation curve, bngsim gave garbage — 891→281 vs 154→1). The scan-reset fidelity fix was routed upstream to Named saved concentration states + reset_conc-to-snapshot scan (parameter_scan/bifurcate after pre-equilibration) bngsim#11 (→ bngsim 0.11.34: native parameter_scan/bifurcate with reset_conc-to-snapshot + on_point, and named saved states). PyBNF now routes a carried-state scan to that native primitive; the fresh-from-seed dose-response paths (ADR-0046) are untouched.

Validated: the full 3-dataset fit reproduces the paper through the bngsim backend to the same tolerance as the BNG2.pl legacy path — F5B 1.0 %, F5D_20min 5.3 %, F5D_60min 7.0 % median rel err at the Table-1 parameters — and runs end-to-end via the pybnf CLI. Covered by a carried-state-scan recovery oracle (m10_preequil_scan) + emission/grammar unit tests; design in ADR-0062.

Deferred (follow-up): PEtab export of these two shapes (a species-amount condition target + a pre-equilibrated dose-response) is not yet emitted — the exporter refuses it with a clear message, a follow-up to ADR-0052's phased export. The fitter fully supports the job; normalization = init already makes it native-only regardless.