sensitivity¶

The parameters of the sensitivity analyses of a model.

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)

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.

parameters_from_sbml ¶

parameters_from_sbml(
    sbml_path,
    exclude_ids=None,
    exclude_na=True,
    exclude_zero=True,
)

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.

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`

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)

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`

Returns:

Type	Description
`DataFrame`	One row per parameter, the columns `COLUMNS`, the type as its value.

write_parameters ¶

write_parameters(parameters, directory)

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

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.

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.

sensitivity¶

ParameterType ¶

SensitivityParameter dataclass ¶

parameters_from_sbml ¶

set_bounds ¶

set_relative_bounds ¶

parameters_to_df ¶

write_parameters ¶

distributions ¶

free_parameters ¶

sample_size ¶

SensitivityParameter `dataclass` ¶