PBPK library¶

pkpdsim.pbpk builds the whole-body PBPK model of a substance from a short definition. A model package writes only what is specific to its substances: the substances with their mechanism flags, the chemistry of its organs (metabolism, transport), its choices (organ variants, routes, population, sex) and its PD components. The library adds a standard human physiology (ICRP 89), a standard organ for every organ, the alternative organ variants, the routes and sinks, the impaired organ function, the observers and the annotation of every element, and writes the SBML: a comp model with one submodel per organ and the flat model which is simulated.

The pages of this section are for modellers first: this page and the tutorial show how a model is built and how the parts fit together; the pages of the parts say what each part does, which equations it generates and where its numbers come from.

How a model is built¶

1. The model package describes its substances (Substance) and their chemistry (Metabolism, Transport, CustomReaction), and makes its choices in one PBPKDefinition: the organ variants (Variants, the standard organ everywhere else), the routes (Route), the PD components (PDComponent), the sex and the population.
2. build(definition, output_dir) in the factory of the model validates the definition and composes the comp model: a top model with the physiology, the blood pools, the parameters of the substances, the sinks, the dose states and the observers (of the library and of the definition), the creators of the definition as model history, and one submodel per organ (LI, KI, GU, ...), the standard organ or a variant, which owns everything inside its boundary. Every port and every replacement is generated; the model package never writes a ReplacedElement.
3. build writes the comp model <sid>.xml and flattens it into <sid>_flat.xml, the model which MODEL_PATH points at and which every simulation runs. Simulation never resolves comp. Both models are validated: the comp model without the units, the flat model with strict units, since libsbml checks the units of a comp model only in its top model and the flat model holds the math of every organ.
4. The experiments of the model set the covariates (BW, HEIGHT), the doses (PODOSE_<s>), the impairment (CP_severity, f_renal_function) and the activities of the proteins (LI__f_cyp2c9) as they do today, and read the observers (Carm_<s>, Aurine_<s>).

A definition¶

A simple substance needs a short specification and its chemistry: an oral drug, bound to albumin, with one Kp, renal filtration and a hepatic CYP3A4 metabolism into a metabolite.

from pkpdsim.pbpk import (
    MM,
    Binding,
    Excretion,
    Kp,
    Metabolism,
    Organ,
    PBPKDefinition,
    Route,
    Substance,
)

definition = PBPKDefinition(
    sid="api_body",
    substances=[
        Substance(
            "api",
            name="apixaban",
            mr=459.5,
            binding=Binding(fu=0.13, protein="albumin"),
            distribution=Kp(1.2, ftissue=5.0),
            excretion=Excretion(urine=True),
        ),
        Substance("api_m2", name="O-desmethyl apixaban", mr=445.5),
    ],
    chemistry=[
        Metabolism(
            "API2M2",
            Organ.LIVER,
            "api",
            products={"api_m2": 1.0},
            kinetics=MM(vmax=0.01, km=0.05),
            protein="CYP3A4",
        ),
    ],
    routes=[Route.iv("api"), Route.oral("api")],
)
definition.validate()
print([s.sid for s in definition.substances], definition.sex, definition.population)

['api', 'api_m2'] male european_icrp

Everything else is a default: the standard organ in every organ (the segmented intestine for small and large intestine), the male ICRP 89 reference individual, the arm vein preset of PK-Sim. The tutorial builds and simulates such a model step by step.

How the parts fit¶

The migration guide explains the move of a hand-written model of pkdb_models onto the library, with the glimepiride model as example.

What is generated¶

Every quantity which depends on parameters only (the physiology, the impairment, the compartments, fu, BP, the coefficients and exchanges of the organs) is a constant with an initial assignment: an experiment which changes BW before the simulation changes every organ volume and flow with it, because sbmlsim evaluates the initial assignments again after the changes of an experiment. A change during a simulation is not followed, unless the definition names the parameter in PBPKDefinition.dynamic (an impairment changed in the middle of a study, a PD output): then every quantity downstream of it is an assignment rule. The start of the species of an endogenous substance (Substance.baseline, and the starts of a definition at the steady state of a production, PBPKDefinition.starts) is an initial assignment as well, which stays one under a dynamic parameter (see Substances). Only what reads a species is always an assignment rule: the outflow concentrations of the organs, the urinary excretion rate, the readouts and the observers; an observer of a definition which reads constants only is a constant with an initial assignment (see Observers). A model loaded with plain roadrunner sets a covariate with r.setValue("init(BW)", 100.0) and resets, so that the initial assignments are evaluated again.

Builds per sex¶

Sex is a choice of the build (PBPKDefinition.sex): it selects the male or female reference values when the model is built (the ICRP 89 anatomy, the hematocrit, the partition coefficients, the interstitial share, the GFR), and a study of both sexes uses one build per sex. A sex switch inside the SBML made the models load about ten times slower. The factory builds one definition for every sex of its studies, create_archive(DEFINITION, model_output_dir, model=..., copyright=..., sexes=(Sex.MALE, Sex.FEMALE)): the build of the sex of the definition keeps its id (<sid>_flat.xml, the master entry of the archive), the build of another sex is the definition with that sex and the id <sid>_<sex> (sex_definition, <sid>_female_flat.xml), each with its comp model, markdown and antimony in the archive. The master entry of the archive is the build of the sex of the definition, so a model with builds per sex keeps its definition male (the default): its master entry is the male build, the model_path of its model object. Without sexes the archive is the build of the sex of the definition, as before. The model object holds both builds (PKPDModel(model_path=..., female_model_path=...), see Models and their commands), the experiments choose one by the sex of their subjects (sex, see Experiments and their metadata), and the healthy GFR, the renal function of a clearance and the renal classes of an experiment are those of the build of its sex (see Impairment). The builds have the same ids, so a fit applies one parameter set to both.

Values and their sources¶

Every number which the library writes into a model is a Value: the number, its unit and its source, a key of data/sources.toml (citation and DOI), and the generated SBML parameter carries the citation in its notes. The data files of the library (pkpdsim/pbpk/data/*.toml) give every number with its source; a number which no publication gives is a choice of the library with the source ModelChoice and a note which gives the reasoning. The tables of these pages are generated from the data files.

A number of a definition is a plain float (the unit of the model is implied), a Value, or a Formula over ids of the top model, which ties it to other parameters (a metabolite with the Kp of its parent, see Substances); a fitted value enters with its uncertainty from the record of its fit, fitted(FITS.parameter("Kp_api", unit=U.dimensionless)), and keeps the id which FITS.parameter and check_model resolve. The units are those of the models: time in min, amount in mmole, volume in litre, area in m2.

The id scheme¶

One id scheme for every model, built by the functions of pkpdsim.pbpk.ids, so that organs, observers, experiments and fits agree on the ids. The ids of the hand-written models are kept where they fit the scheme (Cve_<s>, Aurine_<s>, BW, f_renal_function, the submodel prefixes LI__, KI__, GU__). A local id of an organ is prefixed by its submodel in the flat model (LI__Cpl_api), an id of the top model is not. A substance id must be unique over all models (a metabolite takes the prefix of its parent, api_m2), must not contain __ and must not start with a token of the scheme (pl_, bc_, free_, z1_, ...).

Every other id of the scheme, the ids a model rarely reads: the physiology, the intestine and the nephron, the dissolution and the doses, the protein turnover, the starts and deltas of the observers and the reactions and local ids of the organs (<zone> a zone token z1, <tseg> a tubule segment pt, <kind> a dose iv, po or sol):

A process of the chemistry keeps the id its definition gives (API2M2), its parameters are <p>_Vmax, <p>_Km, <p>_k, <p>_n in the organ (LI__API2M2_Vmax in the flat model), the ratio of a shared constant <p>_Vmax_ratio, the product fractions f_<p>_<s>, and the parameters of a custom reaction keep their ids in the organ (MU__k_deep). The tables are checked against pkpdsim.pbpk.ids by tests/docs/test_pbpk_ids.py: every row is made by its function, and every name of ids.__all__ has a row (but the tuples of the segment tokens and species_of, which lists ids), so a new id of the scheme fails the test until it is documented.