sensitivity.parameters¶
The table of the parameters of a sensitivity analysis, as sbmlsim 0.8 wrote it.
The parameters a sensitivity analysis of a model varies, with their values,
bounds, units, types and references, and the table of them,
parameters.tsv and parameters.tex, which the runner of the analyses
(sbmlsim.sensitivity.runner) writes next to their results. The rows and
columns are the ones of sbmlsim 0.8, so the tables which manuscripts read stay
the same:
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, out)
design = sobol(distributions(parameters), n=4096, seed=1234, model=MODEL_PATH)
sbmlsim.simulation.sampling.parameters_of lists the ids of the constant
parameters of a model for a design; parameters_from_sbml is the table of
sbmlsim 0.8 with the names, values and units, which selects the parameters
otherwise (the constant compartments and the constant or boundary species as
well, in the order of the model).
A global design draws the values around the values of the table. A model with
several variants (sbmlsim.project.Project.variants, e.g. a variant per population)
samples a group of another variant relative to the values of its variant:
build_values reads them, design_factors gives the ratios and
relative_design scales the design.
Bases: StrEnum
Where the value and the bounds of a parameter of an analysis come from.
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(
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 physiologically based model derives from its covariates. |
False
|
Returns:
| Type | Description |
|---|---|
list[SensitivityParameter]
|
The parameters, without 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]]
|
|
required |
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 |
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[str, Mapping[str, float]] | None
|
the values of the parameters in other variants of the model
than the one of the table, by the name of the variant (the runner
gives those of the variants of its groups other than the default
one); each is the column |
None
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
One row per parameter, the columns |
DataFrame
|
the type as its value. |
Write the table of the parameters as parameters.tsv and parameters.tex.
Each file is written atomically (sbmlsim.atomic.write_text_atomic).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
parameters
|
Sequence[SensitivityParameter]
|
the parameters. |
required |
directory
|
Path
|
the directory, created if it does not exist. |
required |
builds
|
Mapping[str, Mapping[str, float]] | None
|
the values in the other variants of the model, see
|
None
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
The table. |
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
|
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. the
degree of a 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, the designs of sbmlsim.simulation.sampling
do not (Scan warns about it), so a runner 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. |
Get the values of parameters in a variant of a model, as parameters_from_sbml reads them.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sbml_path
|
Path
|
the SBML model, e.g. a variant of the model. |
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. |
Get the factors which carry a design of the table to the values of a variant.
A global design draws the values of the parameters in their bounds around the values of the table, which are those of the default variant of the model. A group of another variant samples the same design relative to the values of its variant: every value of a parameter is multiplied with the ratio of its value in the variant to its value in the table, so e.g. a group of a variant varies the body weight around the body weight of its variant by the same factors as the default variant around its own. 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 variant 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 variant, 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. |
Get a design with the values of its parameters multiplied by factors.
The design of a group of another variant, 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. |