credibility.declaration¶

The declaration of the contexts of use of a model.

A Credibility lists the ContextOfUses of a model. A context of use asks a question of the model, names the quantities and the domain it is asked for, the evidence (a selection of the fit mappings with a role) and, optionally, the rules by which it is accepted. A context of use does not raise: it reports problems(), and Credibility raises one DeclarationError with the problems of every context.

The domain of a context claims values of the fields of the metadata of the fit mappings, a dataclass derived from sbmlsim.fit.objects.MappingMetaData whose fields are enums, e.g. the route of a dose. The metadata and the fields a domain can claim belong to the project (metadata_fields, sbmlsim.project.CredibilitySettings), so the declaration is checked against them when the project loads it (Credibility.domain_problems, sbmlsim.project.Project.load_credibility).

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.

Level ¶

Bases: StrEnum

A level of influence, consequence or risk.

EvidenceRole ¶

Bases: StrEnum

What evidence is used for.

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

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.

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` or `pk.cmax`; for a ratio its name, it is matched against no observable.
`description`	`str`	what the quantity is.
`ratio`	`bool \| Pairing`	whether the quantity is a ratio between arms: `True` is declared and recorded, not assessed; a `Pairing` derives the ratio from the decisive points and is assessed by the evidence extension which knows it (`sbmlsim.credibility.extensions`), its observable restricts the evidence like the id of an absolute quantity.

pairing `property` ¶

pairing

Get the pairing of an assessed ratio, None otherwise.

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 the metadata of the fit mappings, see `metadata_fields`.
`statement`	`str`	what is claimed beyond the metadata, e.g. the dose range.

problems ¶

problems(fields)

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

Parameters:

Name	Type	Description	Default
`fields`	`Mapping[str, type[StrEnum]]`	the fields a domain can claim with their enum, see `metadata_fields`.	required

Returns:

Type	Description
`list[str]`	Every problem, empty if the domain claims values of the fields.

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.

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).

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.

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.

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,
    extensions=dict(),
)

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`.
`extensions`	`Mapping[str, object]`	the settings of the evidence extensions for this context by the name of the extension, e.g. the acceptance of the ratio pairs; a setting with a method `problems` is checked, see `sbmlsim.credibility.extensions`.

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.

ratios `property` ¶

ratios

Get the assessed ratio quantities, those with a Pairing.

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.

The domain is checked against the fields of the metadata by domain_problems.

extension_problems ¶

extension_problems(extensions)

Get the settings and the pairings of the context which no extension takes.

A setting of extensions by a name of no extension of the project and a pairing of a ratio quantity which no extension claims (EvidenceExtension.claims) is a problem: neither would be assessed.

Parameters:

Name	Type	Description	Default
`extensions`	`Sequence[EvidenceExtension]`	the evidence extensions of the project.	required

Returns:

Type	Description
`list[str]`	Every problem, each naming the context.

domain_problems ¶

domain_problems(fields)

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

Parameters:

Name	Type	Description	Default
`fields`	`Mapping[str, type[StrEnum]]`	the fields a domain can claim with their enum, see `metadata_fields`.	required

Returns:

Type	Description
`list[str]`	Every problem of the domain.

Credibility `dataclass` ¶

Credibility(
    *,
    contexts,
    limitations=(),
    notes="",
    covariates=None,
    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] \| None`	the covariates of the subjects whose simulated values an evidence extension checks against the reported ones (the equivalency of the inputs), the target of the model and the measurement type of its reported value; `None` for a declaration which declares none, for which an extension takes its own default, and an empty mapping for a declaration which checks none.
`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 `sbmlsim.credibility.variability`; `None` for a model which declares none.

Raises:

Type	Description
`DeclarationError`	with every problem of the declaration but the ones of the domains, which need the fields of the metadata of the project, see `domain_problems`.

domain_problems ¶

domain_problems(fields)

Get the problems of the domains of the contexts of use.

Parameters:

Name	Type	Description	Default
`fields`	`Mapping[str, type[StrEnum]]`	the fields a domain can claim with their enum, see `metadata_fields`.	required

Returns:

Type	Description
`list[str]`	Every problem of a domain, empty if every domain claims values of
`list[str]`	the fields.

extension_problems ¶

extension_problems(extensions)

Get the settings and the pairings of the contexts which no extension takes.

Parameters:

Name	Type	Description	Default
`extensions`	`Sequence[EvidenceExtension]`	the evidence extensions of the project.	required

Returns:

Type	Description
`list[str]`	Every problem, see `ContextOfUse.extension_problems`.

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.

metadata_fields ¶

metadata_fields(metadata_type, fields=None)

Get the fields of the metadata of the mappings which a domain can claim.

Parameters:

Name	Type	Description	Default
`metadata_type`	`type`	the metadata of the fit mappings of the project, a dataclass derived from `sbmlsim.fit.objects.MappingMetaData`.	required
`fields`	`Collection[str] \| None`	the fields a domain can claim, every field whose type is an enum (`StrEnum`, optional or not) without.	`None`

Returns:

Type	Description
`dict[str, type[StrEnum]]`	The enum of every field, in the order of `fields` or of the class.

Raises:

Type	Description
`ValueError`	if a field of `fields` is not a field of the metadata or its type is no enum.

acceptance_result ¶

acceptance_result(name, value, limit, met)

Get the result of a rule, not evaluable for NaN.

Parameters:

Name	Type	Description	Default
`name`	`str`	the name of the rule.	required
`value`	`float`	its value on the points.	required
`limit`	`str`	its limit.	required
`met`	`bool`	whether the value meets the limit.	required

Returns:

Type	Description
`AcceptanceResult`	The result, `met` `None` for a value `NaN`.

credibility.declaration¶

CouLevel ¶

label property ¶

decisive_role property ¶

Level ¶

EvidenceRole ¶

DeclarationError ¶

Unclaimed dataclass ¶

QuantityOfInterest dataclass ¶

pairing property ¶

Domain dataclass ¶

problems ¶

Evidence dataclass ¶

AcceptanceResult dataclass ¶

AcceptanceRule ¶

name property ¶

limit property ¶

evaluate ¶

Acceptance dataclass ¶

name property ¶

limit property ¶

evaluate ¶

MaxGmfe dataclass ¶

name property ¶

limit property ¶

evaluate ¶

AfeRange dataclass ¶

name property ¶

limit property ¶

evaluate ¶

ContextOfUse dataclass ¶

risk property ¶

rules property ¶

ratios property ¶

minimum_points property ¶

decisive_role property ¶

problems ¶

extension_problems ¶

domain_problems ¶

Credibility dataclass ¶

domain_problems ¶

extension_problems ¶

context ¶

metadata_fields ¶

acceptance_result ¶

label `property` ¶

decisive_role `property` ¶

Unclaimed `dataclass` ¶

QuantityOfInterest `dataclass` ¶

pairing `property` ¶

Domain `dataclass` ¶

Evidence `dataclass` ¶

AcceptanceResult `dataclass` ¶

name `property` ¶

limit `property` ¶

Acceptance `dataclass` ¶

name `property` ¶

limit `property` ¶

MaxGmfe `dataclass` ¶

name `property` ¶

limit `property` ¶

AfeRange `dataclass` ¶

name `property` ¶

limit `property` ¶

ContextOfUse `dataclass` ¶

risk `property` ¶

rules `property` ¶

ratios `property` ¶

minimum_points `property` ¶

decisive_role `property` ¶

Credibility `dataclass` ¶