sensitivity¶

The sensitivity analyses of a model: the table of their parameters and their runner.

sbmlsim 0.9 analyses the sensitivity of a model on the result of a scan: a design of sbmlsim.simulation.sampling (local, sobol, fast, lhs) is a dimension of a Scan, and sbmlsim.sensitivity computes the indices on its result. It dropped the table of the parameters of an analysis (sbmlsim.sensitivity.parameters of sbmlsim 0.8), which the sensitivity scripts of the models write next to their results. This module is that table, with the behavior of sbmlsim 0.8, so the tables of the scripts stay the same, and the distributions of the global designs:

# not executed
parameters = parameters_from_sbml(MODEL_PATH, exclude_ids={"Mr_hctz"})
set_bounds(parameters, [("f_renal_function", 0.85, 1.15, ParameterType.SCALING)])
set_relative_bounds(parameters, 0.15)
write_parameters(parameters, MODEL.results_dir / "sensitivity")
design = sobol(distributions(parameters), n=sample_size(4096), seed=1234, model=MODEL_PATH)

SensitivityRunner runs the analyses of a script (LocalAnalysis, SamplingAnalysis, FastAnalysis, SobolAnalysis) over the simulations of its groups (SensitivityGroup) and writes the tables and figures of its outputs (SensitivityOutput); the script keeps only what is the model's own, its parameters, groups, outputs and observables:

# not executed
SENSITIVITY = SensitivityRunner(
    model=MODEL,
    parameters=sensitivity_parameters,
    outputs=OUTPUTS,
    observables=OBSERVABLES,
    analyses={
        "local": LocalAnalysis(groups=GROUPS[:1]),
        "sampling": SamplingAnalysis(groups=GROUPS),
    },
)

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

ParameterType ¶

Bases: StrEnum

Where the value and the bounds of a parameter of an analysis come from.

SensitivityParameter `dataclass` ¶

SensitivityParameter(
    *,
    uid,
    name,
    value=nan,
    lower_bound=nan,
    upper_bound=nan,
    unit=None,
    type=NA,
    reference="",
)

A parameter of a sensitivity analysis.

Attributes:

Name	Type	Description
`uid`	`str`	the id in the model.
`name`	`str`	the name in the model, the id if it has none.
`value`	`float`	the value in the model after its initialization.
`lower_bound`	`float`	the lower bound of the analysis.
`upper_bound`	`float`	the upper bound of the analysis.
`unit`	`str \| None`	the unit in the model.
`type`	`ParameterType`	where the value and the bounds come from.
`reference`	`str`	the references of the value, e.g. a LaTeX citation.

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`.

SensitivityGroup `dataclass` ¶

SensitivityGroup(
    uid,
    name,
    simulation,
    color=None,
    sex=MALE,
    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`.
`sex`	`Sex`	the sex of the group, whose build of the model it runs (`PKPDModel.model_paths`), the male build by default; the design of an analysis is the same for every group.
`prepare`	`Callable[[Scan, Path], Scan] \| None`	a function of the scan of the group over a design and the build of the group (`(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 model of the PBPK library (`pkpdsim.pbpk.Equilibration`), 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 script over the simulations of its groups.

The parameters it varies are the parameters of the script which no simulation of its groups sets (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 script with an analysis of its own runs it itself.

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 script.	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.

NonzeroLocalAnalysis `dataclass` ¶

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

Bases: LocalAnalysis

The local analysis of the parameters whose value is not 0.

A local design changes a value relative to itself, so a severity at 0 (the healthy individual) is not changed and its sensitivity is 0/0; the sampled analyses vary the severities within their bounds.

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; std of the population), 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 sensitivity script.

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).

SensitivityRunner `dataclass` ¶

SensitivityRunner(
    *,
    model,
    parameters,
    outputs,
    observables,
    analyses,
    default=("local",),
    seed=SEED,
)

The sensitivity analyses of a model, run by its script.

The script 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 its command line, or with run. A run writes the table of the parameters (write_parameters) into its folder, model.results_dir / "sensitivity", 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
`model`	`PKPDModel`	the model object: the models which are simulated (the build of the sex of every group, `SensitivityGroup.sex`), the folder of the results and the settings of the simulator.
`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]`	the observables of the simulation of a group, which give the observables of the outputs.
`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 on the command line, at least one.
`seed`	`int`	the seed of the designs.

simulator_settings ¶

simulator_settings(workers)

Get the settings of the simulator of a run which caps the processes.

Parameters:

Name	Type	Description	Default
`workers`	`int \| None`	the processes of `--workers` (`CommandLine.workers`).	required

Returns:

Type	Description
`SimulatorSettings \| None`	The settings of the model with `n_workers=workers`, `None` (the
`SimulatorSettings \| None`	default of `run`, `n_workers=None`) if `workers` is `None`.

run ¶

run(
    names=None, *, path=None, subfolder=None, simulator=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 build 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 male build; with groups of another sex the table has their values as well (value_<sex>).

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, `model.results_dir / "sensitivity"` 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`
`simulator`	`SimulatorSettings \| None`	the settings of the simulator, the settings of the model with `n_workers=None` (sbmlsim chooses the processes of the pool, the script has the guard `if __name__ == "__main__":`) if `None`.	`None`

Returns:

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

Raises:

Type	Description
`TypeError`	for names which are a string.
`ValueError`	for 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 sex); 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 and the `--workers` (`None` if absent or `0`),
`CommandLine`	which a script passes as `simulator=self.simulator_settings(workers)`.

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.	`None`

parameters_from_sbml ¶

parameters_from_sbml(
    sbml_path,
    exclude_ids=None,
    exclude_na=True,
    exclude_zero=True,
    *,
    exclude_derived=False,
)

Get the parameters of a model which an analysis varies, as sbmlsim 0.8 did.

The constant parameters, the constant compartments and the constant or boundary species, in the order of the model, with their values after the initialization (the concentration of a species with only substance units). A parameter whose value is not a number (exclude_na) or is close to zero (exclude_zero), and every id of exclude_ids, is left out; so is every derived parameter, compartment and species (exclude_derived).

Parameters:

Name	Type	Description	Default
`sbml_path`	`Path`	the SBML model.	required
`exclude_ids`	`Iterable[str] \| None`	the ids to leave out.	`None`
`exclude_na`	`bool`	leave out a parameter without a value.	`True`
`exclude_zero`	`bool`	leave out a parameter whose value is close to zero.	`True`
`exclude_derived`	`bool`	leave out every parameter, compartment and species with an initial assignment, e.g. the organ volumes and the clearances which a library model derives from its covariates; the covariates and the fitted parameters have none.	`False`

Returns:

Type	Description
`list[SensitivityParameter]`	The parameters, without bounds.

set_bounds ¶

set_bounds(parameters, bounds)

Set the bounds and the type of parameters.

Parameters:

Name	Type	Description	Default
`parameters`	`Iterable[SensitivityParameter]`	the parameters, changed in place.	required
`bounds`	`Iterable[tuple[str, float, float, ParameterType]]`	`(uid, lower bound, upper bound, type)`; a uid which is no parameter is logged and skipped, as sbmlsim 0.8 printed it.	required

set_relative_bounds ¶

set_relative_bounds(parameters, fraction)

Let every parameter without bounds vary by value * (1 +- fraction).

The bounds of a negative value are reversed, the lower bound value * (1 - fraction) is above the upper bound value * (1 + fraction), as in the table of sbmlsim 0.8, which stays the same; distributions refuses such a parameter, naming it, so a model sets its bounds with set_bounds. A value of 0 has the bounds 0 and 0.

Parameters:

Name	Type	Description	Default
`parameters`	`Iterable[SensitivityParameter]`	the parameters, changed in place.	required
`fraction`	`float`	the relative half width.	required

parameters_to_df ¶

parameters_to_df(parameters, sort=True, builds=None)

Get the table of the parameters.

Parameters:

Name	Type	Description	Default
`parameters`	`Sequence[SensitivityParameter]`	the parameters.	required
`sort`	`bool`	sort the rows by the type and the id, as sbmlsim 0.8 did.	`True`
`builds`	`Mapping[Sex, Mapping[str, float]] \| None`	the values of the parameters in other builds of the model than the one of the table, by sex (`SensitivityRunner` gives those of the sexes of its groups other than male); each is the column `value_<sex>` after `value`.	`None`

Returns:

Type	Description
`DataFrame`	One row per parameter, the columns `COLUMNS` (and `value_<sex>`), the
`DataFrame`	type as its value.

write_parameters ¶

write_parameters(parameters, directory, builds=None)

Write the table of the parameters as parameters.tsv and parameters.tex.

Parameters:

Name	Type	Description	Default
`parameters`	`Sequence[SensitivityParameter]`	the parameters.	required
`directory`	`Path`	the directory, created if it does not exist.	required
`builds`	`Mapping[Sex, Mapping[str, float]] \| None`	the values in the other builds of the model, see `parameters_to_df`.	`None`

Returns:

Type	Description
`DataFrame`	The table.

distributions ¶

distributions(parameters)

Get the distributions of the parameters of a global analysis, uniform in their bounds.

Parameters:

Name	Type	Description	Default
`parameters`	`Sequence[SensitivityParameter]`	the parameters, with bounds.	required

Returns:

Type	Description
`dict[str, Uniform]`	The distribution of every parameter, by its id.

Raises:

Type	Description
`ValueError`	naming the parameters without bounds, or with a lower bound above the upper one (the relative bounds of a negative value, see `set_relative_bounds`).

free_parameters ¶

free_parameters(parameters, simulations)

Get the parameters an analysis varies: those which none of its simulations sets.

A design replaces its targets wherever a simulation sets them, so a parameter which the simulation of a group sets (in its preinit_changes, the preinit_changes of its presimulation or in a Change, e.g. f_renal_function of the degree of renal impairment) would take the values of the design in every group, and the groups would be one analysis. sbmlsim 0.8.5 left such a parameter out of an analysis, sbmlsim 0.9's designs do not, so a script takes the parameters of a design from here. The ids are compared as written, plain ids as sbmlsim 0.8.5 did: a target given as a selection ([S]) does not match the parameter S. Every parameter left out is logged ("Removing fixed parameter"), as sbmlsim 0.8.5 printed it.

Parameters:

Name	Type	Description	Default
`parameters`	`Sequence[SensitivityParameter]`	the parameters of the analysis.	required
`simulations`	`Iterable[Simulation]`	the simulations of the groups of the analysis.	required

Returns:

Type	Description
`list[SensitivityParameter]`	The parameters which no simulation sets, in their order.

build_values ¶

build_values(sbml_path, uids)

Get the values of parameters in a build of a model, as parameters_from_sbml reads them.

Parameters:

Name	Type	Description	Default
`sbml_path`	`Path`	the SBML model, e.g. the female build.	required
`uids`	`Iterable[str]`	the ids of the parameters, compartments and species.	required

Returns:

Type	Description
`dict[str, float]`	The value after the initialization of every id the model has.

design_factors ¶

design_factors(parameters, values)

Get the factors which carry a design of the table to the values of a build.

A global design draws the values of the parameters in their bounds around the values of the table, which are those of the male build of the model. A group of another build samples the same design relative to the values of its build: every value of a parameter is multiplied with the ratio of its value in the build to its value in the table, so a group of women varies the body weight around the female body weight by the same factors as the men around the male one. The bounds of the table are taken relative to its values.

Parameters:

Name	Type	Description	Default
`parameters`	`Sequence[SensitivityParameter]`	the parameters which a design varies.	required
`values`	`Mapping[str, float]`	the values of the parameters in the build of a group.	required

Returns:

Type	Description
`dict[str, float]`	The ratio of every parameter whose value differs, by its id.

Raises:

Type	Description
`ValueError`	for a parameter which has no value in the build, and for a parameter whose value differs and whose bounds cannot be taken relative to its value: a value of the table which is zero or not finite, or a ratio which is not positive (another sign); naming the parameter and both values.

relative_design ¶

relative_design(design, factors)

Get a design with the values of its parameters multiplied by factors.

The design of a group of another build, see design_factors; the bounds of the uniform distributions of its record are multiplied as well.

Parameters:

Name	Type	Description	Default
`design`	`Dimension`	the design over the values of the table.	required
`factors`	`Mapping[str, float]`	the factor of a parameter, by its id; 1 for the others.	required

Returns:

Type	Description
`Dimension`	The design of the group, the given one without a factor.

pk_observables ¶

pk_observables(
    prefix,
    selection,
    outputs,
    *,
    dose=None,
    route=None,
    options=None,
    per_dose_mass=(),
    mr=None,
    pk_id=None,
)

Get the non-compartmental analysis of a concentration and its outputs.

The observables of a sensitivity analysis of the pharmacokinetics of a substance: the analysis pk_id (sbmlsim PK) of the concentration selection with the parameters of the outputs, then an observable <prefix>_<key> of every output in its unit (sbmlsim Formula). The dose of an analysis is a mass (PODOSE_<s> in mg), so an output whose unit has the amount of the dose (per_dose_mass, e.g. cl_f and vz_f) is divided by the molecular weight mr at the start (at(Mr_<s>, 0), a value per simulation like the parameter of the analysis); the molecular weight of the dosed substance, also for a metabolite of it.

# not executed
OBSERVABLES = [
    *pk_observables(
        "tor",
        "Carm_tor",
        {"auc_inf_obs": "mM*min", "cl_f": "ml/min"},
        dose="PODOSE_tor",
        route="oral",
        options=NCAOptions(lloq=LLOQ),
        per_dose_mass={"cl_f", "vz_f"},
        mr="Mr_tor",
    ),
    *pk_observables("Carm_tor_m5", "Carm_tor_m5", {"cmax": "mM"}, pk_id="pk_m5"),
]

Parameters:

Name	Type	Description	Default
`prefix`	`str`	the prefix of the ids of the outputs, e.g. the substance `tor` (`tor_cmax`) or the concentration `Carm_api` (`Carm_api_cmax`).	required
`selection`	`str`	the concentration, e.g. `Carm_tor`.	required
`outputs`	`Mapping[str, str]`	the unit of every output by the key of its parameter of the analysis (`pkpdutils`, e.g. `auc_inf_obs`, `cmax`, `cl_f`).	required
`dose`	`str \| None`	the dose state of the analysis, `None` for an analysis without a dose (a metabolite), see `sbmlsim.simulation.PK`.	`None`
`route`	`str \| None`	the route of the dose, e.g. `oral` or `iv_bolus`.	`None`
`options`	`NCAOptions \| None`	the options of the analysis, e.g. the limit of quantification relative to the maximum (`NCAOptions(lloq=...)`).	`None`
`per_dose_mass`	`Collection[str]`	the outputs whose unit has the amount of the dose.	`()`
`mr`	`str \| None`	the id of the molecular weight of the dosed substance, which an output of `per_dose_mass` is divided by, e.g. `Mr_tor`.	`None`
`pk_id`	`str \| None`	the id of the analysis, `pk_<prefix>` by default; an id of the model, e.g. a species `hctz`, is no id of an observable.	`None`

Returns:

Type	Description
`list[Observable]`	The analysis and the outputs.

Raises:

Type	Description
`ValueError`	if an output per dose mass has no molecular weight.

max_after_dose ¶

max_after_dose(time, values)

Get the maximum of a timecourse after the dose at the time 0.

The function of a Custom observable of one selection, e.g. the largest diuresis after a dose of a simulation which starts before it: Custom("max_diuresis", max_after_dose, "ml/min", symbols=["FLUID__diuresis"]).

Parameters:

Name	Type	Description	Default
`time`	`ndarray`	the times of the timecourse.	required
`values`	`Mapping[str, ndarray]`	the timecourse of the one selection of the observable.	required

Returns:

Type	Description
`float`	The maximum from the time 0 on.

Raises:

Type	Description
`ValueError`	for more or less than one selection.

sample_size ¶

sample_size(n)

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

The environment variable PKPDSIM_SENSITIVITY_N (a positive int) replaces n, e.g. PKPDSIM_SENSITIVITY_N=16 for a quick run of the scripts 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.

notes_sources ¶

notes_sources(sbase)

Get the sources in the notes of an element of a library model.

The library writes the sources of a value as a list after a paragraph Sources: of its notes.

Parameters:

Name	Type	Description	Default
`sbase`	`SBase`	the element.	required

Returns:

Type	Description
`list[str]`	The sources, one text per list item; empty without notes or sources.

library_parameters ¶

library_parameters(
    model_path,
    ids,
    *,
    fit_ids,
    scaling_ids,
    references=MappingProxyType({}),
    relative=0.15,
)

Get the parameters of the analyses of a model of the PBPK library.

A library model has hundreds of constants, most of them initial assignments of the covariates, which an analysis of all constants would vary as well; the analysis names the parameters it varies. They are the ids, in this order, with these bounds:

fitted parameters (fit_ids, type fitted): value * (1 +- relative);
scaling factors (scaling_ids, type scaling, 1 in the healthy individual): 1 +- relative;
severities (SEVERITIES, type scaling): 0 to relative * top, since relative bounds around 0 would be 0;
any other parameter: value * (1 +- relative).

The reference of a parameter is the sources of its notes (; separated), replaced by the text in references (e.g. the guideline of the classes of the renal function, whose notes give no source). A parameter of the type not set with a reference is of the type data.

Parameters:

Name	Type	Description	Default
`model_path`	`Path`	the SBML model.	required
`ids`	`Sequence[str]`	the parameters of the analysis.	required
`fit_ids`	`Collection[str]`	the fitted parameters among the `ids`.	required
`scaling_ids`	`Collection[str]`	the scaling factors among the `ids`.	required
`references`	`Mapping[str, str]`	references by id, which replace those of the notes.	`MappingProxyType({})`
`relative`	`float`	the relative half width of the bounds.	`0.15`

Returns:

Type	Description
`list[SensitivityParameter]`	The parameters of the `ids` with bounds, types and references.

Raises:

Type	Description
`ValueError`	naming every id which is no parameter of the model, and every id of `fit_ids`, `scaling_ids` or `references` which is not in `ids`.

run_subfolders ¶

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

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

A model with several simulations (dulaglutide: 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: the names, the parameters and the sizes, as SensitivityRunner.run checks them.

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, `model.results_dir / "sensitivity"` if `None`.	`None`
`simulator`	`SimulatorSettings \| None`	the settings 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`	for no runner, no subfolder, a subfolder which has no runner, is given twice or does not lie below `path`, runners of different models or with different parameters (they share one table), and see `SensitivityRunner.run`; before anything is written.

sensitivity¶

ParameterType ¶

SensitivityParameter dataclass ¶

SensitivityOutput dataclass ¶

SensitivityGroup dataclass ¶

Analysis dataclass ¶

varied ¶

LocalAnalysis dataclass ¶

NonzeroLocalAnalysis dataclass ¶

SamplingAnalysis dataclass ¶

FastAnalysis dataclass ¶

SobolAnalysis dataclass ¶

CommandLine ¶

SensitivityRunner dataclass ¶

simulator_settings ¶

run ¶

parse_command_line ¶

main ¶

parameters_from_sbml ¶

set_bounds ¶

set_relative_bounds ¶

parameters_to_df ¶

write_parameters ¶

distributions ¶

free_parameters ¶

build_values ¶

design_factors ¶

relative_design ¶

pk_observables ¶

max_after_dose ¶

sample_size ¶

notes_sources ¶

library_parameters ¶

run_subfolders ¶

SensitivityParameter `dataclass` ¶

SensitivityOutput `dataclass` ¶

SensitivityGroup `dataclass` ¶

Analysis `dataclass` ¶

LocalAnalysis `dataclass` ¶

NonzeroLocalAnalysis `dataclass` ¶

SamplingAnalysis `dataclass` ¶

FastAnalysis `dataclass` ¶

SobolAnalysis `dataclass` ¶

SensitivityRunner `dataclass` ¶