experiment.draws¶
The simulation experiments over the draws of the fitted parameters of a model.
A fit of a project becomes part of its model in three steps:
- Adopt the fit: the kind
fitwithadopt(or the kindadopt) writes the record of a finished fit (its parameters, the profile likelihood and the Fisher information) and the adopted fits of the project with it, which a person copies into the directory of the fit records of the project (Project.fits_dir), seesbmlsim.fit.records.adopt_fit. - Use it in the factory: a model file takes the value of a fitted
parameter from the records of the adopted fits, together with its
uncertainty, a distribution of the SBML package distrib, see
sbmlsim.fit.records.AdoptedRecords.parameter:
# not executed
FITS = PROJECT.fit_records()
Parameter("k", **FITS.parameter("k", unit=U.per_min), name="rate")
check_fit_parameters checks that every variant of the model has the
values and the distributions of the records.
3. Draw it: a run of the experiments with UncertaintySettings
(Project.run_experiments(..., uncertainty=...), the field uncertainty of
the kind simulate) draws the parameters of the default variant of the
model which have a distribution once (UncertaintyRun.create, a Latin
hypercube into the dimension sbmlsim.distrib.UNCERTAINTY_DIMENSION) and
gives every experiment the draws as its setting uncertainty;
SimulationExperiment.initialize then runs every simulation over the draws
and every curve of a simulation becomes the band of a quantile range with
the median, see apply_uncertainty.
The draws are independent per parameter: distrib states one distribution per parameter, the correlations of the Fisher information stay in the record.
dataclass
¶
The settings of a run over the draws of the fitted parameters.
Attributes:
| Name | Type | Description |
|---|---|---|
draws |
int
|
the number of draws. |
seed |
int
|
the seed of the draws. |
quantiles |
tuple[float, float]
|
the lower and the upper quantile of the bands. |
dataclass
¶
The draws and the settings of a run, a setting of the experiments.
Attributes:
| Name | Type | Description |
|---|---|---|
settings |
UncertaintySettings
|
the settings of the run. |
dimension |
Dimension
|
the draws of the fitted parameters. |
classmethod
¶
Draw the fitted parameters of the model of a project.
The draws are those of a variant of the model, the default variant
(Project.model_path) without; every variant has the same fitted
parameters with the same distributions (check_fit_parameters), so
the draws run on the experiments of every variant.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
project
|
Project
|
the project, whose variant has the distributions. |
required |
settings
|
UncertaintySettings
|
the settings of the run. |
required |
variant
|
str | None
|
the variant whose distributions are drawn, the default variant without. |
None
|
Returns:
| Type | Description |
|---|---|
UncertaintyRun
|
The run. |
Raises:
| Type | Description |
|---|---|
ValueError
|
if the project has no variants, or no parameter of the variant has a distribution. |
KeyError
|
naming the variants, for an unknown variant. |
Run an initialized experiment over the draws of the fitted parameters.
SimulationExperiment.initialize applies it for the setting
uncertainty. Every simulation becomes a scan over the draws (a scan gets
the dimension of the draws appended); a parameter which the simulation
sets itself, or which the model of the simulation does not have, is not
drawn, and a simulation without a drawn parameter runs once. Every curve
of a figure over the time of a task over the draws, or over the values of
a dimension of its scan (e.g. an amount at a time over the scanned renal
function), becomes the band of the quantiles of the draws with the
median, with the name and the colour of the curve. A curve whose x is
another variable of the task (e.g. an effect over a concentration) has no
common x across the draws: it draws the simulation with the fitted
values, which runs once next to the draws (<simulation>_fitted), over a
thin translucent line of every draw in its colour (the area of the draws,
without a legend entry; not for a curve with a line per point of a
dimension). The curves of the data stay.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
experiment
|
SimulationExperiment
|
the initialized experiment. |
required |
run
|
UncertaintyRun
|
the draws and the settings. |
required |
Raises:
| Type | Description |
|---|---|
ValueError
|
if a scan of the experiment has a dimension of the id of the draws, or a curve of a task draws a line per point of more than one dimension (a band is drawn per point of one). |
Check that the model has the fitted values and the uncertainty of the adopted fits.
Every parameter of an adopted fit must be a parameter of every variant of
the model (Project.variants) with the value of the record of the fit
(within VALUE_RTOL) and a distribution of its draws. A run over the
draws draws the parameters of the default variant only
(UncertaintyRun.create), and every draw replaces the parameter in every
variant: a variant whose value or distribution of a fitted parameter
differs would be simulated with the draws of another value, so it is a
problem, as is a value of the default variant other than the record's.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
project
|
Project
|
the project. |
required |
Returns:
| Type | Description |
|---|---|
list[str]
|
The problems, one line each; empty for a project without adopted fits. |