.. _tutorial: Tutorial ======== PyBNF ships a hands-on, self-contained tutorial that tours its modern (**edition-2**) features on small ODE models. It lives under ``examples/tutorial/`` in the source tree, and every lesson links below to its folder on GitHub. Each lesson is a self-contained folder: a commented model (``*.bngl``), its data (``*.exp``), one or more heavily-commented fits (``*.conf``), and a short walkthrough (``README.md``). Run any lesson from its own folder, for example:: cd examples/tutorial/01_logistic_growth pybnf -c logistic_growth_trf.conf Results land in an ``output/`` directory inside the lesson folder. You need `BioNetGen `__ (with ``BNGPATH`` set) and PyBNF's bngsim backend. How the lessons work -------------------- Every model is a deterministic ODE with a **known closed-form solution**, and its data is generated *from that same model at known-true parameters*. A correct fit therefore recovers the truth — which makes each lesson both a teaching example and an **automated regression test**: the suite in ``tests/test_tutorial_examples.py`` re-runs the lessons and checks that the recovered parameters land within tolerance of the truth (truths and tolerances live in ``examples/tutorial/_manifest.py``). Some lessons drive samplers or real-simulator parameter recovery and run slower; the test suite marks those as opt-in *slow* and *recovery* tiers. The lessons ----------- Getting started ^^^^^^^^^^^^^^^ - `1. Logistic growth `__ — your first fit; then two gradient optimizers, fitting qualitative data, and model checking (``trf``, ``lbfgs``, BPSL, ``check``). - `3. Gompertz growth `__ — a global search followed by a local polish (``pso`` + ``refine``). Optimizers and identifiability ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - `2. Bateman chain `__ — fit several observables at once, and ask whether each rate is identifiable (``de``, profile likelihood). - `6. Step input `__ — when a gradient fit is refused, and how a smooth (sigmoid) step fixes it. - `7. Algorithm bakeoff `__ — six optimizers on one oscillatory fit (``de``/``ade``/``pso``/``cmaes``/``sa``/``ss``). - `25. Island DE `__ — a multi-island differential evolution with migration (``islands``, ``migrate_every``, ``num_to_migrate``). - `44. Initialization `__ — where the search starts: seeding the initial population from an informative prior (``initialization``). Objectives and noise models ^^^^^^^^^^^^^^^^^^^^^^^^^^^ - `8. Robust objectives `__ — when outliers wreck a fit, and the noise models that shrug them off (``noise_model``: Gaussian vs Laplace vs Student-t). - `10. Per-observable noise `__ — give each reporter its own noise model (per-observable ``noise_model``). - `18. Count likelihood `__ — fit integer molecule counts with the likelihood built for them (``neg_bin``). - `19. Shape objectives `__ — fit the shape of a signal when its amplitude is arbitrary (column-joint ``kl`` / ``wasserstein``). - `28. Cumulative counts `__ — fit incident counts from a cumulative prediction (per-observable ``cumulative``, ``neg_bin``). - `35. Scale-free objectives `__ — when data spans orders of magnitude: relative vs absolute error (``norm_sos`` / ``ave_norm_sos`` / ``sod``). - `36. Estimate noise `__ — fit noisy data with no error bars: let the fit estimate the noise (``noise_model = normal, sigma = fit``). - `41. Estimate dispersion `__ — estimate count over-dispersion jointly with the dynamics (``noise_model = neg_bin, dispersion = fit``). - `42. Lognormal error `__ — multiplicative (lognormal) measurement error over orders of magnitude (``noise_model = lognormal, location = mean``). - `43. Custom objective `__ — bring your own objective: a custom Python callable (``objective = callable``). Data, experiments and protocols ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - `5. Noisy decay `__ — uncertainty from resampling, and noise-weighted fitting (``bootstrap``, ``chi_sq``). - `9. Experiment design `__ — richer designs: dose-response at steady state and a two-phase washout (``condition`` / ``preequilibrate``, parameter scans). - `16. Joint fit `__ — fit two experiments at once with one shared rate set (multi-experiment, shared parameters). - `21. Numerical hazards `__ — keep a fit alive when some simulations blow up or hang (``wall_time_sim``, ``max_failed_simulations``). - `22. Normalization `__ — fit data reported relative to a reference (``normalization`` init / peak / zero / unit). - `23. Resume `__ — stop and resume a fit, or extend it with more iterations (``--resume``, backups). - `24. Moment equations `__ — fit a model whose states are the mean and variance (moment-equation observables). - `30. Data fusion `__ — one fit to time-course, steady-state, and qualitative data at once (multi-experiment + ``.prop``). Bayesian inference and uncertainty ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - `17. Bayesian uncertainty `__ — a posterior, not just a best fit: credible intervals from MCMC (``dream``). - `26. MCMC samplers `__ — two more posterior samplers: Metropolis-Hastings and parallel tempering (``mh``, ``pt``). - `27. Priors `__ — an informative prior vs a flat one on a weakly-identified rate (``gamma_var`` in a sampler). - `32. Prior gallery `__ — the whole catalog of prior families: how each is spelled and shaped (``normal_var`` / ``gamma_var`` / ``beta_var`` / … + ``student_t``). - `37. HMC benchmark geometry `__ — Hamiltonian Monte Carlo / NUTS on the built-in benchmark geometries (``job_type = hmc``). - `38. HMC analytical ODE `__ — an ODE's closed-form solution as an HMC likelihood, no simulator (``objective = expression`` + ``hmc``). - `39. Adaptive MCMC `__ — Adaptive Metropolis on a correlated posterior, with R-hat / ESS via ArviZ (``job_type = am``). - `40. Preconditioned DREAM `__ — covariance-whitened proposals for a strongly correlated posterior (``job_type = p_dream``). - `45. Model selection `__ — which growth law? fit competing models and rank by AIC (multi-model). PEtab interoperability ^^^^^^^^^^^^^^^^^^^^^^ - `12. PEtab round-trip `__ — export, import, and validate a PEtab v2 problem (PEtab v2 + the BNGL linter). - `13. PEtab lint clinic `__ — a gallery of broken problems: watch the linter catch each mistake (``petab.v2.lint``). - `14. Observable layer `__ — fit what the instrument reports, not the raw species: a scale, a ratio, a log (measurement models / ``observableFormula``). - `15. PEtab priors `__ — declare what you believe: a PEtab prior gallery and how each imports (``priorDistribution`` → priors). - `20. PEtab observable parameters `__ — import per-observable gains and noise, the Boehm ``sd_*`` pattern (``observableParameters`` / ``noiseParameters``). - `29. PEtab protocols `__ — round-trip dose-response and pre-equilibration through PEtab (``conditions`` / ``experiments``). - `33. SBML PEtab `__ — import a standard SBML PEtab problem and fit it through bngsim (``sbml_backend = bngsim``). - `34. PEtab observableFormula `__ — an arithmetic ``observableFormula`` (ratio / log / scale) in a PEtab table, and its round-trip. Model interoperability and checking ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - `11. Interop `__ — fit the same model as BNGL, SBML, and Antimony, one backend, one answer (``sbml_backend`` on bngsim). - `31. BNGL + SBML fit `__ — one fit mixing a BNGL model and an SBML model (multi-model). - `46. Model checking `__ — does the model satisfy the spec? check a model against qualitative properties, no fitting (``job_type = check``, BPSL ``at`` / ``once`` / ``always`` / ``between``). For the authoritative lesson map — including the edition-2 config keys each lesson uses — see the `tutorial README on GitHub `__. Interactive notebooks --------------------- A companion set of Jupyter notebooks shows the same edition-2 workflows driven **interactively** from a running kernel (PyBNF + bngsim), with results plotted inline. They live under `examples/notebooks `__ and are committed pre-executed, so you can read them without running anything. - `01. Quickstart `__ — write a model, make data, run a differential-evolution fit, plot fit vs data. - `02. bngsim simulation `__ — simulate a model forward with bngsim (no fitting): time courses, a parameter sweep, steady state. - `03. Posterior exploration `__ — sample a posterior with HMC/NUTS, export an ArviZ ``InferenceData``, and read trace / pair / R-hat / ESS. - `04. PEtab in a notebook `__ — import a PEtab problem with ``pybnf.petab.import_job`` and fit it interactively. - `05. Gradient fitting and profiles `__ — a multi-start trust-region least-squares fit using bngsim forward sensitivities, then profile-likelihood identifiability.