Skip to content

metadata

The vocabulary with which the fit mappings of the models are described.

Every fit mapping of an experiment carries metadata which says what its curve is: the tissue, the route, the application form, the dosing, the fasting, the health of the subjects, what was coadministered, the genotype and the phenotype of the subjects, the site of the administration, the kind of the data and the site of the blood sample. The fits select their data by these values (see pkpdsim.fit.metadata_filter), so all models describe their studies with the same words: there is one vocabulary for all models, and every closed vocabulary is an enum of this module. Their conventional members are HEALTHY, NONE (nothing coadministered) and NR (not reported), and a member has one name and one value everywhere. A new study which needs a new member adds it here.

A model uses PKPDMappingMetaData as it is. It extends it only for a facet no other model has, in its fitting/mapping_collections.py, without redefining a field or repeating a vocabulary:

# not executed
@dataclass(kw_only=True)
class LocalMappingMetaData(PKPDMappingMetaData):
    diplotype: str | None = None

The tables of sbmlsim show the metadata by member name (to_dict). The values are readable text, and they are API as much as the names: a model may look a member up by its value, e.g. Genotype(f"CYP2C9 {genotype}") from the genotype in the data of a study, so a value is not changed lightly either.

Tissue

Bases: StrEnum

The tissue of a measurement.

Route

Bases: StrEnum

The route of the administration of a substance.

Not pkpdutils.Route (ORAL, IV_BOLUS), the route of a dose in the non-compartmental analysis; a module which needs both imports one under an alias.

Dosing

Bases: StrEnum

The dosing of a substance.

Fasting

Bases: StrEnum

The fasting state of the subjects at the administration.

ApplicationForm

Bases: StrEnum

The pharmaceutical form of the administered substance.

DataType

Bases: StrEnum

What the values of a curve are.

PKPDData

Bases: StrEnum

Whether a curve is pharmacokinetic or pharmacodynamic data.

Health

Bases: StrEnum

The health of the subjects.

Coadministration

Bases: StrEnum

A substance administered together with the substance of the model.

Genotype

Bases: StrEnum

The genotype of a group of subjects, the gene and its alleles.

Phenotype

Bases: StrEnum

The metabolizer phenotype of the subjects for an enzyme.

AdministrationSite

Bases: StrEnum

The site of an injection or application.

SamplingSite

Bases: StrEnum

The site at which the blood of a sample is drawn.

Plasma, serum and blood are typically sampled from an arm vein, which is their default; the other sites are taken where a study states them. Arterial blood and plasma are arterial samples (see PKPDMappingMetaData).

PKPDMappingMetaData dataclass 

PKPDMappingMetaData(
    *,
    tissue,
    route,
    application_form=NR,
    dosing,
    fasting=NR,
    health,
    coadministration=NONE,
    genotype=NR,
    phenotype=NR,
    administration_site=NR,
    data=NR,
    data_type=NR,
    sampling_site=None,
)

Bases: MappingMetaData

The metadata of a fit mapping: the facets every model describes.

The metadata describes the curve; what a fit does with it is decided by the filters of the fits. The fields are keyword-only, so a model adds fields without a default after the defaults of this class.

Attributes:

Name Type Description
tissue Tissue

the tissue of the measurement.
route Route

the route of the administration.
application_form ApplicationForm

the pharmaceutical form, not reported by default.
dosing Dosing

the dosing.
fasting Fasting

the fasting state, not reported by default.
health Health

the health of the subjects.
coadministration Coadministration

the substance coadministered, none by default.
genotype Genotype

the genotype of the subjects, not reported by default.
phenotype Phenotype

the metabolizer phenotype, not reported by default.
administration_site AdministrationSite

the site of an injection or application, not reported by default.
data PKPDData

whether the curve is pharmacokinetic or pharmacodynamic data, not reported by default.
data_type DataType

what the values of the curve are, not reported by default.
sampling_site SamplingSite | None

the stated site of the blood sample, None if none was stated; read it with resolved_sampling_site(). Without a stated site it follows the tissue: plasma, serum and blood are typically sampled from an arm vein, so their data without a stated site are arm-vein samples (ARM_VEIN), arterial blood and plasma are ARTERIAL, and the tissues without a blood sample (saliva, urine, feces, feces and urine, bile, none) are NOT_APPLICABLE. A blood site on such a tissue, NOT_APPLICABLE on a tissue with a blood sample (plasma, serum, blood, arterial blood and plasma) and a site other than ARTERIAL on arterial blood or plasma are a ValueError. Appended after the fields of the first version, so a subclass of a model keeps its fields valid.

Raises:

Type Description
ValueError

if the sampling site does not fit the tissue.

resolved_sampling_site 

resolved_sampling_site()

Get the sampling site: the stated one, else the one of the tissue.

Read the site with this method, not from the field sampling_site, which holds what was stated (None if nothing). It does not depend on __post_init__, so a subclass which defines its own __post_init__ without calling this one resolves as well, and dataclasses.replace(metadata, tissue=...) re-resolves.

Returns:

Type Description
SamplingSite

The stated site; if none was stated ARTERIAL for arterial
SamplingSite

blood and plasma, NOT_APPLICABLE for a tissue without a blood
SamplingSite

sample and ARM_VEIN for plasma, serum and blood.

to_dict 

to_dict()

Get the metadata by field: the member names of the enums.

Any other value is its string ("None" for None). The order is that of the fields, the fields of this class first. The sampling site is the resolved one (resolved_sampling_site).