uncertainty¶

The uncertainty of the fitted parameters of a model and the bands of its predictions.

A fit of a model becomes part of the model in three steps:

Adopt the fit: run_fit <package> --adopt <fit id> copies the record of a finished fit (its parameters, the profile likelihood and the Fisher information) from the results of the fits into the tracked folder of the fits next to the model (PKPDModel.fits_dir), see adopt_fit.
Use it in the factory: the model lists its adopted fits (PKPDModel.fits), and a model file takes the value of a fitted parameter from the record, together with its uncertainty, see FitRecords.parameter:

# not executed
FITS = MODEL.fit_records()
Parameter("k", **FITS.parameter("k", unit=U.per_min), name="rate")

The uncertainty is a distrib Uncertainty on the SBML parameter: the confidence interval of the profile likelihood (the Fisher information when the fit has no profile), the standard error of the Fisher information, the distribution the draws of the parameter come from and the provenance in its notes, see ParameterUncertainty. check_fit_parameters checks that the model has them. 3. Draw it: run_simulation <package> --uncertainty reads the distributions of the parameters of the model (parameter_distributions), draws them into the dimension uncertainty (uncertainty_dimension) and runs every simulation over the draws; 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.

UncertaintyMethod ¶

Bases: StrEnum

Where the uncertainty of a fitted parameter comes from.

ParameterUncertainty `dataclass` ¶

ParameterUncertainty(
    *,
    pid,
    value,
    unit,
    lower_bound,
    upper_bound,
    scale,
    alpha,
    z,
    method,
    ci_lower,
    ci_upper,
    identifiability=None,
    standard_error=None,
    fisher_ci=None,
    fit_id,
    cost,
    n_data=None,
    record,
)

The fitted value of a parameter and its uncertainty, from the record of a fit.

All numbers are in the unit of the model (unit); the scale is the space the fit searched the parameter in.

Attributes:

Name	Type	Description
`pid`	`str`	the id of the parameter in the flat model.
`value`	`float`	the fitted value.
`unit`	`str \| None`	the unit of the model, as the fit wrote it.
`lower_bound`	`float`	the lower bound of the fit.
`upper_bound`	`float`	the upper bound of the fit.
`scale`	`ParameterScaleType`	the space the fit searched the parameter in.
`alpha`	`float`	the confidence level of the intervals.
`z`	`float`	the quantile of the standard normal of the confidence level of the profile, `sqrt(chi2(alpha, df))`.
`method`	`UncertaintyMethod`	where the confidence interval and the distribution come from.
`ci_lower`	`float \| None`	the lower end of the confidence interval, `None` if it is open (the profile reaches the bound).
`ci_upper`	`float \| None`	the upper end of the confidence interval, `None` if open.
`identifiability`	`str \| None`	the class of the profile likelihood, `None` without.
`standard_error`	`float \| None`	the standard error of the Fisher information in the space of the fit (`scale`), `None` without.
`fisher_ci`	`tuple[float, float] \| None`	the confidence interval of the Fisher information.
`fit_id`	`str`	the id of the fit.
`cost`	`float`	the cost of the fit.
`n_data`	`int \| None`	the number of data points of the fit, `None` if unknown.
`record`	`str`	the path of the record, relative to the folder of the fits.

sigma ¶

sigma()

Get the standard deviation of the distribution in the space of the fit.

From the profile it is the mean of the closed half widths of the confidence interval divided by z; from the Fisher information its standard error. None if neither side of the profile is closed.

interval ¶

interval()

Get the confidence interval, an open side at the bound of the fit.

standard_error_model ¶

standard_error_model()

Get the standard error in the unit of the model (delta method).

distribution ¶

distribution()

Get the distribution of the draws as a formula of distrib.

Returns:

Type	Description
`str`	On a logarithmic scale `lognormal(ln(value), sigma, lb, ub)` with
`str`	sigma in natural logarithms, on the linear scale `normal(value,
`str`	sigma, lb, ub)`, both truncated to the bounds of the fit; without a
`str`	closed side of the profile `uniform(lb, ub)`.

notes ¶

notes()

Get the provenance of the value and of its uncertainty as markdown.

uncertainty ¶

uncertainty(unit=None)

Get the distrib uncertainty of the parameter.

Parameters:

Name	Type	Description	Default
`unit`	`UnitType`	the unit of the values, the unit of the parameter in the model definition (`sbmlutils.factory` unit).	`None`

Returns:

Type	Description
`Uncertainty`	The uncertainty: the confidence interval, the standard error of
`Uncertainty`	the Fisher information if there is one and the distribution of the
`Uncertainty`	draws, the provenance in its notes.

FitRecord `dataclass` ¶

FitRecord(directory, parameters)

The record of an adopted fit: the fitted parameters with their uncertainty.

Attributes:

Name	Type	Description
`directory`	`Path`	the directory of the record, named by the id of the fit.
`parameters`	`Mapping[str, ParameterUncertainty]`	the uncertainty of every fitted parameter by pid.

fit_id `property` ¶

fit_id

The id of the fit.

load `classmethod` ¶

load(directory)

Read the record of an adopted fit.

The value of a parameter is the best parameter set of the fit (parameters.json), the bounds and the scale are those of the problem (optimization_result.json); the confidence interval is the one of the profile likelihood (identifiability.json), the Fisher information (fisher.json) gives the standard error and is the fallback for a parameter without a profile.

Parameters:

Name	Type	Description	Default
`directory`	`Path`	the directory of the record.	required

Returns:

Type	Description
`FitRecord`	The record.

Raises:

Type	Description
`FileNotFoundError`	if the record lacks a required file or has neither a profile nor a Fisher information.
`ValueError`	if a fitted parameter has neither a profile nor a Fisher information.

FitRecords ¶

FitRecords(directory, fit_ids)

The adopted fits of a model: the fitted values and their uncertainty for the factory.

A model file takes the value of a fitted parameter from the record of its fit, so the value, its uncertainty and its provenance come from one place:

# not executed
FITS = MODEL.fit_records()
Parameter("HCTZEX_f", **FITS.parameter("KI__HCTZEX_f", unit=U.dimensionless))

Read the records of the adopted fits.

Parameters:

Name	Type	Description	Default
`directory`	`Path`	the folder of the adopted fits.	required
`fit_ids`	`Sequence[str]`	the ids of the adopted fits.	required

Raises:

Type	Description
`FileNotFoundError`	if a record does not exist.
`ValueError`	if a parameter is in two fits.

parameter ¶

parameter(pid, unit=None)

Get the keyword arguments of a sbmlutils.factory.Parameter of a fitted parameter.

Parameters:

Name	Type	Description	Default
`pid`	`str`	the id of the parameter in the flat model, as the fit names it.	required
`unit`	`UnitType`	the unit of the parameter in the model definition, set on the parameter and its uncertainty.	`None`

Returns:

Type	Description
`dict[str, Any]`	`value` and `uncertainties`, and `unit` if given.

Raises:

Type	Description
`KeyError`	if no adopted fit has the parameter.

UncertaintySettings `dataclass` ¶

UncertaintySettings(
    *, draws=100, seed=1234, quantiles=(0.05, 0.95)
)

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.

UncertaintyRun `dataclass` ¶

UncertaintyRun(settings, dimension)

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.

quantiles `property` ¶

quantiles

The quantiles of the bands.

id `property` ¶

id

The id of the dimension of the draws.

create `classmethod` ¶

create(model, settings)

Draw the fitted parameters of a model.

The draws are those of the male build (model_path); every build has the same fitted parameters with the same distributions (check_fit_parameters), so the draws run on the experiments of every build.

Parameters:

Name	Type	Description	Default
`model`	`PKPDModel`	the model, whose `model_path` has the distributions.	required
`settings`	`UncertaintySettings`	the settings of the run.	required

Returns:

Type	Description
`UncertaintyRun`	The run.

adopt_fit ¶

adopt_fit(fit_dir, fits_dir, *, force=False)

Copy the record of a finished fit into the folder of the fits of a model.

The record is the part of the results of a fit which the model needs: the parameters, the settings and the problem (optimization_result.json), the profile likelihood and the Fisher information with their tables, the metrics, the text report and the methods report as PDF and Typst source with its references (RECORD_FILES) and the figures the Typst source shows, in plots/, so that report.typ compiles in the record. The report is optional, a record of an older fit without it is adopted as well. The runs, the other figures, the LaTeX sources with the PNG copies of their figures and the HTML report stay in the results of the fit.

Parameters:

Name	Type	Description	Default
`fit_dir`	`Path`	the directory of the results of the fit, named by its id.	required
`fits_dir`	`Path`	the folder of the adopted fits of the model.	required
`force`	`bool`	replace a record of the same id.	`False`

Returns:

Type	Description
`Path`	The directory of the record.

Raises:

Type	Description
`FileNotFoundError`	if the fit does not exist, lacks a required file or has neither a profile likelihood nor a Fisher information.
`FileExistsError`	if the record exists and `force` is not set.

convert_value ¶

convert_value(value, unit, target)

Convert a number from one unit into another, both units of pint.

Parameters:

Name	Type	Description	Default
`value`	`float`	the number in `unit`.	required
`unit`	`str \| None`	the unit of the number, `None` for the unit of the target.	required
`target`	`str \| None`	the unit to convert into, `None` for the unit of the number.	required

Returns:

Type	Description
`float`	The number in `target`, the number itself if a unit is missing or
`float`	both are the same.

distribution_from_formula ¶

distribution_from_formula(formula)

Get the sbmlsim distribution of a formula of distrib.

Parameters:

Name	Type	Description	Default
`formula`	`str`	`lognormal(mu, sigma[, lower, upper])` (mu and sigma of the natural logarithm), `normal(mean, sd[, lower, upper])` or `uniform(lower, upper)`, with numbers as arguments (the grammar of `pkpdsim.distrib`).	required

Returns:

Type	Description
`Distribution`	The distribution, truncated if the formula has bounds.

Raises:

Type	Description
`ValueError`	for another formula.

parameter_distributions ¶

parameter_distributions(sbml_path)

Get the distributions of the parameters of a model.

Every parameter with a distrib uncertainty which states a distribution (an uncert parameter of the type distribution) has one.

Parameters:

Name	Type	Description	Default
`sbml_path`	`Path`	the SBML model, the flat model a simulation runs.	required

Returns:

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

Raises:

Type	Description
`ValueError`	if a distribution is not supported, see `distribution_from_formula`, or a parameter states two.

uncertainty_dimension ¶

uncertainty_dimension(sbml_path, draws, seed)

Draw the parameters of a model which have a distribution.

Parameters:

Name	Type	Description	Default
`sbml_path`	`Path`	the SBML model.	required
`draws`	`int`	the number of draws.	required
`seed`	`int`	the seed of the Latin hypercube.	required

Returns:

Type	Description
`Dimension`	The dimension `uncertainty` of the draws.

Raises:

Type	Description
`ValueError`	if no parameter of the model has a distribution.

apply_uncertainty ¶

apply_uncertainty(experiment, run)

Run an initialized experiment over the draws of the fitted parameters.

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_fit_parameters ¶

check_fit_parameters(model)

Check that the model has the fitted values and the uncertainty of its adopted fits.

Every parameter of an adopted fit must be a parameter of every build of the model (model_paths, the flat models) with the value of the fit and a distribution of its draws. The draws are those of the male build (UncertaintyRun.create) and run on every build, so the distribution of a parameter in another build is the one of the male build.

Parameters:

Name	Type	Description	Default
`model`	`PKPDModel`	the model.	required

Returns:

Type	Description
`list[str]`	The problems, one line each; empty for a model without adopted fits.

uncertainty¶

UncertaintyMethod ¶

ParameterUncertainty dataclass ¶

sigma ¶

interval ¶

standard_error_model ¶

distribution ¶

notes ¶

uncertainty ¶

FitRecord dataclass ¶

fit_id property ¶

load classmethod ¶

FitRecords ¶

parameter ¶

UncertaintySettings dataclass ¶

UncertaintyRun dataclass ¶

quantiles property ¶

id property ¶

create classmethod ¶

adopt_fit ¶

convert_value ¶

distribution_from_formula ¶

parameter_distributions ¶

uncertainty_dimension ¶

apply_uncertainty ¶

check_fit_parameters ¶

ParameterUncertainty `dataclass` ¶

FitRecord `dataclass` ¶

fit_id `property` ¶

load `classmethod` ¶

UncertaintySettings `dataclass` ¶

UncertaintyRun `dataclass` ¶

quantiles `property` ¶

id `property` ¶

create `classmethod` ¶