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.