credibility.variability¶

The variability between the subjects: the visual predictive check of the decisive points.

The adopted fits predict every curve with the typical subject of its study group. A model declares how its subjects differ (Credibility.variability, a sbmlsim.fit.variability.Variability: a relative distribution per target, e.g. LogNormal(cv=0.3) of a clearance or of the body weight), and predictive_checks evaluates every adopted fit for VariabilitySettings.subjects subjects around the inputs of every study group (sbmlsim.fit.variability.predictive_check): a data point of a group of N subjects is compared with the means of virtual groups of N subjects, a point of an individual with the subjects. With the propagation of the parameter uncertainty (sbmlsim.credibility.uncertainty) the subjects are nested in the draws of the parameters of the fit; without it they vary around the adopted parameters.

Per context of use, variability_record gives the coverage of the evaluable decisive observations by their bands (VariabilityRecord) with its Wilson interval and whether the expected coverage, the probability between the quantiles of the bands, lies in it (consistent), below it (wide: the bands are wider than the data scatter) or above it (narrow: the declared variability, with the parameter uncertainty, does not explain the scatter of the data, or the typical predictions are biased). The verdict does not change. variability_record_from_dict reads the record of pkpdsim 0.19 as well.

VariabilitySettings `dataclass` ¶

VariabilitySettings(
    subjects=64,
    studies=16,
    groups=1000,
    seed=1234,
    quantiles=(0.05, 0.95),
    level=0.95,
)

The settings of the predictive checks.

Attributes:

Name	Type	Description
`subjects`	`int`	the subjects of every study of a parameter vector of a fit.
`studies`	`int`	the studies of every parameter vector of a variability between the studies (`Variability.between`), else one.
`groups`	`int`	the virtual groups of a data point of a group per study.
`seed`	`int`	the seed of the subjects and the groups.
`quantiles`	`tuple[float, float]`	the quantiles of the bands.
`level`	`float`	the level of the Wilson interval of the coverage.

VpcPoint ¶

Bases: TypedDict

A data point of an adopted fit with the band of its predictive check.

Attributes:

Name	Type	Description
`fit`	`str`	the subset of the fit.
`experiment`	`str`	the experiment.
`mapping`	`str`	the key of the mapping.
`x`	`float \| None`	the x of the point, `None` for a value per simulation.
`DV`	`float`	the observation.
`N`	`int`	the subjects of the observation, 1 for an individual.
`statistic`	`str`	`individual`, `mean` or `gmean`.
`PRED`	`float`	the prediction of the typical subject.
`low`	`float \| None`	the low quantile of the band.
`median`	`float \| None`	the median of the band.
`high`	`float \| None`	the high quantile of the band.
`inside`	`bool \| None`	the observation within the band, `None` without a band.

QuantityCoverage ¶

Bases: TypedDict

The coverage of the observations of a quantity of interest.

Attributes:

Name	Type	Description
`quantity`	`str`	the quantity.
`n_points`	`int`	its evaluable decisive points with a band.
`coverage`	`float \| None`	the share inside their band, `None` without a point.

VariabilityRecord ¶

Bases: TypedDict

The predictive check of the decisive points of a context of use.

Attributes:

Name	Type	Description
`subjects`	`int`	the subjects of every study of a parameter vector.
`studies`	`int`	the studies of every parameter vector, 1 without a variability between the studies.
`vectors`	`int`	the parameter vectors of the fits, the draws of the uncertainty or 1 for the adopted parameters.
`groups`	`int`	the virtual groups of a data point of a group.
`seed`	`int`	the seed.
`targets`	`dict[str, str]`	the target of every factor and its distribution.
`between`	`dict[str, str]`	the target of every factor between the studies and its distribution, empty without.
`quantiles`	`list[float]`	the quantiles of the bands.
`expected`	`float`	the probability between them, the coverage of a model whose variability is the one of the data.
`n_points`	`int`	the evaluable decisive points with a band.
`n_groups`	`int`	those of a group of more than one subject.
`coverage`	`float \| None`	the share of them inside their band, `None` without one.
`low`	`float \| None`	the low end of the Wilson interval of the coverage.
`high`	`float \| None`	the high end.
`level`	`float`	the level of the interval.
`agreement`	`str \| None`	`consistent` (the expected coverage in the interval), `narrow` (above it: the bands miss the data) or `wide` (below it), `None` without a point.
`quantities`	`list[QuantityCoverage]`	the coverage of every quantity of interest which is no ratio.
`failed`	`int`	the subjects whose simulation failed, over the fits.

PredictiveChecks `dataclass` ¶

PredictiveChecks(
    settings, variability, points, vectors, studies, failed
)

The predictive checks of the adopted fits of a model.

Attributes:

Name	Type	Description
`settings`	`VariabilitySettings`	the settings.
`variability`	`Variability`	the declared variability.
`points`	`DataFrame`	the band of every row of the table of the fits, indexed as it, with the columns of `VPC_COLUMNS` but `fit`, `experiment`, `mapping`, `x` and `DV`; no row for a fit without a check.
`vectors`	`Mapping[str, int]`	the parameter vectors of every fit, by its subset.
`studies`	`Mapping[str, int]`	the studies of every parameter vector of every fit, by its subset.
`failed`	`Mapping[str, int]`	the failed subjects of every fit, by its subset.

predictive_checks ¶

predictive_checks(
    project, fits, variability, settings, propagation=None
)

Get the predictive check of every adopted fit of a project.

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
`variability`	`Variability`	the variability of the subjects.	required
`settings`	`VariabilitySettings`	the settings.	required
`propagation`	`FitPropagation \| None`	the draws of the parameters of the fits, see `sbmlsim.credibility.uncertainty.propagate_fits`; the subjects vary around the adopted parameters without.	`None`

Returns:

Type	Description
`PredictiveChecks`	The bands of the points of the fits.

Raises:

Type	Description
`ValueError`	if a target of the variability cannot be scaled in a simulation of a fit, or the points of a check are not the points of the fit.

variability_record ¶

variability_record(checks, decisive, evaluable, quantities)

Get the predictive check of the decisive points of a context of use.

Parameters:

Name	Type	Description	Default
`checks`	`PredictiveChecks`	the predictive checks of the fits.	required
`decisive`	`DataFrame`	the decisive points of the context, indexed as the table of the fits.	required
`evaluable`	`Index`	the index of the evaluable decisive points.	required
`quantities`	`Sequence[QuantityOfInterest]`	the quantities of interest of the context.	required

Returns:

Type	Description
`VariabilityRecord`	The coverage of the evaluable decisive points with a band.

variability_statement ¶

variability_statement(record)

Get the statement of the predictive check of a context of use.

Parameters:

Name	Type	Description	Default
`record`	`VariabilityRecord`	the predictive check of the context.	required

Returns:

Type	Description
`str`	The statement: the variability, the subjects and the coverage with its
`str`	interval and agreement.

variability_record_from_dict ¶

variability_record_from_dict(data)

Get the predictive check 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.

Parameters:

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

Returns:

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

credibility.variability¶

VariabilitySettings dataclass ¶

VpcPoint ¶

QuantityCoverage ¶

VariabilityRecord ¶

PredictiveChecks dataclass ¶

predictive_checks ¶

variability_record ¶

variability_statement ¶

variability_record_from_dict ¶

VariabilitySettings `dataclass` ¶

PredictiveChecks `dataclass` ¶