credibility.uncertainty¶

The parameter uncertainty of the decisive predictions (VV&UQ step 4).

The adopted fits estimate their parameters with an uncertainty, the profile likelihood interval or the standard error of the Fisher information of their record (sbmlsim.fit.records.AdoptedRecord). A context of use whose acceptance is met at the adopted parameters only may fail for parameters which the data fit equally well; the propagation of the parameter uncertainty to the decisive predictions shows how robust the acceptance is and how precise the predictions of the quantities of interest are.

The draws of a fit (parameter_draws) have the marginals the releases draw (ParameterUncertainty.distribution) and the correlation of the Fisher information of the fit, in the space of the fit, as the correlation of the normal scores of a Gaussian copula (sbmlsim.uncertainty.draws.draw): for a normal or log-normal marginal in the scale of the fit this is the multivariate normal of the Fisher covariance, with the widths of the profile. A Fisher information which is not of full rank, or none, gives independent draws. The fits are drawn independently, and the parameters a fit fixes from another adopted fit stay at their adopted values.

propagate_fits evaluates every adopted fit at its draws with the report of the fresh evaluation (FitTable.reports); the assessment reads the predictions per draw (FitPropagation) and records per context of use the prediction bands of the decisive points, their coverage of the observations and the probability that every acceptance rule is met, decided with the anytime-valid statements of sbmlsim.uncertainty.testing (UncertaintyRecord, uncertainty_record_from_dict reads the one of a record of pkpdsim 0.19 as well).

The names differ from the ones of pkpdsim, which clashed with the propagation of sbmlsim.uncertainty and the settings of the draws of the experiments (sbmlsim.experiment.draws.UncertaintySettings): propagate_fits was propagate, FitPropagation was Propagation and PropagationSettings was UncertaintySettings.

PropagationSettings `dataclass` ¶

PropagationSettings(
    *,
    draws=128,
    seed=1234,
    quantiles=(0.05, 0.95),
    threshold=0.9,
    level=0.95,
)

The settings of the propagation of the parameter uncertainty.

Attributes:

Name	Type	Description
`draws`	`int`	the number of draws of every fit, a power of two keeps the balance of the Sobol points; 128 decide a rule met on every draw at the threshold 0.9 for up to about ten rules of a context.
`seed`	`int`	the seed of the draws.
`quantiles`	`tuple[float, float]`	the quantiles of the prediction bands.
`threshold`	`float`	the probability of the statement that a rule is met.
`level`	`float`	the level of the decisions of the rules of a context of use, together (Bonferroni over its rules).

FitDraws `dataclass` ¶

FitDraws(fit_id, pids, values, units, correlated, note)

The draws of the fitted parameters of an adopted fit.

Attributes:

Name	Type	Description
`fit_id`	`str`	the id of the fit.
`pids`	`tuple[str, ...]`	the fitted parameters, in the order of the columns of `values`.
`values`	`ndarray`	one row per draw, in the units of the model.
`units`	`Mapping[str, str \| None]`	the unit of every parameter of the model, `None` if unknown.
`correlated`	`bool`	whether the draws have the correlation of the Fisher information.
`note`	`str`	where the dependence comes from, or why there is none.

subset `property` ¶

subset

The subset of the fit.

FitPropagation `dataclass` ¶

FitPropagation(settings, draws, predictions, failed)

The decisive predictions at the draws of the parameters of the fits.

Attributes:

Name	Type	Description
`settings`	`PropagationSettings`	the settings of the propagation.
`draws`	`Mapping[str, FitDraws]`	the draws of every fit, by its subset.
`predictions`	`DataFrame`	one column per draw, the rows of the table of the fits; `NaN` for a draw which failed and for a fit without draws.
`failed`	`Mapping[str, int]`	the failed draws of every fit, by its subset.

FitUncertainty ¶

Bases: TypedDict

The draws of a fit of the decisive points of a context of use.

Attributes:

Name	Type	Description
`fit`	`str`	the subset of the fit.
`fit_id`	`str`	the id of the fit.
`n_parameters`	`int`	the fitted parameters which are drawn.
`correlated`	`bool`	whether the draws have the Fisher correlation.
`note`	`str`	where the dependence comes from, or why there is none.
`n_failed`	`int`	the draws whose evaluation failed.

RuleProbability ¶

Bases: TypedDict

The probability that an acceptance rule is met over the parameter draws.

Attributes:

Name	Type	Description
`name`	`str`	the rule.
`limit`	`str`	its limit.
`estimate`	`float \| None`	the fraction of the draws on which it is met, `None` if it is evaluable on none.
`low`	`float \| None`	the lower end of the anytime-valid confidence sequence.
`high`	`float \| None`	the upper end.
`n`	`int`	the draws on which the rule is evaluable.
`n_failed`	`int`	the draws on which it is not (a failed evaluation).
`decision`	`str`	`accepted`, `rejected`, `equivalent`, `undecided` of the statement `P(met) >= threshold`, or `not_evaluable`.
`n_needed`	`int \| None`	the draws an undecided statement needs at its estimate.

QuantityBand ¶

Bases: TypedDict

The prediction band of a quantity of interest over the parameter draws.

Attributes:

Name	Type	Description
`quantity`	`str`	the quantity of interest.
`n_points`	`int`	its evaluable decisive points with a band.
`band_fold`	`float \| None`	the median of `upper / lower` of the bands of its points, the precision of its predictions; `None` without a point.
`coverage`	`float \| None`	the share of its points whose observation is inside the band.

SensitivityIndex ¶

Bases: TypedDict

The first-order sensitivity index of a target to a fitted parameter.

Attributes:

Name	Type	Description
`target`	`str`	a quantity of interest or an acceptance rule.
`kind`	`str`	`quantity` or `rule`.
`fit`	`str`	the subset of the fit of the parameter.
`parameter`	`str`	the fitted parameter.
`index`	`float \| None`	the share of the variance of the target over the draws which the parameter explains alone, given data (Plischke 2013), `None` without variance or with fewer than 8 draws.

UncertaintyRecord ¶

Bases: TypedDict

The parameter uncertainty of the decisive predictions of a context of use.

Attributes:

Name	Type	Description
`n_draws`	`int`	the draws of every fit.
`seed`	`int`	the seed.
`quantiles`	`list[float]`	the quantiles of the bands.
`threshold`	`float`	the probability of the statements of the rules.
`level`	`float`	the level of the decisions of the rules together.
`fits`	`list[FitUncertainty]`	the draws of the fits of the decisive points.
`n_points`	`int`	the evaluable decisive points with a band.
`coverage`	`float \| None`	the share of them whose observation is inside the band.
`quantities`	`list[QuantityBand]`	the bands of the quantities which are no ratio.
`rules`	`list[RuleProbability]`	the probability of every acceptance rule, the ratio rule last.
`sensitivity`	`list[SensitivityIndex]`	the first-order indices of every quantity (the mean log ratio of its predictions to the reference predictions) and of the value of every rule to every fitted parameter of the draws.

parameter_draws ¶

parameter_draws(fit_id, parameters, fisher, settings)

Draw the fitted parameters of an adopted fit, see the module.

Parameters:

Name	Type	Description	Default
`fit_id`	`str`	the id of the fit.	required
`parameters`	`Sequence[ParameterUncertainty]`	the uncertainty of every fitted parameter.	required
`fisher`	`FisherInformation \| None`	the Fisher information of the fit, `None` without.	required
`settings`	`PropagationSettings`	the number of draws and the seed.	required

Returns:

Type	Description
`FitDraws`	The draws.

propagate_fits ¶

propagate_fits(project, fits, settings)

Evaluate the adopted fits of a project at the draws of their parameters.

Parameters:

Name	Type	Description	Default
`project`	`Project`	the project with its adopted fits.	required
`fits`	`FitTable`	the fresh evaluation of the fits with their reports, see `sbmlsim.credibility.records.evaluate_fits`.	required
`settings`	`PropagationSettings`	the settings of the propagation.	required

Returns:

Type	Description
`FitPropagation`	The predictions per draw.

Raises:

Type	Description
`ValueError`	if the points of a draw are not the reference points.

sensitivity_indices ¶

sensitivity_indices(target, kind, y, draws)

Get the first-order indices of a target over the draws of the parameters.

The indices are estimated from the draws of the propagation, without further simulations (sbmlsim.uncertainty.statistics.first_order_given_data); the index of a parameter correlated with another includes the effect of the other, so the indices of correlated parameters do not add up.

Parameters:

Name	Type	Description	Default
`target`	`str`	the quantity or the rule.	required
`kind`	`str`	`quantity` or `rule`.	required
`y`	`ndarray`	the value of the target on every draw, `NaN` for a failed draw.	required
`draws`	`Mapping[str, FitDraws]`	the draws of the fits of the target, by subset; the draw `k` of every fit belongs to the value `k`.	required

Returns:

Type	Description
`list[SensitivityIndex]`	One index per parameter of the fits, in their order.

rule_probability ¶

rule_probability(name, limit, met, settings, m)

Get the probability that a rule is met from its results on the draws.

Parameters:

Name	Type	Description	Default
`name`	`str`	the rule.	required
`limit`	`str`	its limit.	required
`met`	`Sequence[bool \| None]`	whether the rule is met on every draw, `None` where it is not evaluable.	required
`settings`	`PropagationSettings`	the threshold and the level.	required
`m`	`int`	the number of rules decided together, for the level of Bonferroni.	required

Returns:

Type	Description
`RuleProbability`	The probability with the decision of `P(met) >= threshold`.

uncertainty_record_from_dict ¶

uncertainty_record_from_dict(data)

Get the uncertainty record of a context of use from plain data.

The record of pkpdsim 0.19 is read as well; a record of pkpdsim 0.18 or earlier has none, and a record without the sensitivity has none.

Parameters:

Name	Type	Description	Default
`data`	`Mapping[str, Any] \| None`	the record, `None` for none.	required

Returns:

Type	Description
`UncertaintyRecord \| None`	The record, `None` without.

credibility.uncertainty¶

PropagationSettings dataclass ¶

FitDraws dataclass ¶

subset property ¶

FitPropagation dataclass ¶

FitUncertainty ¶

RuleProbability ¶

QuantityBand ¶

SensitivityIndex ¶

UncertaintyRecord ¶

parameter_draws ¶

propagate_fits ¶

sensitivity_indices ¶

rule_probability ¶

uncertainty_record_from_dict ¶

PropagationSettings `dataclass` ¶

FitDraws `dataclass` ¶

subset `property` ¶

FitPropagation `dataclass` ¶