credibility¶

The credibility of a model for its contexts of use.

A model declares what it is used for (ContextOfUse), how risky a wrong answer is, which evidence supports it and when it is accepted (Credibility). The evidence is selected from the data points of the adopted fits (evaluate_fits, mapping_table) with the kinds their records store (select, check_declaration). The assessment (assess, CredibilityAssessment) gives every context of use its metrics, acceptance, domain coverage, verdict and the factors of V&V 40 (FACTORS) as plain data, written as JSON. The verification (verify) evaluates the fits again with tightened tolerances and a second integration method and checks the builds, for the factors of the verification, and runs the battery of the checks of the builds (run_battery): mass balance, non-negativity, zero dose, steady state, superposition, a second simulator, plausibility and rebuild. The temporal validation (chronology) splits the decisive points by whether the model collected their study after the fit, and the provenance of the study data (study_data) names the collection every study with points was written by. The parameter uncertainty of the adopted fits is propagated to the decisive predictions (propagate, UncertaintySettings), the probability that the acceptance is met over the draws of the parameters. The simulated inputs of the mappings, the covariates of the subjects and the doses, are checked against the reported ones of their studies (input_checks), the equivalency of the inputs, and the decisive points with the declared variability of the subjects (predictive_checks, VariabilitySettings), the visual predictive check.

AcceptanceRecord ¶

Bases: TypedDict

The result of an acceptance rule as plain data, see AcceptanceResult.

ContextResult `dataclass` ¶

ContextResult(
    *,
    id,
    title,
    question,
    level,
    influence,
    consequence,
    risk,
    rationale,
    extrapolation,
    domain_statement,
    quantities,
    acceptance,
    verdict,
    factors,
    n_decisive,
    n_evaluable,
    minimum_points,
    verification=list(),
    ratios=list(),
    ratio_acceptance=None,
    temporal=None,
    uncertainty=None,
    inputs=None,
    variability=None,
)

The assessment of a context of use.

Attributes:

Name	Type	Description
`id`	`str`	the id of the context.
`title`	`str`	the title.
`question`	`str`	the question.
`level`	`CouLevel`	the level on the ladder.
`influence`	`Level`	the influence of the model on the decision.
`consequence`	`Level`	the consequence of a wrong decision.
`risk`	`Level`	the model risk.
`rationale`	`str`	why this level, influence and consequence.
`extrapolation`	`str`	the argument for a domain without validation evidence.
`domain_statement`	`str`	what the domain claims beyond the metadata.
`quantities`	`list[QuantityRecord]`	the quantities of interest (`id`, `description`, `ratio`, `coverage`, `n_points`, see `QuantityRecord`).
`acceptance`	`list[AcceptanceRecord]`	the results of the acceptance rules (`name`, `value`, `limit`, `met`, see `AcceptanceResult`).
`verdict`	`Verdict`	the verdict.
`factors`	`list[FactorRecord]`	the factors of V&V 40 (`id`, `name`, `status`, `statement`, `step`), in the order of `FACTORS`.
`n_decisive`	`int`	the points of the decisive evidence, each row once.
`n_evaluable`	`int`	the decisive points which are applicable, see `applicable`.
`minimum_points`	`int`	the evaluable points the verdict needs, see `ContextOfUse.minimum_points`; 0 in a record of pkpdsim 0.17.
`verification`	`list[CheckRecord]`	the checks of the verification of the decisive predictions, in the order of `Check`; empty if the assessment was not verified.
`ratios`	`list[RatioRecord]`	the pairs of the arms of the assessed ratio quantities, see `pkpdsim.credibility.ratios`; empty without one and in a record of pkpdsim 0.18 or earlier.
`ratio_acceptance`	`AcceptanceRecord \| None`	the result of the rule of the ratio pairs (`ContextOfUse.ratio_rule`), `None` without an assessed ratio.
`temporal`	`TemporalRecord \| None`	the decisive points of the studies the model collected after their fit, see `pkpdsim.credibility.temporal`; `None` for a context decided on calibration data, an assessment without the chronology of the model and a record of pkpdsim 0.18 or earlier.
`uncertainty`	`UncertaintyRecord \| None`	the parameter uncertainty of the decisive predictions, see `pkpdsim.credibility.uncertainty`; `None` for an assessment without the propagation and a record of pkpdsim 0.18 or earlier.
`inputs`	`InputsRecord \| None`	the equivalency of the inputs of the decisive mappings, see `pkpdsim.credibility.inputs`; `None` for an assessment without the checks of the inputs and a record of pkpdsim 0.18 or earlier.
`variability`	`VariabilityRecord \| None`	the predictive check of the decisive points with the declared variability of the subjects, see `pkpdsim.credibility.variability`; `None` without it and in a record of pkpdsim 0.18 or earlier.

verified `property` ¶

verified

Get whether every check passed, None if not verified.

decisive_role `property` ¶

decisive_role

Get the role of the evidence which decides, see CouLevel.decisive_role.

uncovered_quantities `property` ¶

uncovered_quantities

Get the ids of the quantities of interest which are uncovered.

to_dict ¶

to_dict()

Get the result as plain data, NaN as None.

from_dict `classmethod` ¶

from_dict(data)

Get the result from plain data, None as NaN.

A record of pkpdsim 0.17 has no minimum of points, read as 0, and no coverage of the quantities, read as None with 0 points; a record of 0.18 or earlier has no ratio pairs, no temporal record, no uncertainty, no equivalency of the inputs and no predictive check.

Coverage ¶

Bases: StrEnum

The coverage of a claimed value of the domain of a context of use.

CoverageEntry `dataclass` ¶

CoverageEntry(
    *, context, field, value, coverage, claimed, n_points
)

The coverage of a value of a field of the metadata by a context of use.

Attributes:

Name	Type	Description
`context`	`str`	the id of the context of use.
`field`	`str`	the field of the metadata, e.g. `health`.
`value`	`str`	the name of the value, e.g. `RENAL_IMPAIRMENT`.
`coverage`	`Coverage \| None`	the coverage of a claimed value, `None` for a value outside the claimed domain.
`claimed`	`bool`	whether the domain claims the value; the values of the points of the evidence outside the claim are not claimed.
`n_points`	`int`	the points with the value: the applicable points of the validation evidence for a validated value, of the calibration evidence for a calibrated one, every point of the evidence for a value outside the claim.

to_dict ¶

to_dict()

Get the entry as plain data.

from_dict `classmethod` ¶

from_dict(data)

Get the entry from plain data.

CredibilityAssessment `dataclass` ¶

CredibilityAssessment(
    *,
    provenance,
    contexts,
    evidence,
    coverage,
    limitations,
    unclaimed,
    notes,
    verification=None,
    cross_validations=list(),
    studies=list(),
    inputs=list(),
    vpc=list(),
)

The assessment of the contexts of use of a model.

Attributes:

Name	Type	Description
`provenance`	`Provenance`	what the assessment was computed from.
`contexts`	`list[ContextResult]`	the result of every context of use, in the declared order.
`evidence`	`list[EvidenceResult]`	the metrics of every evidence of every context.
`coverage`	`list[CoverageEntry]`	the coverage of the domain of every context.
`limitations`	`list[EvidenceResult]`	the metrics of the limitations, of the model (context `""`) and of the contexts; they enter no acceptance.
`unclaimed`	`list[UnclaimedRecord]`	the validation points which no evidence and no limitation selects, per fit and mapping (`fit`, `experiment`, `mapping`, `n`).
`notes`	`str`	the notes of the declaration.
`verification`	`VerificationSummary \| None`	what the verification compared, `None` if the assessment was not verified.
`cross_validations`	`list[CrossValidation]`	the leave-one-study-out cross-validations of the adopted fits, see `pkpdsim.credibility.cross_validation`; empty without one and in a record of pkpdsim 0.18 or earlier.
`studies`	`list[StudyData]`	the provenance of the data of every study with points in the adopted fits, see `pkpdsim.credibility.studies`; empty in a record of pkpdsim 0.18 or earlier.
`inputs`	`list[InputCheck]`	the checks of the simulated inputs of every mapping of the adopted fits against the reported ones, see `pkpdsim.credibility.inputs`; empty without and in a record of pkpdsim 0.18 or earlier.
`vpc`	`list[VpcPoint]`	every data point of the adopted fits with the band of its predictive check, see `pkpdsim.credibility.variability`; empty without the check and in a record of pkpdsim 0.18 or earlier.

to_dict ¶

to_dict()

Get the assessment as plain data, NaN as None.

from_dict `classmethod` ¶

from_dict(data)

Get the assessment from plain data, None as NaN.

to_json ¶

to_json(path)

Write the assessment as JSON.

Parameters:

Name	Type	Description	Default
`path`	`Path`	the file.	required

from_json `classmethod` ¶

from_json(path)

Read an assessment written with to_json.

Parameters:

Name	Type	Description	Default
`path`	`Path`	the file.	required

Returns:

Type	Description
`CredibilityAssessment`	The assessment.

EvidenceResult `dataclass` ¶

EvidenceResult(
    *,
    context,
    name,
    role,
    description,
    selection,
    n_points,
    n_mappings,
    n_studies,
    outliers_dropped,
    limitation_subtracted,
    metrics,
)

The metrics of an evidence of a context of use or of a limitation.

Attributes:

Name	Type	Description
`context`	`str`	the id of the context of use, `""` for a limitation of the model.
`name`	`str`	the name of the evidence.
`role`	`EvidenceRole`	the role of the evidence.
`description`	`str`	what the evidence is.
`selection`	`str`	what the evidence selects, see `describe_selection`.
`n_points`	`int`	the data points.
`n_mappings`	`int`	the fit mappings, by experiment and key.
`n_studies`	`int`	the studies, the experiments of the mappings.
`outliers_dropped`	`int`	the outlier points a validation dropped.
`limitation_subtracted`	`int`	the limitation points subtracted.
`metrics`	`dict[str, float]`	`criteria_metrics` and the values of the acceptance rules of the context, `NaN` if not evaluable.

to_dict ¶

to_dict()

Get the result as plain data, NaN as None.

from_dict `classmethod` ¶

from_dict(data)

Get the result from plain data, None as NaN.

Provenance `dataclass` ¶

Provenance(
    *,
    model,
    title,
    fits,
    versions,
    commit,
    dirty,
    date,
    lock=None,
)

What an assessment was computed from.

Attributes:

Name	Type	Description
`model`	`str`	the name of the model.
`title`	`str`	the title of the model.
`fits`	`list[str]`	the ids of the adopted fits.
`versions`	`dict[str, str]`	the versions of the packages, see `VERSIONED_PACKAGES`.
`commit`	`str \| None`	the commit of the repository of the model, `None` outside one.
`dirty`	`bool \| None`	whether the repository has changes, `None` outside one.
`date`	`str`	the date of the assessment, ISO 8601 with the time zone.
`lock`	`str \| None`	whether the evidence matched the lock of the declaration (`matched`), the lock was written with the assessment (`written`), or `None` without a lock, see `pkpdsim.credibility.lock`.

to_dict ¶

to_dict()

Get the provenance as plain data.

from_dict `classmethod` ¶

from_dict(data)

Get the provenance from plain data.

QuantityRecord ¶

Bases: TypedDict

A quantity of interest as plain data, see QuantityOfInterest.

Attributes:

Name	Type	Description
`id`	`str`	the id of the quantity.
`description`	`str`	what the quantity is.
`ratio`	`bool`	whether the quantity is a ratio between arms.
`coverage`	`str \| None`	`covered` with an applicable decisive point of the quantity inside the claimed domain, an assessed ratio with an evaluable pair whose numerator lies inside it, else `uncovered`; `None` for a ratio without a pairing and in a record of pkpdsim 0.17, which did not assess it.
`n_points`	`int`	the applicable decisive points of the quantity inside the claimed domain, the evaluable pairs of an assessed ratio, 0 for a ratio without a pairing.

UnclaimedRecord ¶

Bases: TypedDict

The unclaimed validation points of a fit mapping.

Attributes:

Name	Type	Description
`fit`	`str`	the subset of the fit.
`experiment`	`str`	the experiment.
`mapping`	`str`	the key of the mapping.
`n`	`int`	the points.

Verdict ¶

Bases: StrEnum

The verdict of the assessment of a context of use.

label `property` ¶

label

Get the verdict in words, e.g. supported with extrapolation.

Battery `dataclass` ¶

Battery(*, results, fates, settings)

The results of the battery of a model.

Attributes:

Name	Type	Description
`results`	`tuple[BatteryResult, ...]`	the result of every check of `BATTERY_CHECKS`, in its order.
`fates`	`tuple[Fate, ...]`	the fate of every dose of every build, see `Fate`.
`settings`	`str`	the settings of the simulations in words.

failed `property` ¶

failed

Get the checks which failed.

result ¶

result(check)

Get the result of a check.

Raises:

Type	Description
`KeyError`	if the battery has no result of the check.

to_dict ¶

to_dict()

Get the battery as plain data.

from_dict `classmethod` ¶

from_dict(data)

Get the battery from plain data.

BatteryResult `dataclass` ¶

BatteryResult(
    *,
    check,
    status,
    cases,
    largest,
    at,
    problems,
    statement,
)

The result of a check of the battery over the builds of a model.

Attributes:

Name	Type	Description
`check`	`Check`	the check.
`status`	`BatteryStatus`	whether it passed, failed or was not applicable.
`cases`	`int`	what was checked, e.g. the doses of the mass balance over the builds or the species of the non-negativity.
`largest`	`float`	the largest relative deviation of the check, `NaN` for a check without one.
`at`	`str`	where the largest deviation is, e.g. `male IVDOSE_tor: Aurine_tor`.
`problems`	`tuple[str, ...]`	what failed, a line each.
`statement`	`str`	what was checked in words, the reason for a check which is not applicable.

passed `property` ¶

passed

Get whether the check passed, None if it was not applicable.

to_dict ¶

to_dict()

Get the result as plain data, NaN as None.

from_dict `classmethod` ¶

from_dict(data)

Get the result from plain data, None as NaN.

BatteryStatus ¶

Bases: StrEnum

The result of a check of the battery.

Fate `dataclass` ¶

Fate(*, build, dose, substance, amount, parts, imbalance)

Where a dose went at the end of the horizon, the mass balance of a route.

The parts are the differences to the simulation without a dose, so the fate of a dose of an endogenous substance is that of the dose and not of its production.

Attributes:

Name	Type	Description
`build`	`str`	the build, e.g. `male`.
`dose`	`str`	the dose state or infusion rate, e.g. `IVDOSE_tor`.
`substance`	`str`	the dosed substance.
`amount`	`float`	the dose (mmole).
`parts`	`Mapping[str, float]`	the parts of the dose (mmole) by name: `body` (the species which are no sink), `urine` and `feces` (the sinks), `dose` (not yet applied) and a reaction which does not read a dose by its id (negative for an elimination, positive for a production).
`imbalance`	`float`	the imbalance of the dose simulation relative to the largest term of its balance.

to_dict ¶

to_dict()

Get the fate as plain data.

from_dict `classmethod` ¶

from_dict(data)

Get the fate from plain data.

Acceptance `dataclass` ¶

Acceptance(criterion, minimum)

The percentage of the points a criterion accepts is at least minimum.

Attributes:

Name	Type	Description
`criterion`	`Criterion`	the criterion, e.g. `Fold(2.0)`.
`minimum`	`float`	the minimum percentage (0 to 100).

name `property` ¶

name

Get the name of the criterion.

limit `property` ¶

limit

Get the limit, e.g. >= 80.

evaluate ¶

evaluate(points)

Evaluate the percentage of the points the criterion accepts.

AcceptanceResult `dataclass` ¶

AcceptanceResult(name, value, limit, met)

The result of an acceptance rule.

Attributes:

Name	Type	Description
`name`	`str`	the name of the rule.
`value`	`float`	the value of the rule on the points, `NaN` if not evaluable.
`limit`	`str`	the limit, e.g. `>= 80`.
`met`	`bool \| None`	whether the rule is met, `None` if the value is `NaN`.

AcceptanceRule ¶

Bases: Protocol

A rule on the data points of the evidence of a context of use.

name `property` ¶

name

Get the name of the rule.

limit `property` ¶

limit

Get the limit of the rule, e.g. >= 80.

evaluate ¶

evaluate(points)

Evaluate the rule on the data points (DV, IPRED, DV_SD).

AfeRange `dataclass` ¶

AfeRange(low, high)

The average fold error, the bias, is inside the range.

Attributes:

Name	Type	Description
`low`	`float`	the smallest accepted AFE.
`high`	`float`	the largest accepted AFE.

name `property` ¶

name

Get the name of the rule.

limit `property` ¶

limit

Get the limit, e.g. 0.8 to 1.25.

evaluate ¶

evaluate(points)

Evaluate the AFE of the points, the bounds included.

ContextOfUse `dataclass` ¶

ContextOfUse(
    *,
    id,
    title,
    question,
    level,
    influence,
    consequence,
    quantities,
    domain,
    evidence,
    acceptance=(),
    limitations=(),
    rationale="",
    extrapolation="",
    min_points=None,
    ratio_acceptance=None,
)

What a model is used for: the question, the domain, the evidence and the acceptance.

Attributes:

Name	Type	Description
`id`	`str`	the slug of the context, unique in the model.
`title`	`str`	the title.
`question`	`str`	the question of the context, one sentence.
`level`	`CouLevel`	the level on the ladder.
`influence`	`Level`	the influence of the model on the decision.
`consequence`	`Level`	the consequence of a wrong decision.
`quantities`	`tuple[QuantityOfInterest, ...]`	the quantities asked for, at least one which is no ratio.
`domain`	`Domain`	the domain claimed, at least one value of the metadata above C1.
`evidence`	`tuple[Evidence, ...]`	the evidence.
`acceptance`	`tuple[AcceptanceRule, ...]`	the rules, empty for the default of the risk.
`limitations`	`tuple[Evidence, ...]`	the evidence of what the model does not describe.
`rationale`	`str`	why this level, influence and consequence.
`extrapolation`	`str`	the argument for a domain without validation evidence.
`min_points`	`int \| None`	the evaluable decisive points the verdict needs, at least 1; `None` for the default of the risk, see `minimum_points`.
`ratio_acceptance`	`GuestAcceptance \| None`	the rule of the pairs of the assessed ratio quantities, `None` for the default of the risk, see `ratio_rule`.

risk `property` ¶

risk

Get the model risk of the influence and the consequence.

rules `property` ¶

rules

Get the acceptance rules: the declared ones or the default of the risk.

ratio_rule `property` ¶

ratio_rule

Get the rule of the ratio pairs: the declared or the default of the risk.

ratios `property` ¶

ratios

Get the assessed ratio quantities, those with a Ratio.

minimum_points `property` ¶

minimum_points

Get the evaluable points the verdict needs: the declared or the default of the risk.

decisive_role `property` ¶

decisive_role

Get the role of the evidence which decides, see CouLevel.decisive_role.

problems ¶

problems()

Get the problems of the context of use, each naming the context.

CouLevel ¶

Bases: StrEnum

The level of a context of use on the ladder from describing to predicting.

label `property` ¶

label

Get the name of the level, e.g. interpolate.

decisive_role `property` ¶

decisive_role

Get the role of the evidence which decides: calibration for C1, else validation.

Credibility `dataclass` ¶

Credibility(
    *,
    contexts,
    limitations=(),
    notes="",
    covariates=DEFAULT_COVARIATES,
    variability=None,
)

The contexts of use of a model.

Attributes:

Name	Type	Description
`contexts`	`tuple[ContextOfUse, ...]`	the contexts of use.
`limitations`	`tuple[Evidence, ...]`	the model limitations, evidence of what it does not describe.
`notes`	`str`	notes on the declaration.
`covariates`	`Mapping[str, str]`	the covariates of the subjects whose simulated values the equivalency of the inputs checks against the reported ones, the target of the model and the measurement type of PK-DB of its reported value (`DEFAULT_COVARIATES`, the body weight and the height), see `pkpdsim.credibility.inputs`; a model whose targets have other ids or which simulates further covariates declares them.
`variability`	`Variability \| None`	the variability between the subjects, relative distributions of targets (`sbmlsim.fit.variability.Variability`), the input of the predictive check of the decisive points, see `pkpdsim.credibility.variability`; `None` for a model which declares none.

Raises:

Type	Description
`DeclarationError`	with every problem of the declaration.

context ¶

context(id)

Get a context of use by its id.

Parameters:

Name	Type	Description	Default
`id`	`str`	the id of the context.	required

Returns:

Type	Description
`ContextOfUse`	The context.

Raises:

Type	Description
`KeyError`	if there is no such context.

DeclarationError ¶

DeclarationError(problems)

Bases: ValueError

The declaration of the credibility of a model is invalid.

Attributes:

Name	Type	Description
`problems`		every problem of the declaration.

Create the error.

Parameters:

Name	Type	Description	Default
`problems`	`list[str]`	every problem of the declaration.	required

Domain `dataclass` ¶

Domain(*, metadata=dict(), statement='')

The domain a context of use claims.

Attributes:

Name	Type	Description
`metadata`	`Mapping[str, Collection[StrEnum]]`	the claimed values by field of `PKPDMappingMetaData`.
`statement`	`str`	what is claimed beyond the metadata, e.g. the dose range.

problems ¶

problems()

Get the problems of the domain: an unknown field or a value of another vocabulary.

Evidence `dataclass` ¶

Evidence(
    name, role, selection, description="", *, fit=None
)

A selection of the data with a role.

Attributes:

Name	Type	Description
`name`	`str`	the name of the evidence.
`role`	`EvidenceRole`	what the evidence is used for.
`selection`	`Selection`	the fit mappings it selects.
`description`	`str`	what the evidence is.
`fit`	`str \| None`	the subset of the adopted fits it is taken from, `None` for all.

EvidenceRole ¶

Bases: StrEnum

What evidence is used for.

GuestAcceptance `dataclass` ¶

GuestAcceptance(minimum, delta=GUEST_DELTA)

The percentage of the ratio pairs within the limits of Guest et al. is at least minimum.

Attributes:

Name	Type	Description
`minimum`	`float`	the minimum percentage (0 to 100).
`delta`	`float`	the accepted variability at a ratio of 1, see `pkpdsim.credibility.ratios.guest_limit`.

name `property` ¶

name

Get the name of the rule.

limit `property` ¶

limit

Get the limit, e.g. >= 80.

evaluate ¶

evaluate(pairs)

Evaluate the percentage of the evaluable pairs within the limits.

Parameters:

Name	Type	Description	Default
`pairs`	`Collection[bool \| None]`	whether every pair is within, `None` for one which is not evaluable.	required

Returns:

Type	Description
`AcceptanceResult`	The result, not evaluable without an evaluable pair.

problems ¶

problems()

Get the problems of the rule: a minimum outside 0 to 100, a delta not above 1.

Level ¶

Bases: StrEnum

A level of influence, consequence or risk.

MaxGmfe `dataclass` ¶

MaxGmfe(maximum)

The geometric mean fold error is at most maximum.

Attributes:

Name	Type	Description
`maximum`	`float`	the largest accepted GMFE.

name `property` ¶

name

Get the name of the rule.

limit `property` ¶

limit

Get the limit, e.g. <= 1.5.

evaluate ¶

evaluate(points)

Evaluate the GMFE of the points.

QuantityOfInterest `dataclass` ¶

QuantityOfInterest(id, description, *, ratio=False)

A quantity a context of use is asked for.

Attributes:

Name	Type	Description
`id`	`str`	the observable of the fit mappings, e.g. `Cve_hctz` or `pk.cmax`; for a ratio its name, it is matched against no observable.
`description`	`str`	what the quantity is.
`ratio`	`bool \| Ratio`	whether the quantity is a ratio between arms: `True` is declared and recorded, not assessed; a `Ratio` pairs the arms and is assessed with the limits of Guest et al., its observable restricts the evidence like the id of an absolute quantity.

pairing `property` ¶

pairing

Get the pairing of an assessed ratio, None otherwise.

Ratio `dataclass` ¶

Ratio(*, observable, numerator, denominator, summary=AUC)

The arms of a ratio quantity: a numerator over its reference in a study.

See pkpdsim.credibility.ratios: per fit and study (the experiment) every decisive mapping of the observable which numerator selects is paired with the one which denominator selects, and the ratio of their summaries is compared for the data and the predictions.

Attributes:

Name	Type	Description
`observable`	`str`	the observable of the arms, e.g. `Carm_hctz`; compared without the brackets of a concentration.
`numerator`	`MappingFilter`	selects the mappings of the arms, e.g. the renal impairment.
`denominator`	`MappingFilter`	selects the mapping of the reference arm, e.g. healthy.
`summary`	`Summary`	how the points of an arm are summarized.

Summary ¶

Bases: StrEnum

How the points of an arm of a ratio are summarized, see Ratio.

Unclaimed `dataclass` ¶

Unclaimed(within=None)

The validation points which no other evidence and no limitation selects.

Attributes:

Name	Type	Description
`within`	`MappingFilter \| None`	restricts the points to the ones this filter selects.

Factor `dataclass` ¶

Factor(*, id, name, status, statement, step=None)

A credibility factor of V&V 40.

Attributes:

Name	Type	Description
`id`	`str`	the id of the factor.
`name`	`str`	the name of the factor in V&V 40.
`status`	`FactorStatus`	how the factor is assessed.
`statement`	`str`	what the factor assesses, or the platform statement.
`step`	`int \| None`	the step of the credibility work which will assess a factor which is not assessed, `None` otherwise.

to_dict ¶

to_dict()

Get the factor as plain data.

FactorRecord ¶

Bases: TypedDict

A factor as plain data, see Factor.

FactorStatus ¶

Bases: StrEnum

How a credibility factor is assessed.

InputCheck ¶

Bases: TypedDict

The check of a simulated input of a mapping against the reported one.

Attributes:

Name	Type	Description
`fit`	`str`	the subset of the fit.
`experiment`	`str`	the experiment, the study.
`mapping`	`str`	the key of the mapping.
`target`	`str`	the target of the model.
`kind`	`str`	`covariate` or `dose`.
`measurement`	`str`	the measurement type of the reported value (`weight`, `height`, ..., `dosing`).
`unit`	`str`	the unit of the target in the model, of every value.
`simulated`	`float`	the simulated value.
`source`	`str`	`simulation` (set by the simulation) or `model` (the value of the model).
`reported`	`float \| None`	the reported central value (mean, median, geometric mean, the value of an individual, the dose) the simulated one is compared with, `None` without.
`low`	`float \| None`	the low end of the reported range, `None` without.
`high`	`float \| None`	the high end of the reported range, `None` without.
`reported_by`	`list[str]`	the groups, individuals or interventions of the reported value.
`status`	`str`	the result, see `InputStatus`.
`ratio`	`float \| None`	the simulated over the reported central value, `None` without.

InputsRecord ¶

Bases: TypedDict

The equivalency of the inputs of the decisive mappings of a context.

Attributes:

Name	Type	Description
`n_mappings`	`int`	the decisive mappings.
`n_checked`	`int`	the decisive mappings with at least one input checked.
`inputs`	`list[InputSummary]`	the summary of every input, sorted by kind and target.
`differs`	`list[InputCheck]`	the checks which differ.

InputStatus ¶

Bases: StrEnum

How a simulated input compares with the reported one.

LockMismatchError ¶

LockMismatchError(problems)

Bases: ValueError

The evidence selects other mappings than the lock of the declaration.

Attributes:

Name	Type	Description
`problems`		every evidence which differs, with its added and removed mappings.

Create the error.

Parameters:

Name	Type	Description	Default
`problems`	`list[str]`	every evidence which differs.	required

RatioRecord ¶

Bases: TypedDict

A pair of arms of a ratio quantity.

Attributes:

Name	Type	Description
`quantity`	`str`	the id of the ratio quantity.
`fit`	`str`	the subset of the fit of the points.
`experiment`	`str`	the experiment, the study of the arms.
`numerator`	`str`	the key of the mapping of the numerator.
`denominator`	`str`	the key of the mapping of the denominator.
`observed`	`float`	the ratio of the summaries of the data, `NaN` if one is not evaluable.
`predicted`	`float`	the ratio of the summaries of the predictions.
`limit`	`float`	the limit of Guest et al. for the observed ratio.
`within`	`bool \| None`	whether the predicted ratio lies within the limits, `None` if the pair is not evaluable.
`metadata`	`dict[str, str]`	the values of the fields of the domain of the numerator (`DOMAIN_FIELDS`, by name), e.g. `{"health": "RENAL_IMPAIRMENT"}`, which the qualification across models groups by.

FitTable `dataclass` ¶

FitTable(
    *,
    table,
    lookup,
    recorded_kinds,
    reports=(lambda: MappingProxyType({}))(),
)

The data points of the adopted fits of a model.

Attributes:

Name	Type	Description
`table`	`DataFrame`	one row per data point (`evaluate_fits`) or per mapping (`mapping_table`), with the columns `fit` (the subset of the fit), `experiment`, `mapping`, `kind`, `observable` and the fields of the metadata of the mappings; the data points have the columns of `sbmlsim.fit.metrics.FitMetrics.datapoints_df` as well.
`lookup`	`MappingLookup`	the fit mapping of an experiment and a key.
`recorded_kinds`	`Kinds`	the kinds the records of the adopted fits store, by the subset of the fit, the experiment and the key of the mapping.
`reports`	`Mapping[str, FitReport]`	the reports the data points were evaluated with, by the subset of the fit (`evaluate_fits`), which the verification evaluates again with other settings; none for `mapping_table`.

KindMismatchError ¶

KindMismatchError(problems)

Bases: ValueError

The kinds of the fit mappings differ from the kinds the adopted fits recorded.

Attributes:

Name	Type	Description
`problems`		every mapping whose kind differs.

Create the error.

Parameters:

Name	Type	Description	Default
`problems`	`list[str]`	every mapping whose kind differs.	required

EvidenceSelection `dataclass` ¶

EvidenceSelection(
    *,
    context,
    evidence,
    rows,
    outliers_dropped,
    limitation_subtracted,
)

The data points of an evidence of a context of use.

Attributes:

Name	Type	Description
`context`	`str`	the id of the context of use.
`evidence`	`Evidence`	the evidence.
`rows`	`Index`	the selected rows of the table of the fits (`FitTable.table`).
`outliers_dropped`	`int`	the points of kind outlier which a validation selected and dropped.
`limitation_subtracted`	`int`	the limitation points the evidence selected and which were subtracted.

SelectionError ¶

SelectionError(problems)

Bases: ValueError

The evidence of a declaration selects invalid data.

Attributes:

Name	Type	Description
`problems`		every problem of the selection.

Create the error.

Parameters:

Name	Type	Description	Default
`problems`	`list[str]`	every problem of the selection.	required

Selections `dataclass` ¶

Selections(
    *,
    evidence,
    limitations,
    unclaimed,
    limitation_evidence=(),
)

The data points of the evidence of every context of use of a model.

Attributes:

Name	Type	Description
`evidence`	`tuple[EvidenceSelection, ...]`	the selection of every evidence, in the order of the contexts and their evidence.
`limitations`	`Index`	the rows of the limitations of the model and of every context.
`unclaimed`	`DataFrame`	the validation points of no evidence and no limitation, with the columns `fit`, `experiment`, `mapping` and `n` (the points).
`limitation_evidence`	`tuple[EvidenceSelection, ...]`	the selection of every limitation, the ones of the model first, with the context `""`, then the ones of the contexts.

StudyData ¶

Bases: TypedDict

The data of a study the adopted fits of a model have points of.

Attributes:

Name	Type	Description
`study`	`str`	the study (the experiment).
`folder`	`str \| None`	the folder of the study relative to the folder of the model, `None` if no data path of the model has it.
`fits`	`list[str]`	the subsets of the fits with points of the study.
`n_points`	`int`	the data points of the study in the fits, a point of two fits twice.
`recorded`	`bool`	whether the folder has a record of its collection.
`collected`	`str \| None`	the day of the first collection, ISO format.
`dating`	`str \| None`	how the day of the first collection is known.
`updated`	`str \| None`	the day of the latest collection, ISO format.
`released`	`str \| None`	the day PK-DB released the study, ISO format.
`pkdb_id`	`str \| None`	the identifier of the release in PK-DB.
`source_digest`	`str \| None`	the digest of the source files in PK-DB.
`pkdb_data_commit`	`str \| None`	the commit of pkdb_data of the latest collection.
`pkdb_data_dirty`	`bool \| None`	whether the study folder of that checkout had changes.
`n_tables`	`int`	the tables of the record.
`changed`	`list[str] \| None`	the tables which differ from the record (`-` removed, `+` added), `None` without the digests of the tables.

Chronology `dataclass` ¶

Chronology(fits, studies)

When the adopted fits of a model ran and when it collected its studies.

Attributes:

Name	Type	Description
`fits`	`Mapping[str, date]`	the day of every adopted fit, by its subset.
`studies`	`Mapping[str, StudyRecord]`	the record of every study of the data of the model, by study.

collected ¶

collected(study)

Get the day the model collected a study, None if not known.

new ¶

new(points)

Get which points are of a study collected after the day of their fit.

Parameters:

Name	Type	Description	Default
`points`	`DataFrame`	data points with the columns `fit` and `experiment`.	required

Returns:

Type	Description
`Series`	True for a point whose study the model collected after the day of
`Series`	its fit; False for a point without a day of collection or fit.

TemporalRecord ¶

Bases: TypedDict

The decisive points of a context of use which are new for their fit.

Attributes:

Name	Type	Description
`studies`	`list[TemporalStudy]`	the new studies, by study and fit.
`n_points`	`int`	the decisive points of the new studies.
`n_evaluable`	`int`	those the fold criteria can evaluate.
`acceptance`	`list[AcceptanceRecord]`	the acceptance rules of the context on the new points.
`n_known`	`int`	the decisive studies which the model collected no later than the day of their fit.
`undated`	`list[str]`	the decisive studies without a day of collection.

TemporalStudy ¶

Bases: TypedDict

A study a model collected after the fit of its decisive points.

Attributes:

Name	Type	Description
`study`	`str`	the study (the experiment).
`fit`	`str`	the subset of the fit.
`fit_date`	`str`	the day the fit ran, ISO format.
`collected`	`str`	the day the model collected the study, ISO format.
`released`	`str \| None`	the day PK-DB released the study, `None` if not released.
`pkdb_id`	`str \| None`	the identifier of the release in PK-DB.
`n_points`	`int`	the decisive points of the study of this fit.
`n_evaluable`	`int`	those the fold criteria can evaluate.

Propagation `dataclass` ¶

Propagation(settings, draws, predictions, failed)

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

Attributes:

Name	Type	Description
`settings`	`UncertaintySettings`	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.

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.

UncertaintySettings `dataclass` ¶

UncertaintySettings(
    *,
    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).

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.

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.

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.

Check ¶

Bases: StrEnum

A check of the verification and the factor of V&V 40 it assesses.

The checks of the predictions (tolerances, integrator, setup) compare the decisive predictions of a context of use; the checks of the battery (pkpdsim.credibility.battery) check the builds of the model, for every context of use alike.

label `property` ¶

label

Get the check in words, e.g. second integration method.

factor `property` ¶

factor

Get the id of the factor of V&V 40 the check assesses.

CheckRecord ¶

Bases: TypedDict

The result of a check for a context of use.

A check of the battery (pkpdsim.credibility.battery) is a check of the builds of the model, the same for every context.

Attributes:

Name	Type	Description
`check`	`str`	the check, see `Check`.
`factor`	`str`	the id of the factor of V&V 40 the check assesses.
`n_points`	`int`	the decisive points compared, the cases of a check of the battery.
`max_difference`	`float`	the largest relative difference of a decisive prediction, `NaN` for the setup and without a point; the largest deviation of a check of the battery.
`at`	`str`	the point of the largest difference, `experiment.mapping at x`, empty without one; the case of the largest deviation of a check of the battery.
`acceptance_changed`	`bool \| None`	whether a rule of the acceptance is met with the alternative predictions and not with the reference or the other way, `None` for the setup and the battery.
`passed`	`bool`	whether the check passed.
`problems`	`list[str]`	what failed beyond the numbers, e.g. a failed evaluation or an issue of a build.

Verification `dataclass` ¶

Verification(*, predictions, failures, summary)

The alternative predictions and the problems an assessment is verified with.

Attributes:

Name	Type	Description
`predictions`	`Mapping[Check, Series]`	the predictions of every numerical check (`tolerances`, `integrator`) per row of the table of the fits, `NaN` where the evaluation of a fit failed.
`failures`	`Mapping[Check, Mapping[str, str]]`	the failed evaluations of every numerical check, the message by the subset of the fit.
`summary`	`VerificationSummary`	what was compared, see `VerificationSummary`.

problems `property` ¶

problems

Get the issues of the builds of the model.

VerificationSummary `dataclass` ¶

VerificationSummary(
    *,
    tightening,
    limit,
    scale_floor,
    fits,
    problems,
    battery=None,
)

What the verification of an assessment compared, as plain data.

Attributes:

Name	Type	Description
`tightening`	`float`	the factor the tolerances were divided by.
`limit`	`float`	the largest relative difference a check accepts.
`scale_floor`	`float`	the floor of a relative difference, of the largest reference prediction of the mapping.
`fits`	`list[FitSettingsRecord]`	the settings of every adopted fit and of its alternatives.
`problems`	`list[str]`	the issues of the builds of the model, see `build_problems`.
`battery`	`Battery \| None`	the checks of the builds of the model, see `pkpdsim.credibility.battery`, `None` if it did not run.

to_dict ¶

to_dict()

Get the summary as plain data.

from_dict `classmethod` ¶

from_dict(data)

Get the summary from plain data.

assess ¶

assess(
    model,
    source_commit=None,
    *,
    verification=True,
    lock=False,
    uncertainty=None,
    variability=None,
)

Assess the contexts of use of a model on its adopted fits.

The fits are evaluated fresh on the current model and data, see evaluate_fits, and, with verification, again with the alternatives of the checks of pkpdsim.credibility.verification; the cross-validations of the adopted fits, the chronology of the model and its studies (pkpdsim.credibility.temporal) and the provenance of the study data (pkpdsim.credibility.studies) are read, and the simulated inputs of the mappings are checked against the reported ones (pkpdsim.credibility.inputs).

Parameters:

Name	Type	Description	Default
`model`	`PKPDModel`	the model with a declaration and adopted fits.	required
`source_commit`	`str \| None`	the commit of the source repository of a release, see `provenance`.	`None`
`verification`	`bool`	verify the decisive predictions; the factors of the verification are not assessed without.	`True`
`lock`	`bool`	write the lock of the evidence (`pkpdsim.credibility.lock`) instead of comparing the evidence with it.	`False`
`uncertainty`	`UncertaintySettings \| None`	propagate the parameter uncertainty of the adopted fits to the decisive predictions with these settings, see `pkpdsim.credibility.uncertainty`; the factor model inputs is not assessed without.	`None`
`variability`	`VariabilitySettings \| None`	check the decisive points with the declared variability of the subjects (`Credibility.variability`) with these settings, nested in the draws of the parameters with `uncertainty`, see `pkpdsim.credibility.variability`.	`None`

Returns:

Type	Description
`CredibilityAssessment`	The assessment.

Raises:

Type	Description
`ValueError`	if the model has no declaration or no adopted fits, or the settings of the variability are given for a declaration without a variability.
`KindMismatchError`	if a kind differs from the recorded one.
`SelectionError`	if the evidence selects invalid data.
`LockMismatchError`	if the evidence differs from the lock.

assess_table ¶

assess_table(
    credibility,
    fits,
    provenance,
    verification=None,
    cross_validations=(),
    chronology=None,
    studies=(),
    propagation=None,
    inputs=None,
    variability=None,
)

Assess the contexts of use of a declaration on the data points of the fits.

Parameters:

Name	Type	Description	Default
`credibility`	`Credibility`	the declaration.	required
`fits`	`FitTable`	the data points of the adopted fits with `DV`, `IPRED` and `DV_SD`, see `evaluate_fits`.	required
`provenance`	`Provenance`	what the table was computed from.	required
`verification`	`Verification \| None`	the alternative predictions of the table and the issues of the builds, see `pkpdsim.credibility.verification.verify`; the assessment is not verified without.	`None`
`cross_validations`	`Sequence[CrossValidation]`	the cross-validations of the adopted fits, which assess the factor model form.	`()`
`chronology`	`Chronology \| None`	when the adopted fits ran and the model collected its studies, see `pkpdsim.credibility.temporal`; no context has a temporal record without.	`None`
`studies`	`Sequence[StudyData]`	the provenance of the study data of the points, see `pkpdsim.credibility.studies.study_data`, recorded as it is.	`()`
`propagation`	`Propagation \| None`	the predictions at the draws of the parameters of the fits, see `pkpdsim.credibility.uncertainty.propagate`; no context has an uncertainty record without.	`None`
`inputs`	`Sequence[InputCheck] \| None`	the checks of the simulated inputs of the mappings against the reported ones, see `pkpdsim.credibility.inputs.input_checks`; no context has a record of the equivalency of its inputs without.	`None`
`variability`	`PredictiveChecks \| None`	the predictive checks of the fits with the declared variability, see `pkpdsim.credibility.variability`; no context has a predictive check without.	`None`

Returns:

Type	Description
`CredibilityAssessment`	The assessment.

Raises:

Type	Description
`SelectionError`	if the evidence selects invalid data, see `select`.

describe_selection ¶

describe_selection(selection)

Describe what a selection of an evidence selects.

Parameters:

Name	Type	Description	Default
`selection`	`Selection`	the selection.	required

Returns:

Type	Description
`str`	The mapping keys by study for a `NamedFilter`, e.g.
`str`	`CredA: fm_dose; CredB: fm_dose, fm_zero`; the clauses of a
`str`	`MetadataFilter`, e.g. `route in [IV, PO] and health not in [HEALTHY]`;
`str`	`unclaimed validation data` for `Unclaimed`, followed by `within` and
`str`	the description of its filter; the qualified name otherwise.

run_battery ¶

run_battery(model, *, rebuild=True, cross_simulator=True)

Run the battery of the checks of a model on its builds.

The checks of the simulations need a substance with a molecular weight, Mr_<s>, the convention of the PBPK models; they are not applicable to a model without.

Parameters:

Name	Type	Description	Default
`model`	`PKPDModel`	the model, every build of `model_paths`.	required
`rebuild`	`bool`	run the check `rebuild`, which runs the factory.	`True`
`cross_simulator`	`bool`	run the check `cross_simulator` when AMICI is installed, which compiles every build.	`True`

Returns:

Type	Description
`Battery`	The results of the checks and the fates of the doses.

check_declaration ¶

check_declaration(model)

Check the credibility declaration of a model against its adopted fits.

The declaration must be valid, the kinds of the mappings of the current selection of the fit definitions must be the recorded kinds of the adopted fits, and the evidence must select valid data (see select), all from the fit definitions and the records, without a simulation, and select the mappings of its lock, if the model has one. A problem of the records, e.g. a record without the kinds of its mappings, two kinds of one mapping, no adopted fits or a subset adopted twice, is a problem as well, after which the kinds and the evidence are not checked.

Parameters:

Name	Type	Description	Default
`model`	`PKPDModel`	the model with a declaration and adopted fits.	required

Returns:

Type	Description
`list[str]`	Every problem, empty if the declaration holds.

Raises:

Type	Description
`ValueError`	if the model has no declaration.

input_checks ¶

input_checks(model, fits, covariates)

Check the simulated inputs of every mapping of the adopted fits.

Parameters:

Name	Type	Description	Default
`model`	`PKPDModel`	the model, the folders of its studies hold the reported values.	required
`fits`	`FitTable`	the evaluated adopted fits with their reports, see `pkpdsim.credibility.records.evaluate_fits`.	required
`covariates`	`Mapping[str, str]`	the target of every covariate and the measurement type of its reported value, see `Credibility.covariates`.	required

Returns:

Type	Description
`list[InputCheck]`	The checks of every mapping of the points, in the order of the fits and
`list[InputCheck]`	their mappings.

lock_differences ¶

lock_differences(model, selections, fits)

Get every evidence whose mappings differ from the lock of the model.

Parameters:

Name	Type	Description	Default
`model`	`PKPDModel`	the model.	required
`selections`	`Selections`	the current selection of its declaration.	required
`fits`	`FitTable`	the table of the fits the selection was made on.	required

Returns:

Type	Description
`list[str] \| None`	A line per evidence which is new, gone or selects other mappings, with
`list[str] \| None`	the added (`+`) and removed (`-`) mappings; empty if the selection
`list[str] \| None`	matches the lock, `None` if the model has no lock.

write_lock ¶

write_lock(model, selections, fits)

Write the lock of the evidence of a model.

Parameters:

Name	Type	Description	Default
`model`	`PKPDModel`	the model.	required
`selections`	`Selections`	the selection of its declaration.	required
`fits`	`FitTable`	the table of the fits the selection was made on.	required

Returns:

Type	Description
`Path`	The file of the lock.

guest_limit ¶

guest_limit(observed, delta=GUEST_DELTA)

Get the limit of Guest et al. (2011) of an observed ratio.

Parameters:

Name	Type	Description	Default
`observed`	`float`	the observed ratio, positive.	required
`delta`	`float`	the accepted variability at a ratio of 1.	`GUEST_DELTA`

Returns:

Type	Description
`float`	The limit, `NaN` for a ratio which is not positive and finite.

ratio_pairs ¶

ratio_pairs(
    quantity, ratio, points, lookup, delta=GUEST_DELTA
)

Get the pairs of the arms of a ratio quantity in the decisive points.

Parameters:

Name	Type	Description	Default
`quantity`	`str`	the id of the ratio quantity.	required
`ratio`	`Ratio`	its pairing.	required
`points`	`DataFrame`	the decisive points of the context of use with `fit`, `experiment`, `mapping`, `observable`, `DV`, `IPRED` and `x`.	required
`lookup`	`MappingLookup`	the fit mapping of an experiment and a key, which the filters of the numerator and the denominator read.	required
`delta`	`float`	the accepted variability of the limit at a ratio of 1.	`GUEST_DELTA`

Returns:

Type	Description
`list[RatioRecord]`	The pairs, in the order of the points, and the problems of
`list[str]`	`pairings`.

evaluate_fits ¶

evaluate_fits(model)

Evaluate the adopted fits of a model into the table of their data points.

Every fit is evaluated fresh on the current model and data with the settings it ran with (sbmlsim.fit.cli.report_from_records), at the reference parameter set of its record; the kinds of its mappings must be the recorded ones.

Parameters:

Name	Type	Description	Default
`model`	`PKPDModel`	the model, its `fits` are evaluated.	required

Returns:

Type	Description
`FitTable`	The data points of every fit with the column `fit`, the subset, and the
`FitTable`	report of every fit.

Raises:

Type	Description
`ValueError`	if the model has no adopted fits, see `_adopted_fits`.
`FileNotFoundError`	if a record has no parameters or no kinds.
`KindMismatchError`	if a kind differs from the recorded one.

kind_differences ¶

kind_differences(table, recorded)

Compare the kinds of the mappings of a table with the recorded kinds.

Parameters:

Name	Type	Description	Default
`table`	`DataFrame`	a table of the fits with the columns `fit`, `experiment`, `mapping` and `kind`, see `FitTable`.	required
`recorded`	`Kinds`	the recorded kinds, see `recorded_kinds`.	required

Returns:

Type	Description
`list[str]`	One message per mapping whose kind differs from the recorded one, or
`list[str]`	which only the table or only the record has; empty if the kinds agree.

mapping_table ¶

mapping_table(model)

Get the mappings of the adopted fits of a model without a simulation.

The kinds are the ones of the current selection of every fit definition; the excluded mappings, which a fit does not evaluate, are no rows. The recorded kinds are compared by the caller, see kind_differences.

Parameters:

Name	Type	Description	Default
`model`	`PKPDModel`	the model, its `fits` are listed.	required

Returns:

Type	Description
`FitTable`	One row per fit and mapping with the columns of `KEY_COLUMNS` and the
`FitTable`	fields of the metadata.

Raises:

Type	Description
`ValueError`	if the model has no adopted fits, see `_adopted_fits`.
`FileNotFoundError`	if a record has no parameters or no kinds.

recorded_kinds ¶

recorded_kinds(record, fit)

Get the kinds of the mappings which the record of an adopted fit stores.

Parameters:

Name	Type	Description	Default
`record`	`Path`	the directory of the record of the adopted fit.	required
`fit`	`str`	the subset of the fit, the first item of every key.	required

Returns:

Type	Description
`dict[tuple[str, str, str], str]`	The kind by the subset, the experiment and the key of the mapping.

Raises:

Type	Description
`FileNotFoundError`	if the record has no metrics of its mappings.
`ValueError`	if the metrics lack the experiment, the mapping or the kind, or store two kinds of one mapping.

default_acceptance ¶

default_acceptance(risk)

Get the acceptance a context of use of a risk takes without its own.

Parameters:

Name	Type	Description	Default
`risk`	`Level`	the model risk.	required

Returns:

Type	Description
`tuple[AcceptanceRule, ...]`	The rules, all of which must be met.

model_risk ¶

model_risk(influence, consequence)

Get the model risk of an influence and a consequence.

Parameters:

Name	Type	Description	Default
`influence`	`Level`	the influence of the model on the decision.	required
`consequence`	`Level`	the consequence of a wrong decision.	required

Returns:

Type	Description
`Level`	The model risk.

normalize_observable ¶

normalize_observable(observable)

Get an observable without the brackets of a concentration.

Parameters:

Name	Type	Description	Default
`observable`	`str`	the observable, e.g. `[A]`, `A` or `pk.cmax`.	required

Returns:

Type	Description
`str`	The observable, e.g. `A` for `[A]`.

select ¶

select(credibility, fits)

Select the data points of the evidence of every context of use.

A mapping (its experiment and key) which is training data of any adopted fit counts as fitted in every fit: a validation which selects its points, in any fit, is an error which names the fits it is training data of, and neither Unclaimed nor the unclaimed validation points take them. Two Unclaimed of different contexts may take the same points. See the module for the other rules.

Parameters:

Name	Type	Description	Default
`credibility`	`Credibility`	the declaration.	required
`fits`	`FitTable`	the table of the adopted fits, see `evaluate_fits` and `mapping_table`.	required

Returns:

Type	Description
`Selections`	The points of every evidence, the limitation points and the unclaimed
`Selections`	validation points.

Raises:

Type	Description
`SelectionError`	with every problem of the selection.

study_data ¶

study_data(model, points)

Get the provenance of the studies the data points are of.

Parameters:

Name	Type	Description	Default
`model`	`PKPDModel`	the model.	required
`points`	`DataFrame`	the data points of the adopted fits, with the columns `fit` and `experiment`, see `pkpdsim.credibility.records.evaluate_fits`.	required

Returns:

Type	Description
`list[StudyData]`	A record per study of the points, sorted by study.

Raises:

Type	Description
`ValueError`	if a record is not readable, see `pkpdsim.data.read_study_record`.

chronology ¶

chronology(model)

Get when the adopted fits of a model ran and when it collected its studies.

Parameters:

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

Returns:

Type	Description
`Chronology`	The days of the adopted fits of `model.fits` and the records of the
`Chronology`	study folders of every data path of the model.

Raises:

Type	Description
`ValueError`	if a record is not readable, see `pkpdsim.data.read_study_record`.

propagate ¶

propagate(model, fits, settings)

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

Parameters:

Name	Type	Description	Default
`model`	`PKPDModel`	the model with its adopted fits.	required
`fits`	`FitTable`	the fresh evaluation of the fits with their reports, see `pkpdsim.credibility.records.evaluate_fits`.	required
`settings`	`UncertaintySettings`	the settings of the propagation.	required

Returns:

Type	Description
`Propagation`	The predictions per draw.

Raises:

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

predictive_checks ¶

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

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

Parameters:

Name	Type	Description	Default
`model`	`PKPDModel`	the model with its adopted fits.	required
`fits`	`FitTable`	the fresh evaluation of the fits with their reports, see `pkpdsim.credibility.records.evaluate_fits`.	required
`variability`	`Variability`	the variability of the subjects.	required
`settings`	`VariabilitySettings`	the settings.	required
`propagation`	`Propagation \| None`	the draws of the parameters of the fits, see `pkpdsim.credibility.uncertainty.propagate`; 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.

verify ¶

verify(model, fits, tightening=TIGHTENING, *, battery=True)

Evaluate the adopted fits of a model with the alternatives of the checks.

Parameters:

Name	Type	Description	Default
`model`	`PKPDModel`	the model, whose builds are checked.	required
`fits`	`FitTable`	the data points of the adopted fits with their reports, see `pkpdsim.credibility.records.evaluate_fits`.	required
`tightening`	`float`	the factor the tolerances are divided by.	`TIGHTENING`
`battery`	`bool`	run the battery of the checks of the builds, see `pkpdsim.credibility.battery.run_battery`.	`True`

Returns:

Type	Description
`Verification`	The alternative predictions, the issues of the builds and the battery.

Raises:

Type	Description
`ValueError`	if the table of the fits has no reports.

credibility¶

AcceptanceRecord ¶

ContextResult dataclass ¶

verified property ¶

decisive_role property ¶

uncovered_quantities property ¶

to_dict ¶

from_dict classmethod ¶

Coverage ¶

CoverageEntry dataclass ¶

to_dict ¶

from_dict classmethod ¶

CredibilityAssessment dataclass ¶

to_dict ¶

from_dict classmethod ¶

to_json ¶

from_json classmethod ¶

EvidenceResult dataclass ¶

to_dict ¶

from_dict classmethod ¶

Provenance dataclass ¶

to_dict ¶

from_dict classmethod ¶

QuantityRecord ¶

UnclaimedRecord ¶

Verdict ¶

label property ¶

Battery dataclass ¶

failed property ¶

result ¶

to_dict ¶

from_dict classmethod ¶

BatteryResult dataclass ¶

passed property ¶

to_dict ¶

from_dict classmethod ¶

BatteryStatus ¶

Fate dataclass ¶

to_dict ¶

from_dict classmethod ¶

Acceptance dataclass ¶

name property ¶

limit property ¶

evaluate ¶

AcceptanceResult dataclass ¶

AcceptanceRule ¶

name property ¶

limit property ¶

evaluate ¶

AfeRange dataclass ¶

name property ¶

limit property ¶

evaluate ¶

ContextOfUse dataclass ¶

risk property ¶

rules property ¶

ratio_rule property ¶

ratios property ¶

minimum_points property ¶

decisive_role property ¶

problems ¶

CouLevel ¶

label property ¶

decisive_role property ¶

Credibility dataclass ¶

context ¶

DeclarationError ¶

Domain dataclass ¶

problems ¶

Evidence dataclass ¶

EvidenceRole ¶

GuestAcceptance dataclass ¶

name property ¶

limit property ¶

evaluate ¶

problems ¶

Level ¶

MaxGmfe dataclass ¶

name property ¶

limit property ¶

ContextResult `dataclass` ¶

verified `property` ¶

decisive_role `property` ¶

uncovered_quantities `property` ¶

from_dict `classmethod` ¶

CoverageEntry `dataclass` ¶

from_dict `classmethod` ¶

CredibilityAssessment `dataclass` ¶

from_dict `classmethod` ¶

from_json `classmethod` ¶

EvidenceResult `dataclass` ¶

from_dict `classmethod` ¶

Provenance `dataclass` ¶

from_dict `classmethod` ¶

label `property` ¶

Battery `dataclass` ¶

failed `property` ¶

from_dict `classmethod` ¶

BatteryResult `dataclass` ¶

passed `property` ¶

from_dict `classmethod` ¶

Fate `dataclass` ¶

from_dict `classmethod` ¶

Acceptance `dataclass` ¶

name `property` ¶

limit `property` ¶

AcceptanceResult `dataclass` ¶

name `property` ¶

limit `property` ¶

AfeRange `dataclass` ¶

name `property` ¶

limit `property` ¶

ContextOfUse `dataclass` ¶

risk `property` ¶

rules `property` ¶

ratio_rule `property` ¶

ratios `property` ¶

minimum_points `property` ¶

decisive_role `property` ¶

label `property` ¶

decisive_role `property` ¶

Credibility `dataclass` ¶

Domain `dataclass` ¶

Evidence `dataclass` ¶

GuestAcceptance `dataclass` ¶

name `property` ¶

limit `property` ¶

MaxGmfe `dataclass` ¶

name `property` ¶

limit `property` ¶

QuantityOfInterest `dataclass` ¶

pairing `property` ¶

Ratio `dataclass` ¶

Unclaimed `dataclass` ¶

Factor `dataclass` ¶

FitTable `dataclass` ¶

EvidenceSelection `dataclass` ¶

Selections `dataclass` ¶

Chronology `dataclass` ¶

Propagation `dataclass` ¶

UncertaintySettings `dataclass` ¶

PredictiveChecks `dataclass` ¶

VariabilitySettings `dataclass` ¶

label `property` ¶

factor `property` ¶

Verification `dataclass` ¶

problems `property` ¶

VerificationSummary `dataclass` ¶

from_dict `classmethod` ¶