Repository navigation
Conversation
dweindl
force-pushed
the
doc-migration-guide
branch
2 times, most recently
from
October 21, 2026 14:19
d3634c4 to
6f027e9
Compare
dweindl
force-pushed
the
doc-migration-guide
branch
9 times, most recently
from
October 21, 2026 19:51
a8fccef to
c45e978
Compare
dweindl
marked this pull request as ready for review
October 21, 2026 20:08
dweindl
added a commit
to PEtab-dev/libpetab-python
that referenced
this pull request
Oct 26, 2026
PEtab v2 has no `parameterScale`. Converting a v1 `parameterScaleNormal(μ, σ)` prior on a `log10`-scaled parameter to `log-normal(μ ln10, σ ln10)` keeps the prior distribution, but adds a Jacobian term to the v2 MAP objective, which moves the optimum by `−σ² ln10` decades. No v2 prior over the unscaled parameter can preserve both the distribution and the optimum. `petab1to2` and `petab_files_1to2` get a `reparametrize` argument, which uses `petab.v2.reparametrize_log` (#560) to estimate `log10_<id>` (or `log_<id>`) instead of `<id>`: * `"none"` (default): current behaviour, now with a warning for converted `parameterScale*` priors * `"priors"`: log-scaled parameters with `parameterScale*` priors * `"all"`: all estimated log-scaled parameters without priors on linear scale (i.e., without `logNormal`, `uniform`, ...); this also preserves the v1 default prior (uniform on parameter scale) Log-scaled parameters sharing a placeholder with selected parameters are added. Such placeholders are substituted by `10^placeholder`, so numeric overrides are log-transformed. Since overrides must be finite, `0` overrides are replaced by a new fixed parameter `negative_infinity` with nominal value `-inf` (assuming PEtab-dev/PEtab#687 is accepted). With `"all"`, parameters without parameter-scale priors are skipped (with a warning) if their placeholder can't be log-transformed, i.e., if it is also overridden by negative numbers or by parameters that are not reparametrized. Parameters with `lowerBound = 0` (allowed in v1 for log-scaled parameters with an initialization prior) get `lowerBound = -inf` on log scale (PEtab-dev/PEtab#682). They are skipped with a warning if their prior on log scale would be an improper uniform prior, i.e., the v1 default prior if other estimated parameters have priors. Also fixes `petab1to2` adding default `uniform` priors to non-estimated parameters, and to all parameters if the v1 parameter table has an `objectivePriorType` column, but no estimated parameter has a prior. Priors of non-estimated parameters are converted as before. Non-estimated parameters are only reparametrized if they share a placeholder with selected parameters. A nominal value of `0` then becomes `-inf`, assuming PEtab-dev/PEtab#685 / PEtab-dev/PEtab#687 is accepted. Their `parameterScale*` priors are converted to log scale as well, unless they depend on missing bounds (then they are dropped with a warning). Checked on the benchmark collection: all 35 problems convert and pass v2 linting with `"all"` (now also tested in CI); with `"priors"`, 44 parameters are reparametrized in Bachmann, Isensee, Raimundez and Schwen. Checked with AMICI (v1 importer vs. v2 `PetabImporter`, forward sensitivities) on 30 benchmark problems converted with `"all"` (5 large ones excluded), at the nominal parameters and at a shifted point: log-likelihoods agree to a relative difference of ≤ 2e-8, and gradients agree to ≤ 2e-5 of the largest gradient entry, except for Crauste at the nominal parameters (4e-4 at rtol/atol 1e-12/1e-16, decreasing with tighter tolerances; 5e-14 at the shifted point). The remaining deviations are due to integration tolerances. Log-priors are identical for Bachmann, Isensee and Raimundez. (Before the `0` overrides were supported, 6 log-scaled Bachmann parameters couldn't be reparametrized, and their v1 default prior became a linear `uniform`, which preserves the MAP, but changes the log-prior by a constant.) The default is `"none"` for now, to keep `petab1to2` uninvasive, i.e., to not change the parametrization unless requested. Open to change. References Benchmarking-Initiative/Benchmark-Models-PEtab#333, PEtab-dev/PEtab#680, PEtab-dev/PEtab#683 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Add a non-normative page "Upgrading from PEtab v1" to the v2 documentation. It lists the structural changes, explains the consequences of the removal of `parameterScale` for the objective function, describes how to reparametrize log-scaled parameters (`log10_k` with `k = 10^log10_k`), the `reparametrize` option of `petab1to2` in libpetab-python 0.10.0, the other changes affecting objective values (log10 observables, truncated priors, default prior), and how to verify a conversion. Infinite bounds and priors of non-estimated parameters follow errata E1 and E2. References #680. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The sphinx_rtd_theme sets `white-space: nowrap` on all table cells, which makes tables with longer text, such as the structural changes table in the migration guide, require horizontal scrolling. Override this in `custom.css` so that cell contents wrap. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
dweindl
force-pushed
the
doc-migration-guide
branch
from
October 26, 2026 14:37
c45e978 to
434d989
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a non-normative page "Upgrading from PEtab v1" to the v2 documentation (
doc/v2/migration_guide.rst, linked from the v2 toctree after the tutorial).Contents: a quick path for the typical case; the structural changes (handled by
petab1to2) and what has to be done by hand; the consequences of removingparameterScalefor the objective function, i.e., how PEtab v1 tools evaluated priors on log-scaled parameters (D2D, pyPESTO, libpetab-python at pinned commits), what PEtab v2 specifies, and why a faithful conversion reparametrizes log-scaled parameters aslog10_kwithk = 10^log10_kin the model; the step-by-step reparametrization recipe including measurement-table placeholders; thereparametrizeoption ofpetab1to2; the other changes affecting objective values (log10observables, truncated priors, default prior); and a verification procedure, withSchwen_PONE2014from the benchmark collection as example.Also allows line breaks in table cells (
doc/_static/custom.css), since the RTD theme'snowrapmade wider tables scroll horizontally.The spec page is not modified. Infinite bounds and priors of non-estimated parameters follow errata E1 (#684) and E2 (#686). The
petab1to2section describespetab.v2.reparametrize_logandpetab1to2(reparametrize=...)as released in libpetab-python 0.10.0 (PEtab-dev/libpetab-python#560, PEtab-dev/libpetab-python#539). A second page on comparing objective values across tools will follow in a separate PR.References #680.
🤖 Generated with Claude Code
👀 https://petab--683.org.readthedocs.build/en/683/v2/migration_guide.html