Docs: v1→v2 migration guide (incl. parameter scaling) and comparing objective values across tools

I propose two non-normative documentation pages. Both come from problems we ran into while converting the benchmark collection to v2 (Benchmarking-Initiative/Benchmark-Models-PEtab#333).

1. Migration guide, "Upgrading from PEtab v1"

"Changes from PEtab 1.0.0" lists what changed, but not what a change means for an existing problem, or how to convert a problem so that it stays the same estimation problem. Parameter scaling is the main gap. The spec only says that parameterScale was removed because its "interaction with parameter priors was not well-defined", and that "the model parameters can be transformed in the model file".

Proposed content for parameter scaling:

• What v1 specified: bounds and nominal values on linear scale; parameterScale* priors on the scaled parameter; parameterScaleUniform as the default, "equivalent to no prior". v1 left open whether other priors on a log-scaled parameter are densities over x or over log10 x (#402).
• How v1 tools implemented it:
  • D2D and pyPESTO evaluate priors as densities over the scaled parameter, without a Jacobian (D2D arCollectRes.m, pyPESTO).
  • libpetab's v1 Prior evaluates them as densities over x, with the Jacobian (priors.py).
  • Gradients are commonly reported with respect to the scaled parameters (e.g., AMICI, pyPESTO), and start points are sampled on the parameter scale.
  • Other tools still to be surveyed.
• Consequences: for log-scaled parameters with priors, objective values and optima differ between tools. Gradients differ by a factor of x·ln(10) per parameter.
• In v2: no parameter scale; priors are densities over the parameter as used in the model; the objective is fully defined.
• How to reproduce a v1 problem exactly: a step-by-step reparametrization. This covers a new parameter log10_k with k = 10^log10_k (e.g., an initial assignment), transformed bounds, nominal values and priors, and substitution in observable/noise formulas and overrides for parameters that don't appear in the model.
  • Options for defining k = 10^log10_k in an SBML model: an initial assignment keeps k a constant entity (it can still be a condition target) and is sufficient, since log10_k is constant. An assignment rule also works, but makes k an algebraic entity, so it can no longer be a condition or event target; its only advantage is robustness in tools that don't re-evaluate initial assignments after changing parameter values. Substituting 10^log10_k into all model expressions and removing k loses its annotations and changes every kinetic law; setting k in the condition table for each experiment spreads the model definition over the experiments.
  • Measurement table overrides cannot be expressions, so 10^log10_k cannot be substituted there. Instead, the placeholder is transformed (ph → 10^ph in the observable/noise formula), and all overrides of that placeholder are log-transformed (k → log10_k, a number c → log10(c)).
  • This fails if the same placeholder also receives non-positive numbers or parameters that stay on linear scale. Then, the observable should be split, so that each copy's placeholder only receives overrides that can be log-transformed, or none at all. This reproduces the v1 problem exactly. Keeping the parameter on linear scale instead is not recommended: it changes the parametrization, and, with a uniform prior, shifts the log-prior by a constant (uniform on linear scale instead of on log scale).
• What petab1to2 does and what it preserves. Explicit parameterScaleNormal priors become log-normal (keeps the distribution, moves the optimum). Unspecified priors become uniform(lb, ub) (keeps the optimum, changes the distribution). PEtab-dev/libpetab-python#535, PEtab-dev/libpetab-python#536.

Other changes with numerical consequences that should be covered:

• the removal of log10-normal noise (rescale the noise parameters);
• the removal of initialization priors;
• bounds now truncating priors;
• the default uniform(lb, ub) prior, which adds a constant to the objective as soon as any parameter has a prior.

2. "Comparing objective values across tools"

For PEtab v1 and v2 alike: why the same problem gives different objective values in different tools, and how to convert between them. These mismatches are common in practice. AMICI's benchmark-model tests document, per problem, how the reference values of the original benchmark collection relate to the PEtab log-likelihood: a factor of 1/2 or −1/2, a sign, a log10 correction term, χ² instead of the log-likelihood, priors included, and one unexplained mismatch (Schwen_PONE2014). Draft outline:

Each entry would give the conversion formula. A worked example (e.g., Boehm_JProteomeRes2014) would show the PEtab-defined value next to the values reported by major tools and the original reference value. I'd verify the tool-specific statements with the tool developers before publishing.

Relates to #402.

🤖 Drafted with AI assistance