Release notes for sbmlsim 0.9.2

A patch release of fixes: parameter fitting, PEtab conditions and species, the models of parallel scans and of experiments, SBML events after a change, and the paths of exported problems. A few checks are stricter, they refuse input which gave wrong results silently before.

Fixes

Parameter fitting

• Parameter sets are evaluated in the units of the problem (#289). The values of a parameter set with units are converted into the resolved units of the problem before they are evaluated (fit, report, metrics, Fisher information, profiles and likelihood), ParameterSets.to_df(units=...) converts the values it displays, and the values the models start from are given in the units of their fit parameters, a target without a unit in the model is not converted.
• initialize changes a problem only when it succeeds (#289). The settings and the resolved data are taken over after the validation, so a failed initialization keeps the previous working state. A problem keeps its own copies of the fit parameters, so setting x0 of one problem no longer changes the start values of another problem of the same definition.
• One loss per fit (#289). The arguments of the optimizer, of a fit and of the reoptimization of a profile, cannot override the loss of FitSettings or add a second robust loss (loss other than "linear", f_scale other than 1). A run records its algorithm and the arguments of the optimizer in effect, and a new start value is used by the following runs.
• A failed simulation is never the best fit (#289). A simulation which fails gives an infinite cost also when its mapping has no data points, so it is neither cost zero nor the optimum of a fit; the optimum of a run is validated after the run.
• Reports are independent (#289). A FitReport keeps a copy of the definition and the parameter sets and initializes its own problem, so another report or a problem which is initialized again does not change its settings, and its figures and metrics come from the same evaluation. The data a report hands out can be changed without changing what it writes.
• Profiles and Fisher information (#289). A confidence interval of a profile uses only the converged, finite points, so an incomplete scan reports no spurious interval of zero width and does not classify the parameter as identifiable. A Fisher variance of zero gives a standard error and an interval of zero width instead of NaN.
• Combining results (#289). OptimizationResult.combine matches the parameters by their ids when the results list them in another order and refuses results of different parameter definitions.
• Numerics of the objective (#289). Soft L1 keeps small residuals exact and does not overflow for large finite ones, an infinite residual stays infinite. The normalization of the log-likelihood stays in log space for extreme noise. Differential evolution accepts bounded parameters without start values.

PEtab

• Conditions of a later period are changes at their time (#289). With the sbmlsim extension, a condition of a later period was applied before the initialization of the model.
• Species and targets of conditions per model (#289). The formulas of species and the targets of conditions use the model of their experiment, so a problem of several models keeps the concentration and amount semantics of each one.
• The extension and the standard tables are compared (#289). A problem whose standard periods and conditions disagree with the simulation of the sbmlsim extension is read with a warning naming the experiment, the conditions and the differing targets or times; the extension stays authoritative, and its units and output grid are kept.
• A problem which is read is fitted in parallel (#289). Its experiment class is pickled as its PEtab definition and built again in every worker. PetabReader.from_yaml and from_petab take derived_dir, the directory of the compiled models.
• Exports stay in their directory (#289). The export refuses a model file name of an SBML derivation annotation which would write outside of the output directory, also through a symbolic link.

Simulation, models and experiments

• Events triggered by a change follow SBML (#289). Events which a change triggers are executed by priority, evaluated again after every event, ties in document order, with their persistence and the values of the time of the trigger or of the execution. A priority the simulator cannot evaluate is 0, with a warning.
• Parallel scans simulate the model which was loaded (#289). The workers load the SBML the model was loaded from, a hierarchical model flattened, so a source file which is rewritten or deleted after loading does not change the simulation. A compiled plan checks the symbols and units of its model before it runs, also in a worker.
• Models of experiments (#289). An abstract model loads its resolved path, so another working directory does not load another model, and keeps its selections. Experiments which name the same relative file in different directories no longer share a cached model, and an inline hierarchical model resolves its submodels against its resource directory.
• Units of hierarchical models (#289). The units are read from the flattened SBML, which keeps the units of the species and compartments of the submodels.
• Reserved names in scans (#289). A target named like a variable of the result, e.g. status, is a coordinate <dimension>.<target>, and a clash of names is reported before the simulation.
• Interpolation at the end (#289). The interpolation keeps the exact end points of a simulation next to undefined values, also in a result padded after the end of a simulation.
• JSON of experiments (#289). The definition keeps the parameters of data formulas, the selections and resource directories of the models and the ids of the tasks, writes NumPy scalars as JSON numbers and is written only once it is encoded, so a failure leaves no truncated file.

Networks, sampling and comparison

• Networks of PEtab SciML (#289). Sparse indices of an input are refused without expanding the inferred index space, activations keep NaN, and frozen elements must be finite.
• Profile sampling (#289). profile_parameters draws from the piecewise linear density by inverting its integral exactly and normalizes the density of every parameter by itself, which removes the bias of the draws and the underflow after another profile found a better optimum.
• Units of distributions (#289). cdf converts a quantity into the unit of the distribution.
• Comparison of datasets (#289). DataSetsComparison compares every candidate with the reference, the rows by position and not by their index, tables without time with time_column=False, and integer columns without wrapping; an undefined value never agrees.

Stricter checks

These raise where 0.9.1 gave a result which was silently wrong (#289):

• A parameter set with an explicit unit for a fit parameter without a unit raises, since the unit of the target is unresolved.
• loss and f_scale of the optimizer other than the defaults raise, the loss belongs to FitSettings.
• Normalized residuals of training data whose mean is zero raise, the normalization would divide by zero.
• sbmlsim.serialization.to_json raises a TypeError for an object it cannot encode instead of writing its string or its internal attributes; a SimulationExperiment whose definition holds such an object logs a warning naming its type and writes no JSON.
• DataSetsComparison raises for fewer than two results, for results without rows and for selections and factors of different length; its relative difference stays NaN where a value is undefined.

Performance

• Parallel scans (#289). The workers read one private snapshot per distinct model instead of receiving the SBML with every chunk, at most two chunks per worker are pending, and the models of the workers are reused across runs.
• Scans of values per simulation (#289). A scan which keeps only values per simulation does not interpolate, transmit or assemble the timecourses it drops.
• Reports and metrics (#289). A fit report and its metrics evaluate a parameter set once for the metrics, the tables and the figures, and the Fisher summaries reuse their decompositions.
• Networks (#289). The evaluation of a network releases intermediate activations after their last use and does not check the immutable nominal arrays again.