sensitivity.runner¶

The sensitivity analyses of a project over the groups of its simulations.

A SensitivityRunner runs the analyses of a model (LocalAnalysis, SamplingAnalysis, FastAnalysis, SobolAnalysis) over the simulations of their groups (SensitivityGroup, each on a variant of the model of the project, sbmlsim.project.Project.variants) and writes the table of the parameters (sbmlsim.sensitivity.parameters) and the tables and figures of its outputs (SensitivityOutput) in the layout of sbmlsim 0.8.5, which manuscripts read. The designs are the ones of sbmlsim.simulation.sampling, the indices the ones of sbmlsim.sensitivity; the runner keeps only what is the model's own, its parameters, groups, outputs and observables:

SENSITIVITY = SensitivityRunner(
    project=PROJECT,
    parameters=sensitivity_parameters,
    outputs=OUTPUTS,
    observables=OBSERVABLES,
    analyses={
        "local": LocalAnalysis(groups=GROUPS[:1]),
        "sampling": SamplingAnalysis(groups=GROUPS),
    },
    out=Path("results/sensitivity"),
)

if __name__ == "__main__":
    SENSITIVITY.main()

A project lists its runners in Project.sensitivities, a runner or a mapping of runners by subfolder (run_subfolders, a model with several simulations), or a reference "module:attribute" to either; the kind sensitivity of python -m sbmlsim.run runs them into its --out, one unit per analysis and subfolder (prepare_run).

The layout of the results below the folder of a run:

analysis	files
every run	`parameters.tsv`, `parameters.tex`
local	`local/local_d<delta>_nvar<n_var>_<k>_<group>.tsv` and `.png`
sampling	`sampling/<group>/samples.tsv`, `sampling/sampling_N<n>.tsv`, `_compact.tsv`, `.tex`, `_sensitivity_samples.png`, `_sensitivity_outputs.png`
fast, sobol	`<analysis>/<group>/<output>.S1.tsv` and `.ST.tsv`, `<analysis>/<prefix>_sensitivity_<k>_<group>_S1.png`, `_ST.png` and `_<ko>_<output>.png`
subfolders	`<subfolder>/<analysis>/...`, the table once in the folder

SensitivityOutput `dataclass` ¶

SensitivityOutput(uid, name, observable='')

An output of the analyses, an observable of the simulation of a group.

Attributes:

Name	Type	Description
`uid`	`str`	the id of the output in the tables and the names of the files: the columns `output` and `uid` of the tables of sbmlsim 0.8.5, the columns of `samples.tsv`, `<uid>.S1.tsv`, `<uid>.ST.tsv` and the figure of its indices, `..._<o>_<uid>.png`.
`name`	`str`	the name of the output in the titles of the figures, in the heatmaps and in the column `name` of the tables of sbmlsim 0.8.5, unique among the outputs of a runner.
`observable`	`str`	the id of the observable in the result of the scan, the uid when empty; an id of an output which is no identifier, e.g. `[Cve_api]_cmax`, names an observable `Cve_api_cmax`. A parameter of a `PK` observable is `<id>.<parameter>`, e.g. `pk.cmax`.

SensitivityGroup `dataclass` ¶

SensitivityGroup(
    uid,
    name,
    simulation,
    color=None,
    variant=None,
    prepare=None,
)

A group of the analyses, e.g. a degree of renal impairment.

Attributes:

Name	Type	Description
`uid`	`str`	the id of the group, the folder of its tables and figures.
`name`	`str`	the name of the group in the titles of the figures.
`simulation`	`Simulation`	the simulation of the group, its changes in `preinit_changes`; an analysis varies no parameter which it sets, see `free_parameters`.
`color`	`str \| None`	the color of the group in the figures of `sampling` which compare the groups, a color of matplotlib; the color of the property cycle of matplotlib (`C0`, `C1`, ...) of its position if `None`.
`variant`	`str \| None`	the variant of the model of the project which the group runs (`Project.variants`), the default variant (the first) if `None`; the design of an analysis is the same for every group, relative to the values of its variant, see `design_factors`.
`prepare`	`Callable[[Scan, Path], Scan] \| None`	a function of the scan of the group over a design and the SBML file of its variant (`(scan, model_path) -> scan`) which gives the scan that runs, `None` for the scan as it is; e.g. the drug-free equilibration of every point of a physiologically based model, which replaces a long pre-run from a negative start that leaves a slow state off its steady state. The module knows no model: what the function does is the model's.

Analysis `dataclass` ¶

Analysis(*, groups)

Bases: ABC

An analysis of a runner over the simulations of its groups.

The parameters it varies are the parameters of the runner which no simulation of its groups sets (varied, free_parameters). It writes one result per quantity: the tables and figures of sbmlsim 0.8.5, with their names, into <analysis>, and what sbmlsim 0.8.5 wrote no file of (the samples, the tables of the global indices) per group into <analysis>/<group>. The analyses are the four of this module, LocalAnalysis, SamplingAnalysis, FastAnalysis and SobolAnalysis; a subclass may vary other parameters by overriding varied.

Attributes:

Name	Type	Description
`groups`	`Sequence[SensitivityGroup]`	the groups of the analysis, at least one, the ids unique; stored as a tuple.

varied ¶

varied(parameters)

Get the parameters the analysis varies, which no group sets.

Parameters:

Name	Type	Description	Default
`parameters`	`Sequence[SensitivityParameter]`	the parameters of the runner.	required

Returns:

Type	Description
`list[SensitivityParameter]`	The parameters, see `free_parameters`.

LocalAnalysis `dataclass` ¶

LocalAnalysis(*, groups, delta=0.01, n_var=3)

Bases: Analysis

The local sensitivities of every group, each parameter by +-delta, as sbmlsim 0.8.5.

Per group the designs sampling.local of delta * k / n_var, k = 1, ..., n_var (their values are those of the simulation of the group), the indices sensitivity.local, and the table of sbmlsim 0.8.5, local_d<delta>_nvar<n_var>_<k>_<group>.tsv (a row per parameter and output: parameter, output, effect, Sij, |Sij|, classification, method, difference, n_var, sorted by |Sij|; Sij the mean of normalized over the designs, as sbmlsim 0.8.5 averaged its steps), and its heatmap (.png, the parameters with their names, the outputs by name, cutoff 0.05, no clustering), in the folder of the analysis.

Attributes:

Name	Type	Description
`delta`	`float`	the relative change of a parameter, in (0, 1).
`n_var`	`int`	the number of steps of sbmlsim 0.8.5 up to `delta`, at least 1.

SamplingAnalysis `dataclass` ¶

SamplingAnalysis(*, groups, n=1000)

Bases: _SampledAnalysis

The uncertainty of the outputs over a Latin hypercube of the parameters.

One design sampling.lhs of sample_size(n) points for every group; per group the parameters and outputs of every point, samples.tsv (sbmlsim 0.8.5 kept them in its cache only). The tables and figures of sbmlsim 0.8.5 compare the groups: sampling_N<n>.tsv (a row per group and output: gid, gname, uid, name, N, mean, median, std, cv, min, q005, q095, max, the uncertainty U = (P97.5 - P2.5) / P50, its symbol and classification, unit; the statistics of ScanResult.summary, std the sample standard deviation), sampling_N<n>_compact.tsv and its LaTeX table sampling_N<n>.tex (an output per row, mean (cv in %) per group), and the figures of the samples of the parameters and of the outputs per group, sampling_N<n>_sensitivity_samples.png and ..._outputs.png.

Attributes:

Name	Type	Description
`n`	`int`	the number of samples, see `sample_size`.

FastAnalysis `dataclass` ¶

FastAnalysis(*, groups, n=1000)

Bases: _GlobalAnalysis

The indices of the extended FAST, sampling.fast and sensitivity.fast.

The files of sbmlsim 0.8.5 have the prefix fast_M4_N<n>.

Attributes:

Name	Type	Description
`n`	`int`	the number of samples per parameter, more than 64 (`4 m^2` of the `m = 4` harmonics of `sampling.fast`), see `sample_size`.

SobolAnalysis `dataclass` ¶

SobolAnalysis(*, groups, n=4096)

Bases: _GlobalAnalysis

The Sobol indices, sampling.sobol and sensitivity.sobol.

The files of sbmlsim 0.8.5 have the prefix sobol_N<n>.

Attributes:

Name	Type	Description
`n`	`int`	the base number of samples, a power of two of at least 2, see `sample_size`.

CommandLine ¶

Bases: NamedTuple

The words of the command line of a runner.

Attributes:

Name	Type	Description
`analyses`	`tuple[str, ...]`	the names of the analyses, the default analyses without one.
`choices`	`tuple[str, ...]`	the words of the choices of the script, in their order, none if none is given.
`workers`	`int \| None`	the processes of `--workers`, `None` if not given or `0` (`n_workers=None`, sbmlsim chooses).
`out`	`Path \| None`	the folder of `--out`, `None` if not given.

SensitivityRunner `dataclass` ¶

SensitivityRunner(
    *,
    parameters,
    outputs,
    observables,
    analyses,
    default=("local",),
    seed=SEED,
    project=None,
    out=None,
    description="",
)

The sensitivity analyses of a model of a project.

The runner gives what is the model's own (the parameters, the outputs with their observables, the analyses with their groups) and runs them with main from a command line, with run, or as an entry of Project.sensitivities with the kind sensitivity. A run writes the table of the parameters (write_parameters) into its folder and the results of an analysis into <analysis> below it, or below a subfolder of it, see Analysis. A model with several simulations has a runner per simulation, see run_subfolders. What can be checked is checked when the runner is created, and the rest at the start of a run, before anything is written.

Attributes:

Name	Type	Description
`parameters`	`Callable[[], Sequence[SensitivityParameter]]`	the function which gives the parameters of the analyses with their bounds; it reads the model, so it is called by a run.
`outputs`	`Sequence[SensitivityOutput]`	the outputs of the analyses, at least one, the ids, the names and the observables unique; stored as a tuple.
`observables`	`Sequence[Observable] \| Callable[[], Sequence[Observable]]`	the observables of the simulation of a group, which give the observables of the outputs, or a function which builds them when a run starts, e.g. the non-compartmental analyses which a model package supplies; a sequence is stored as a tuple.
`analyses`	`Mapping[str, Analysis]`	the analyses by name, the name on the command line and the folder; at least one, stored read-only.
`default`	`Sequence[str]`	the analyses which run without a name, at least one.
`seed`	`int`	the seed of the designs.
`project`	`Project \| None`	the project, whose variants the groups run and whose simulator settings the simulations use; `None` for a runner which a project lists, which binds it (`Project.sensitivity`).
`out`	`Path \| None`	the folder of the results of a run without a folder of its own (`run(path=...)`, `--out`), e.g. the results directory of a model package; a run without either raises.
`description`	`str`	what the analyses analyse, listed by `Project.analyses`.

bound ¶

bound(project)

Get the runner of a project, which binds a runner without a project.

Parameters:

Name	Type	Description	Default
`project`	`Project`	the project which lists the runner.	required

Returns:

Type	Description
`SensitivityRunner`	The runner with the project.

Raises:

Type	Description
`ValueError`	for a runner of another project, or a group of a variant which the project has not.

run ¶

run(names=None, *, path=None, subfolder=None, workers=None)

Run analyses and write the table of the parameters.

The names, the parameters (their distributions, whether an analysis varies one, whether a global design carries to the variant of every group, design_factors) and the numbers of samples of a smoke run are checked before anything is written. The values of the table are those of the default variant; with groups of another variant the table has their values as well (value_<variant>).

Parameters:

Name	Type	Description	Default
`names`	`Sequence[str] \| None`	the names of the analyses, `default` if `None`.	`None`
`path`	`Path \| None`	the folder of the results and of the table of the parameters, `out` if `None`.	`None`
`subfolder`	`str \| None`	the folder of the analyses below `path`; the table of the parameters stays in `path`. Several simulations of a model run with `run_subfolders`, which writes the table once.	`None`
`workers`	`int \| None`	the processes of the simulator, `None` lets sbmlsim choose (a pool for large designs; the script has the guard `if __name__ == "__main__":`).	`None`

Returns:

Type	Description
`Path`	The folder of the results, `path`.

Raises:

Type	Description
`TypeError`	for names which are a string.
`ValueError`	for a runner without a project, a run without a folder, a name which is no analysis or is given twice, a subfolder which does not lie below `path`, and see `distributions`, `sample_size` and `design_factors` (a global design of a group of another variant); before anything is written.

parse_command_line ¶

parse_command_line(argv=None, *, choices=())

Read the names of the analyses, and of choices of the script, from a command line.

A script with a choice of its own, e.g. the simulation of a model with several, reads it here with the names of the analyses, in any order (local sampling multi), and runs the analyses itself.

Parameters:

Name	Type	Description	Default
`argv`	`Sequence[str] \| None`	the arguments, those of the process if `None`.	`None`
`choices`	`Sequence[str]`	the words of the choices of the script, none an analysis.	`()`

Returns:

Type	Description
`CommandLine`	The names of the analyses, the default analyses without one, the
`CommandLine`	words of the choices, the `--workers` (`None` if absent or `0`),
`CommandLine`	which a script passes as `workers`, and the folder of `--out`.

Raises:

Type	Description
`TypeError`	for arguments which are a string.
`ValueError`	for a choice which is the name of an analysis.
`SystemExit`	with 2 for a word which is neither an analysis nor a choice or which is given twice (argparse), with 0 for `--help`.

main ¶

main(argv=None)

Run the analyses named on the command line, see parse_command_line, run.

Parameters:

Name	Type	Description	Default
`argv`	`Sequence[str] \| None`	the arguments, those of the process if `None`: the names of the analyses, `default` without one; an unknown name exits with 2; `--workers N` caps the processes of the pool, `--out DIR` is the folder of the results, `out` without.	`None`

SensitivityUnit `dataclass` ¶

SensitivityUnit(subfolder, analysis)

An analysis of a run, in a subfolder for a run of several runners.

Attributes:

Name	Type	Description
`subfolder`	`str \| None`	the subfolder of its runner, `None` for a single runner.
`analysis`	`str`	the name of the analysis.

folder `property` ¶

folder

The folder of the analysis relative to the folder of the run.

PreparedRun `dataclass` ¶

PreparedRun(
    project,
    runners,
    parameters,
    observables,
    plans,
    builds,
    _models=dict(),
)

A checked run of sensitivity analyses: its table and its units.

Created by prepare_run, which checks everything a run needs before anything is written; write_table writes the table of the parameters and run_unit runs one analysis into a folder.

Attributes:

Name	Type	Description
`project`	`Project`	the project of the runners.
`runners`	`Mapping[str \| None, SensitivityRunner]`	the runners by their subfolder, `None` for a single runner.
`parameters`	`tuple[SensitivityParameter, ...]`	the parameters of the table.
`observables`	`Mapping[str \| None, tuple[Observable, ...]]`	the observables of every runner.
`plans`	`Mapping[str \| None, tuple[tuple[str, ...], dict[str, list[SensitivityParameter]]]]`	the names of the analyses of every runner and the parameters each varies.
`builds`	`Mapping[str, Mapping[str, float]]`	the values of the parameters in the variants of the groups other than the default one, by variant.

units `property` ¶

units

The analyses of the run, in the order of the runners and their names.

identity ¶

identity()

Get what the run computes, JSON types, which the plan of the kind records.

The table of the parameters as the hash of its values to twelve digits (a platform may differ in the last bits) and every unit with its analysis, its groups, its resolved settings (the number of samples of a smoke run, SBMLSIM_SENSITIVITY_N), the parameters it varies, the outputs and the seed.

Returns:

Type	Description
`dict[str, Any]`	`{"table": <sha256>, "units": [...]}`.

unit_identity ¶

unit_identity(unit)

Get what a unit computes, see identity.

Parameters:

Name	Type	Description	Default
`unit`	`SensitivityUnit`	one of `units`.	required

write_table ¶

write_table(path, *, show=False)

Write the table of the parameters into a folder.

Parameters:

Name	Type	Description	Default
`path`	`Path`	the folder, created if it does not exist.	required
`show`	`bool`	print the table on the console of the package.	`False`

Returns:

Type	Description
`DataFrame`	The table.

simulator ¶

simulator(workers)

Create the simulator of a run with the settings of the project.

Parameters:

Name	Type	Description	Default
`workers`	`int \| None`	the processes, `None` lets sbmlsim choose.	required

run_unit ¶

run_unit(unit, folder, simulator)

Run an analysis of the run into a folder.

Parameters:

Name	Type	Description	Default
`unit`	`SensitivityUnit`	the analysis, one of `units`.	required
`folder`	`Path`	the folder of the analysis.	required
`simulator`	`Simulator`	the simulator, see `simulator`.	required

sample_size ¶

sample_size(n)

Get the number of samples of a sampled analysis, n unless a smoke run sets another.

The environment variable SBMLSIM_SENSITIVITY_N (a positive int) replaces n, e.g. SBMLSIM_SENSITIVITY_N=16 for a quick run of the analyses in a verification.

Parameters:

Name	Type	Description	Default
`n`	`int`	the number of samples of the analysis.	required

Returns:

Type	Description
`int`	The number of samples.

Raises:

Type	Description
`ValueError`	if the variable is set and is no positive int.

bind ¶

bind(target, project)

Bind a runner or the runners of subfolders to the project which lists them.

Parameters:

Name	Type	Description	Default
`target`	`SensitivityRunner \| Mapping[str, SensitivityRunner]`	a runner or the runners by their subfolder.	required
`project`	`Project`	the project.	required

Returns:

Type	Description
`SensitivityRunner \| dict[str, SensitivityRunner]`	The runners with the project, see `SensitivityRunner.bound`.

Raises:

Type	Description
`TypeError`	for an object which is neither.
`ValueError`	see `SensitivityRunner.bound`.

prepare_run ¶

prepare_run(target, names=None, subfolders=None)

Check a run of a runner or of the runners of subfolders, before anything is written.

The names of the analyses, the subfolders, the project, the parameters (read once per function), their distributions, whether an analysis varies one, the numbers of samples of a smoke run and whether a global design carries to the variant of every group.

Parameters:

Name	Type	Description	Default
`target`	`SensitivityRunner \| Mapping[str, SensitivityRunner]`	a runner, or the runners by the name of their subfolder.	required
`names`	`Sequence[str] \| None`	the names of the analyses, the default analyses of every runner if `None`.	`None`
`subfolders`	`Sequence[str] \| None`	the subfolders which run, every one if `None`; only for the runners of subfolders.	`None`

Returns:

Type	Description
`PreparedRun`	The prepared run.

Raises:

Type	Description
`TypeError`	for names or subfolders which are a string.
`ValueError`	for no runner, no subfolder, a subfolder which has no runner, is given twice or does not lie below the folder, runners of different projects or with different parameters (they share one table), subfolders of a single runner, and see `SensitivityRunner.run`.

run_subfolders ¶

run_subfolders(
    runners,
    names=None,
    *,
    subfolders=None,
    path=None,
    workers=None,
)

Run the analyses of several simulations of a model, each into a subfolder.

A model with several simulations (e.g. a single dose and weekly doses) has a runner per simulation, with its outputs and groups, by the name of its subfolder. The table of the parameters is written and printed once into path, the analyses of a runner run into path / <subfolder> / <analysis> / <group>. Everything is checked before anything is written, for every runner, see prepare_run.

Parameters:

Name	Type	Description	Default
`runners`	`Mapping[str, SensitivityRunner]`	the runners by the name of their subfolder.	required
`names`	`Sequence[str] \| None`	the names of the analyses, the default analyses of every runner if `None`.	`None`
`subfolders`	`Sequence[str] \| None`	the subfolders which run, every one if `None`.	`None`
`path`	`Path \| None`	the folder of the results, the `out` of the first runner which runs if `None`.	`None`
`workers`	`int \| None`	the processes of the simulator, see `SensitivityRunner.run`.	`None`

Returns:

Type	Description
`Path`	The folder of the results, `path`.

Raises:

Type	Description
`TypeError`	for names or subfolders which are a string.
`ValueError`	see `prepare_run` and `SensitivityRunner.run`; before anything is written.

sensitivity.runner¶

SensitivityOutput dataclass ¶

SensitivityGroup dataclass ¶

Analysis dataclass ¶

varied ¶

LocalAnalysis dataclass ¶

SamplingAnalysis dataclass ¶

FastAnalysis dataclass ¶

SobolAnalysis dataclass ¶

CommandLine ¶

SensitivityRunner dataclass ¶

bound ¶

run ¶

parse_command_line ¶

main ¶

SensitivityUnit dataclass ¶

folder property ¶

PreparedRun dataclass ¶

units property ¶

identity ¶

unit_identity ¶

write_table ¶

simulator ¶

run_unit ¶

sample_size ¶

bind ¶

prepare_run ¶

run_subfolders ¶

SensitivityOutput `dataclass` ¶

SensitivityGroup `dataclass` ¶

Analysis `dataclass` ¶

LocalAnalysis `dataclass` ¶

SamplingAnalysis `dataclass` ¶

FastAnalysis `dataclass` ¶

SobolAnalysis `dataclass` ¶

SensitivityRunner `dataclass` ¶

SensitivityUnit `dataclass` ¶

folder `property` ¶

PreparedRun `dataclass` ¶

units `property` ¶