Release notes for sbmlsim 0.14.0

A release of the documentation, of quantities and of fits that converge. The documentation starts with a tutorial and shows what its code prints and plots. Results are quantities first: res.q[...], res.to(...), plots in units and label_axes. A fit simulates only the times of its data. Its finite differences follow the tolerance of the integrator, so the runs of a fit no longer stop next to their start values. A run of simulation experiments shows its progress and where the time went.

Results which change: the fits (another step of the finite differences), the Fisher information (another step), the units of SBML Level 1/2 models (the repressilator is in minutes and items) and the labels of figures (the short units of pint, time [h]).

Features

• A tutorial and the outputs of the documentation (#393).
  • Tutorial. docs/tutorial.md takes the whole body model of hydrochlorothiazide through the features of the package step by step: a simulation, observables, changes, scans, a sensitivity analysis, a fit to the data of Patel 1984 and an uncertainty analysis. The model is part of the package, sbmlsim.resources.HCTZ_SBML, so the tutorial runs after pip install sbmlsim.
  • Outputs. Every code block of the documentation is followed by what it prints and by the figures it draws. scripts/docs_outputs.py runs the blocks of a page and writes both into it. tests/docs/test_docs_code.py fails when a page is out of step with its code.
  • Pages. Every page was checked against the code and rewritten to be shorter and plainer.
• Results are quantities first (#398, #400, #401).
  • res.q["cp"] is a variable or coordinate of a ScanResult as a quantity, e.g. res.q["time"].to("hr"). One point of a ragged result has no padding, so res.sel(dose="high").q["cp"].max() is its peak.
  • res.to({"time": "hr", "pk.cmax": "µM"}) is a new result with variables and coordinates in other units and the same labels. Converting the time converts the times of the changes as well.
  • Quantities plot with matplotlib in their units: the first quantity on an axis sets its unit, the others are converted. sbmlsim.plot.label_axes(ax, "time", "HCTZ plasma") labels the axes time [h] and HCTZ plasma [ng/ml].
  • plot_bands draws quantities with time_unit, unit and name, so a band shares an axis with lines of quantities. plot_distribution takes unit and name.
  • The table of the data points of a fit, FitReport.points, FitMetrics.datapoints_df and datapoints.tsv, has the units of x and of the values in the columns x_unit and unit.
  • data.to_quantity takes the unit registry of the package by default.
  • The documentation reads results as quantities, plots them with their units and sets no steps: the output of a simulation is the steps of the integrator, and a common grid where one is needed is time= of the run.
• A run of experiments shows its progress and where the time went (#391, #399).
  • ExperimentRunner.run_experiments(progress=None) and run_experiments show a progress bar over the experiments and a row per running experiment on an interactive terminal or in a notebook, also for a run in a pool. progress=False prints nothing, True prints the last frame on any console.
  • A table of the timings ends the run: the seconds of every experiment per phase (models, initialization, simulations, data, figures, outputs) with totals and shares. ExperimentResult.timings has them.
  • The table fits narrow consoles and a console without UTF-8. The timing messages of the log are gone.

Changes

• Fits simulate the times of their data (#397).
  • A group of fit mappings simulates the start and the times of its data with the selections of its own mappings, also for observables which are timecourses without reductions, e.g. Formula("cp", "[Cve_hctz] * Mr_hctz"), which are evaluated on that output.
  • The evaluation of a fit, e.g. its report, simulates the output of the simulation for the curves of its figures, which were lines between the times of the data.
  • A step of the fit of the tutorial takes 1.0 ms instead of 2.0 ms.
• The finite differences follow the tolerance of the integrator (#397).
  • Before. The least squares optimizer took the step of SciPy, the square root of the machine epsilon, far below the noise of the integrator: the jacobian was noise and every run of the HCTZ fit stopped next to its start values. The Fisher information took central differences with a step of 1e-6, its standard errors were up to 30 times too small.
  • Now. A least squares fit takes diff_step = sqrt(relative_tolerance) of its settings (1e-3) unless it is given, also fit_cli (was 0.05) and the re-optimizations of a profile (was 0.05). The Fisher information takes the cube root of the relative tolerance (1e-2).
  • Effect. 17 of 20 runs of the HCTZ fit reach the best cost instead of 1 of 20, the median cost is 28.4 instead of 190.6. The Fisher matrix of its optimum is within 9e-4 of a reference at a tolerance of 1e-12, it was off by a factor of 143.
• The axis of a figure writes the short unit of pint: Axis("time", unit="hr") is labelled time [h], as label_axes labels it. A unit pint does not read is written as given.
• Less output. A ScanResult prints at most 8 of its variables. A plain number in the changes of a model logs no warning. A run without paths logs no warnings about them, and ExperimentRunner takes base_path and data_path as optional.

Fixes

• The default units of SBML Level 1/2 models: the time is in time, a species in substance and a compartment in volume, area or length, each of them redefined by a unit definition of the same id. The repressilator was in seconds without units of its species.
• The PEtab reader gave the data of a concentration [S] the unit of the amount.
• A change of a model in a unit which cannot be converted raises a ValueError; an unknown target raises as well.
• ExperimentReport failed for an experiment without a source file, e.g. one defined in a notebook, and for a model of inline SBML.
• A figure without titles of its plots had an empty band below its title.
• A curve with a style warned about its label as an ignored style argument.
• The label of error bars reads Patel 1984 ± SD.
• DataSet.from_df warned about a mean_sd column which lost nothing.
• The label of a hypothesis of one scenario names its scenario, and units of hypotheses and of the plots of the analyses are short, ng/ml.
• RoadrunnerSBMLModel.tolerances gives the compartment of every species.
• The sodium and chloride urine data of Patel 1984 in examples/hctz_fitting are tagged as urine.