pbpk¶

The PBPK library, see PBPK library: the package and the classes a model package writes its definition with, and the build. The organs, the physiology and the id scheme are on the pages pbpk organs, pbpk physiology and pbpk ids and data.

The PBPK model library: the building blocks of the PBPK models of a substance.

The base of the experiments of a model built on the library (PBPKSimulationExperiment, ScaledRenalMap, healthy_gfr, REFERENCE_GFR, molecular_weights of pkpdsim.pbpk.experiment), the equilibration outside an experiment (equilibrated_simulation of pkpdsim.pbpk.equilibration) and the validity of the kidney outflow (kidney_outflow, KidneyOutflow of pkpdsim.pbpk.kidney_validity) are exported lazily: they import sbmlsim, which a factory does not need, so import pkpdsim.pbpk imports no simulator.

definition¶

The definition of a PBPK model: the substances, the chemistry and the choices.

Variants `dataclass` ¶

Variants(organs=dict())

The organ variants of a definition, the standard organ everywhere else.

Attributes:

Name	Type	Description
`organs`	`Mapping[Organ, str \| OrganComponent]`	the variant of an organ, by name or as component; the names are resolved from the variant registry when the model is built. The organs may be given as `Organ` members, their values or their names (`"li"`, `"liver"`), normalised to `Organ` members.

PBPKDefinition `dataclass` ¶

PBPKDefinition(
    sid,
    substances,
    chemistry=(),
    variants=Variants(),
    routes=(),
    pd=(),
    sex=MALE,
    population=DEFAULT_POPULATION,
    arm_vein="pksim_default",
    dynamic=(),
    name=None,
    notes=None,
    observers=(),
    creators=(),
    parameters=(),
    starts=dict(),
    deltas=(),
    readouts=(),
    slow_pools=(),
)

The definition of a PBPK model.

Attributes:

Name	Type	Description
`sid`	`str`	the id of the model.
`substances`	`Sequence[Substance]`	the substances.
`chemistry`	`Sequence[Metabolism \| Transport \| CustomReaction]`	the processes, each defined once per organ.
`variants`	`Variants`	the organ variants.
`routes`	`Sequence[Route]`	the routes of administration.
`pd`	`Sequence[PDComponent]`	the pharmacodynamic components.
`sex`	`Sex`	the sex of the model, chosen when it is built: its reference values and default individual; a study of both sexes uses one model per sex, the builds of `create_archive(..., sexes=...)`. A `Sex` member or its value (`"female"`), normalised to the member.
`population`	`str`	the population (`pkpdsim.pbpk.populations`), chosen when the model is built: its reference individual of the sex is the default individual (`BW`, `HEIGHT`, `AGE`); the reference anatomy stays ICRP 89.
`arm_vein`	`str`	the preset of the weights of the arm vein sampling site (`data/arm_vein.toml`), the PK-Sim default skin and muscle mix.
`dynamic`	`tuple[str, ...]`	the parameters of the top model which change during a simulation (an impairment changed in the middle of a study, a PD output): every quantity which depends on them is an assignment rule instead of an initial assignment, so it follows the change; every other quantity follows a change before the simulation only.
`name`	`str \| None`	the name of the model.
`notes`	`str \| None`	the notes of the model.
`observers`	`Sequence[Observer]`	the observers of the definition, parameters of the top model after the observers of the library (a sum of metabolites, a ratio, a species of an organ by its flat id): an assignment rule if it reads a state, else a constant with an initial assignment.
`creators`	`Sequence[Creator]`	the creators of the model, its model history (sbmlutils `Creator`).
`parameters`	`Sequence[ModelParameter]`	the constant parameters of the top model which the model package states (`ModelParameter`), read by the formulas, the observers and the custom reactions of the definition.
`starts`	`Mapping[str, Q]`	the initial concentrations (mM) of species by their flat id (`MU__Cpl_crtn`, a pool `Cve_crtn`, a species of a custom reaction): a number, a `Value` or a `Formula` over the constants of the top model, the initial assignment of the species. For the organs which a production or an elimination of the chemistry moves away from the equilibrium with the baseline of an endogenous substance (`Substance.baseline`): their steady state, so that the body starts stationary. The library generates it from the declared rates of the custom reactions (`CustomReaction.stationary`, `pkpdsim.pbpk.stationary`), a start given here replaces the generated one; without declarations `pkpdsim.pbpk.steady_state` gives the formulas of the organs of the library.
`deltas`	`tuple[str, ...]`	the observers of the top model (`Carm_<s>`, an observer of the definition) whose change over their value at the start a model reads: each gets the constant `<id>_0` (`ids.delta_base`, the base of the delta), its value at the start (an initial assignment), and the observer `<id>_delta = <id> - <id>_0`, e.g. the increase of an endogenous substance over the value before a dose.
`readouts`	`tuple[str, ...]`	the readouts of the library which the model reads, by id, outputs of the intestine with a lumen: the dissolved amount in the lumen `Alumen_<s>`, the summed fluxes of the absorption `Rabs_<s>`, the efflux into the lumen `Reff_<s>` and the loss to the feces `Rfeces_<s>` (`ids.lumen_amount`, ...), the amount absorbed `Aabs_<s>` and the gross absorbed fraction of the oral dose `Fa_<s>`; a model without readouts has none of them.
`slow_pools`	`Sequence[SlowPool]`	the slow (deep) pools of the tissues (`SlowPool`), one per substance: the species `Cslow_<s>` in the merged tissue of each of its organs with the exchange `kslow_<s>Vti(Kpslow_<s>Cti_<s> - Cslow_<s>)` with the tissue (the default) or `kslow_<s>Vti(Kpslow_<s>Cpl_<s> - Cslow_<s>)` with the plasma of the organ (`SlowPool.source`); a model without them has none of their elements.

combine `classmethod` ¶

combine(*definitions, sid)

Couple the definitions of several packages into one physiology.

The substances, the chemistry, the routes, the PD components, the dynamic parameters, the observers and parameters of the definitions, the deltas, the readouts, the slow pools and the creators are the unions of the definitions (the observers of the library follow from the substances), the organ variants are merged; there is one physiology, so the definitions must agree on sex, population and the arm vein preset. Substance ids are unique over all packages, so nothing is renamed: an id which two definitions define is accepted only if both define equal objects, compared by value (a shared metabolite; a fitted value which both take from their fit records, whose uncertainties are equal by their fields, equal_by_value; PD components are equal by the id of their model, their inputs and outputs; a creator is the same person when all its fields are equal). An organ variant is a requirement: an organ which a definition leaves out (the default organ) means no requirement, so the coupled model takes the variant another definition chooses (e.g. its zonated liver); two definitions which choose different variants of an organ raise.

Parameters:

Name	Type	Description	Default
`*definitions`	`PBPKDefinition`	the definitions, e.g. of a drug and an inhibitor.	`()`
`sid`	`str`	the id of the coupled model.	required

Returns:

Type	Description
`PBPKDefinition`	The coupled definition, in the order of the definitions.

Raises:

Type	Description
`ValueError`	if no definition is given, the definitions differ in sex, population or arm vein preset, two definitions define an id (substance, process, route, PD component, observer, parameter, the slow pool of a substance) differently, or choose different variants of an organ; naming the id.

parameter_value ¶

parameter_value(sid)

Get the number of a constant parameter of the definition (parameters).

A constant of a formulation or a dose, e.g. the factor of the dissolution of a prolonged release tablet, is a parameter of the definition, so the model and its archive carry it; the experiments read it here, the one place of the number, and set the parameter of the library from it (f_dis_release_<s> in the simulations of the prolonged release):

# not executed
formulation_map = {
    "immediate release": 1.0,
    "prolonged release": DEFINITION.parameter_value("f_dis_pr_tor"),
}

Parameters:

Name	Type	Description	Default
`sid`	`str`	the id of the parameter.	required

Returns:

Type	Description
`float`	The number in the unit of the parameter.

Raises:

Type	Description
`ValueError`	if the definition has no parameter of the id or its value is a formula, whose number only the model has.

validate ¶

validate(*, symbols=True)

Check the definition.

The observers of the definition are checked against the top model: validate composes the model without them (pkpdsim.pbpk.builder; an element of an organ which an observer reads is exposed by the organ) and checks that an observer id is no id of the body nor of another observer, that every symbol of its formula is an id of the top model, an exposed element of an organ, a requested readout or another observer, and that the observers do not read each other in a cycle; an observer of constants only is accepted (a constant with an initial assignment). compose makes the same check on the model it composes and calls validate without it.

Parameters:

Name	Type	Description	Default
`symbols`	`bool`	check the observers against the top model.	`True`

Raises:

Type	Description
`ValueError`	with all problems found, naming the offending ids.

substance¶

Substances and how the body treats them: binding, erythrocytes, distribution.

Binding `dataclass` ¶

Binding(fu, protein='unknown', ckd=True)

The binding to plasma proteins.

Attributes:

Name	Type	Description
`fu`	`Q`	the fraction unbound in plasma.
`protein`	`Literal['albumin', 'agp', 'unknown']`	the binding protein.
`ckd`	`bool`	whether the CKD factor of the binding acts on the fu of the substance (the CKD profile of albumin or alpha-1-acid glycoprotein, `fimp_albumin_ckd`, `fimp_agp_ckd`; the binding capacity `fimp_plasma_protein` for an unknown protein); `False` for a substance whose binding is measured unchanged in renal impairment (fu then follows only the factor of its binding protein).

Erythrocytes `dataclass` ¶

Erythrocytes(mode, bp=None, kbc=None, k_exchange=None)

The distribution into the erythrocytes.

Attributes:

Name	Type	Description
`mode`	`Literal['equilibrium', 'kinetic']`	`equilibrium` (instantaneous, given by `bp` or `kbc`) or `kinetic` (explicit blood cell species with exchange rates).
`bp`	`Q \| None`	the blood to plasma ratio (equilibrium).
`kbc`	`Q \| None`	the blood cell to plasma coefficient (equilibrium or kinetic).
`k_exchange`	`Q \| None`	the exchange rate between plasma and blood cells (kinetic).

Mode ¶

Bases: StrEnum

How a substance is exchanged between plasma and tissue.

PERFUSION `class-attribute` `instance-attribute` ¶

PERFUSION = 'perfusion'

Flow-limited: the tissue is in equilibrium with the blood leaving it.

TISSUE `class-attribute` `instance-attribute` ¶

TISSUE = 'tissue'

Merged tissue with finite exchange PS * fu * (Cpl - Cti/Kp).

PERMEABILITY `class-attribute` `instance-attribute` ¶

PERMEABILITY = 'permeability'

Interstitial and intracellular space with a permeability each.

Kp `dataclass` ¶

Kp(
    value=None,
    overrides=dict(),
    interstitial=None,
    *,
    organs=None,
    mode=TISSUE,
    ftissue=None,
    ps=dict(),
    ps_per_volume=True,
    ckd_floor=dict(),
)

Bases: _Exchange

A tissue to plasma coefficient of the whole tissue.

Every organ the substance enters has the coefficient of its override, else the scale of interstitial times its interstitial share, else value.

Attributes:

Name	Type	Description
`value`	`Q \| None`	the coefficient of the substance, `Kp_<s>`; `None` when every organ the substance enters has an override or `interstitial` is set (no `Kp_<s>` then; a value with `interstitial` is refused, no organ would read it).
`overrides`	`Mapping[Organ, Q]`	the coefficients of single organs, by `Organ` member, value or name (normalised to `Organ` members).
`interstitial`	`Q \| None`	the scale of the interstitial share, the extracellular distribution of a substance which reaches the interstitial fluid and not the cells (a contrast agent, a marker of the extracellular volume, a highly bound acid): every organ without an override has `Kp_<o>_<s> = fKp_<s> * share`, the share `f_int*K_int_pls(fu)/(1 - f_vas)` of the organ at the fu of the substance and the fractions of the reference individual of the sex of the build (`distribution.interstitial_share`, the lower bound `check_kp` sets), so a female build has the female share. The scale is the parameter `fKp_<s>`: a number, a `Value` (fitted, `fitted(FITS.parameter("fKp_<s>"))`) or a `Formula`. `None` (the default) creates no `fKp_<s>`.

KpMethod `dataclass` ¶

KpMethod(
    method,
    logp,
    pka,
    compound,
    factor=1.0,
    *,
    organs=None,
    mode=TISSUE,
    ftissue=None,
    ps=dict(),
    ps_per_volume=True,
    ckd_floor=dict(),
)

Bases: _Exchange

The tissue to plasma coefficients from a calculation method.

Attributes:

Name	Type	Description
`method`	`Literal['rodgers_rowland']`	the method.
`logp`	`float`	the log10 of the octanol:water partition coefficient.
`pka`	`tuple[float, ...]`	the pKa values.
`compound`	`Literal['neutral', 'acid', 'base', 'zwitterion']`	the type of the compound.
`factor`	`Q`	a factor on all coefficients.

ThresholdReabsorption `dataclass` ¶

ThresholdReabsorption(threshold, n)

A reabsorption of the filtered load up to a renal threshold.

The reabsorbed fraction of the filtrate at the plasma concentration C, 1/(1 + (fu*C/threshold)^n)^(1/n), of the unbound (filtered) concentration fu*C: the reabsorption fu*GFR*C/(1 + (fu*C/threshold)^n)^(1/n) takes almost all of a filtrate below the threshold and approaches the transport maximum GFR*threshold above it, and it never exceeds the filtration fu*GFR*C (the fraction is at most 1). n sets how sharp the threshold is: far below it the excreted fraction of the filtrate is about (fu*C/threshold)^n/n. The law of the reabsorption of creatine with its renal threshold (CRREABS of the creatinine model).

Attributes:

Name	Type	Description
`threshold`	`Q`	the renal threshold, a concentration of the filtrate (mM), `reab_threshold_<s>`.
`n`	`Q`	the sharpness of the threshold (dimensionless), `reab_n_<s>`.

Excretion `dataclass` ¶

Excretion(
    urine=False, fraction_reabsorbed=0.0, reabsorption=None
)

The excretion which is not a process of the chemistry.

Attributes:

Name	Type	Description
`urine`	`bool`	glomerular filtration `fu*GFR`.
`fraction_reabsorbed`	`Q`	the constant fraction of the filtrate which is reabsorbed, `f_reabsorbed_<s>`.
`reabsorption`	`ThresholdReabsorption \| None`	a reabsorption which depends on the plasma concentration instead of the constant fraction (`ThresholdReabsorption`), `None` for the constant fraction; with it `fraction_reabsorbed` stays 0 and the substance has no `f_reabsorbed_<s>`.

Substance `dataclass` ¶

Substance(
    sid,
    name,
    mr,
    annotations=list(),
    binding=None,
    erythrocytes=None,
    distribution=None,
    excretion=Excretion(),
    inhibits=(),
    induces=(),
    baseline=None,
)

A substance of the model.

Attributes:

Name	Type	Description
`sid`	`str`	the short id, unique over all models (metabolites take the prefix of the parent, `api_m2`).
`name`	`str`	the name.
`mr`	`Q`	the molecular weight (g/mole).
`annotations`	`list[tuple[BQB, str]]`	the annotations (ChEBI, PubChem, NCIT).
`binding`	`Binding \| None`	the plasma protein binding, `None` is fu = 1.
`erythrocytes`	`Erythrocytes \| None`	the distribution into erythrocytes, `None` is none.
`distribution`	`Kp \| KpMethod \| None`	the distribution into tissues, `None` is vascular only.
`excretion`	`Excretion`	the excretion.
`inhibits`	`tuple[Inhibition, ...]`	the inhibitions of proteins by the substance.
`induces`	`tuple[Induction, ...]`	the inductions of proteins by the substance.
`baseline`	`Q \| None`	the plasma concentration (mM) of an endogenous substance at the start, `baseline_<s>`; `None` starts every species at 0. Every plasma species starts at it, every other species of the blood and the tissue at the equilibrium of its exchange with plasma (e.g. `Kp*baseline` in the merged tissue), the lumen, the tubule and the sinks at 0. A `Formula` may read the parameters of the top model and the observers of the definition (a production over a clearance), not what changes during the simulation.

chemistry¶

The processes of the chemistry: metabolism, transport and custom reactions.

A process states its own constants, or takes its capacity as a ratio of another process of the organ (RateOf); a metabolism converts its substrate into its products by fractions, numbers or values with the remainder REST; a custom reaction has the constants of its mechanism as ModelParameters, its own constants with provenance, and may declare its rate at the steady state (stationary): a Formula of the rate, "linear" for a rate law which is linear in its substrate, or Saturable(vmax, km) for a Michaelis-Menten rate of a plasma species; the builder then writes the starts of its substances at their steady state (pkpdsim.pbpk.stationary).

The enum fields of a process (organ, direction, membrane, part) may be given as member, value or name ("li", "liver", "basolateral"): the process holds the member, anything else raises a ValueError which names the field and the allowed values.

REST `module-attribute` ¶

REST = Rest.REST

The product of a metabolism which takes the remainder of the fractions: 1 - sum of the fractions of the other products.

LINEAR `module-attribute` ¶

LINEAR = 'linear'

The steady state of a custom reaction whose rate law is linear in its substrate (CustomReaction.stationary): a first order clearance of a plasma or tissue species.

Fraction ¶

Fraction = float | Value | Rest

The fraction of a product of a metabolism: a number, a value (fitted) or the remainder REST.

Stationary ¶

Stationary = Formula | Literal['linear'] | Saturable

The steady state of a custom reaction (CustomReaction.stationary).

RateOf `dataclass` ¶

RateOf(process, factor)

The constant of a process as a ratio of the constant of another process.

The vmax of MM or Hill or the k of FirstOrder of a metabolism or transport, given as a factor times the same constant of another metabolism or transport of the same organ (two transporters of one substrate with a fixed ratio of their capacities): the constant <process>_Vmax (or _k) is the initial assignment <process>_Vmax_ratio * <other>_Vmax of the organ, so it follows a change of the other constant before the simulation (a fit of one capacity moves both), and the factor is the constant <process>_Vmax_ratio with its provenance (ids.rate_ratio).

Attributes:

Name	Type	Description
`process`	`str`	the id of the other process, a metabolism or transport of the organ which states the same constant itself (a `vmax` for a `vmax`, a `k` with the same `per_volume` for a `k`).
`factor`	`Q`	the ratio (dimensionless), a number, a `Value` or a `Formula`.

Rest ¶

Bases: Enum

The remainder of the product fractions of a metabolism, REST.

FirstOrder `dataclass` ¶

FirstOrder(k, per_volume=True)

First order kinetics on the unbound concentration.

Attributes:

Name	Type	Description
`k`	`Q \| RateOf`	the clearance per litre of organ (1/min), with `per_volume=False` the clearance of the whole organ (l/min); `RateOf` a ratio of the `k` of another process of the organ.
`per_volume`	`bool`	`k` is per litre of organ (the default), so the whole organ has the clearance `k * V<o>` and follows the organ of the individual, as the `vmax` of `MM` and `Hill` does; `False` keeps the clearance of the whole organ, which does not scale with the organ volume.

MM `dataclass` ¶

MM(vmax, km)

Michaelis-Menten kinetics on the unbound concentration.

Attributes:

Name	Type	Description
`vmax`	`Q \| RateOf`	the maximal rate per litre of organ (mmole/min/l), the whole organ has the maximal rate `vmax * V<o>`; `RateOf` a ratio of the `vmax` of another process of the organ.
`km`	`Q`	the Michaelis constant (mmole/l).

Hill `dataclass` ¶

Hill(vmax, km, n)

Hill kinetics on the unbound concentration.

Attributes:

Name	Type	Description
`vmax`	`Q \| RateOf`	the maximal rate per litre of organ (mmole/min/l), the whole organ has the maximal rate `vmax * V<o>`; `RateOf` a ratio of the `vmax` of another process of the organ.
`km`	`Q`	the concentration of the half-maximal rate (mmole/l).
`n`	`Q`	the Hill coefficient.

Direction ¶

Bases: StrEnum

The direction of a transport relative to the cell.

Membrane ¶

Bases: StrEnum

The membrane a transporter sits in.

BASOLATERAL `class-attribute` `instance-attribute` ¶

BASOLATERAL = 'basolateral'

The blood side.

APICAL `class-attribute` `instance-attribute` ¶

APICAL = 'apical'

The side of bile, urine or gut lumen.

Metabolism `dataclass` ¶

Metabolism(
    sid,
    organ,
    substrate,
    products,
    kinetics,
    protein=None,
    profile=None,
)

The conversion of a substrate in an organ.

Attributes:

Name	Type	Description
`sid`	`str`	the id of the process, unique in the definition.
`organ`	`Organ`	the organ.
`substrate`	`str`	the id of the substrate.
`products`	`Mapping[str, Fraction]`	the fractions of the substrate converted into each product; no products is an elimination. Numbers which sum to 1 are the stoichiometry of one reaction. A `Value` (a fitted fraction) or the remainder `REST` (one product, `1 - sum` of the others) makes every fraction a constant of the organ, `f_<process>_<product>` (`ids.product_fraction`), the reaction consumes the substrate and one reaction per product forms it with its fraction of the rate, `<process>_to_<product>` (`ids.product_reaction`); the fractions can never sum above 1: the range of a fitted fraction is its value and the support of the distribution of its draws (the bounds of the fit), a fitted fraction needs the remainder.
`kinetics`	`FirstOrder \| MM \| Hill`	the rate law.
`protein`	`str \| None`	the id of the enzyme, its activity factor multiplies the rate.
`profile`	`str \| None`	the name of the abundance profile of the enzyme.

Transport `dataclass` ¶

Transport(
    sid,
    organ,
    substance,
    direction,
    membrane,
    kinetics,
    protein=None,
)

The active transport of a substance in an organ.

Attributes:

Name	Type	Description
`sid`	`str`	the id of the process, unique in the definition.
`organ`	`Organ`	the organ.
`substance`	`str`	the id of the transported substance.
`direction`	`Direction`	the direction relative to the cell.
`membrane`	`Membrane`	the membrane.
`kinetics`	`FirstOrder \| MM \| Hill`	the rate law.
`protein`	`str \| None`	the id of the transporter.

Saturable `dataclass` ¶

Saturable(vmax, km)

A Michaelis-Menten rate of a plasma species, vmax*C/(km + C).

The formulas have two scopes, by where the class is used:

the steady state of a custom reaction (CustomReaction.stationary): its rate law is the saturable rate of the plasma species of its substrate C, so its organ starts at the root of a quadratic; the formulas read the ids of the organ, as the rate law (Vti, the parameters of the reaction) and constants of the top model;
an argument of the formulas of pkpdsim.pbpk.steady_state (a saturable secretion of the kidney plasma, which a model writes into a parameter of the definition): the formulas read the ids of the top model only.

Attributes:

Name	Type	Description
`vmax`	`str`	the capacity of the whole organ (mmole/min), a formula.
`km`	`str`	the Michaelis constant (mM), a formula.

CustomReaction `dataclass` ¶

CustomReaction(
    sid,
    organ,
    part,
    equation,
    formula,
    parameters=list(),
    species=list(),
    stationary=None,
)

A mechanism the library has no class for, placed like any process.

Attributes:

Name	Type	Description
`sid`	`str`	the id of the process, unique in the definition.
`organ`	`Organ`	the organ.
`part`	`Part`	the part of the organ it acts in.
`equation`	`str`	the reaction equation.
`formula`	`str`	the rate law.
`parameters`	`Sequence[ModelParameter \| Parameter]`	the constants of the rate law, local ids of the organ (`<ORGAN>__<id>` in the flat model), none by default: a `ModelParameter` (a number, a `Value` with its provenance and the uncertainty of a fit, a `Formula` over ids of the top model), or a sbmlutils `Parameter` as it is. An id is defined once in an organ, the other reactions of the organ read it.
`species`	`list[Species]`	additional species of the reaction.
`stationary`	`Stationary \| None`	the rate of the reaction at the steady state of its substances, which makes the builder start every organ part of them at their steady state (`pkpdsim.pbpk.stationary`), `None` for none: a `Formula` of the rate (mmole/min), a formula of the organ as the rate law (it reads the elements of the organ, the parameters of the reaction, the starts of species of other substances and constants of the top model, never a species of a substance it moves); `"linear"` (`LINEAR`), a rate law linear in its substrate, a plasma or tissue species of one substance, whose clearance the builder takes from the rate law; `Saturable(vmax, km)`, a Michaelis-Menten rate of the plasma species of its substrate. Every custom reaction which moves a substance with a steady state declares its own.

check_kinetics ¶

check_kinetics(where, k)

Check that the parameters of a rate law are positive.

A RateOf is checked by check_rate_of.

check_rate_of ¶

check_rate_of(p, chemistry)

Check a constant of a process which is a ratio of another process, RateOf.

The other process is a metabolism or transport of the same organ which states the same constant itself (a Vmax for a Vmax, a first order k with the same per_volume for a k, so that both have one unit), the factor is positive and dimensionless; a chain of ratios (and so a cycle) is refused.

Parameters:

Name	Type	Description	Default
`p`	`Metabolism \| Transport`	the process.	required
`chemistry`	`Mapping[str, Metabolism \| Transport \| CustomReaction]`	the processes of the definition by id.	required

Returns:

Type	Description
`list[str]`	The problems, naming the processes.

check_products ¶

check_products(p)

Check the product fractions of a metabolism: their sum is never above 1.

Numbers sum to 1 (the stoichiometry of one reaction). A Value (fixed or fitted) is a constant of the organ which a fit, a scan or an experiment may change, so the products need the remainder REST, which keeps the sum at 1 for every value; the remainder is never negative: the sum of the upper ends of the ranges of the other fractions (fraction_range) is at most 1, and not always 1 (a remainder of 0). Every fraction is positive and its range not negative; a Formula cannot be bounded.

Parameters:

Name	Type	Description	Default
`p`	`Metabolism`	the metabolism.	required

Returns:

Type	Description
`list[str]`	The problems, naming the metabolism and the products.

fraction_range ¶

fraction_range(f)

Get the range of a fraction: its value and the support of the draws of a fit.

The distribution of the draws of a fitted value (the uncertainty of fitted, truncated to the bounds of the fit) is the range a fit or an uncertainty run gives the fraction (pkpdsim.distrib.support).

check_stationary ¶

check_stationary(p)

Check the declared steady state of a custom reaction.

A Formula in mmole/min, the text "linear" or a Saturable with two formulas; the build checks what the declaration reads and whether the organs have a closed steady state (pkpdsim.pbpk.stationary).

Parameters:

Name	Type	Description	Default
`p`	`CustomReaction`	the custom reaction.	required

Returns:

Type	Description
`list[str]`	The problems, naming the reaction.

check_custom_parameters ¶

check_custom_parameters(p, defined)

Check the parameters of a custom reaction, local ids of its organ.

An SId without __ (the separator of the flat ids), defined once in the organ (defined, the ids of the other custom reactions of the organ: they read it), a ModelParameter with a value in its unit. That an id is no other element of the organ is checked by the build (OrganBuilder.model_definition).

Parameters:

Name	Type	Description	Default
`p`	`CustomReaction`	the custom reaction.	required
`defined`	`set[str]`	the parameter ids of the custom reactions of the organ so far, to which the ids of `p` are added.	required

Returns:

Type	Description
`list[str]`	The problems, naming the reaction and the ids.

proteins¶

Enzymes and transporters, and their inhibition and induction by substances.

The protein table, the declarations of inhibition and induction and the turnover of the proteins (turnover). The SBML is generated by the organs: the base activity f_<protein> of every organ with a process of the protein, the turnover state E_<protein> under mechanism-based inhibition and induction (pkpdsim.pbpk.organ_builder), and the inhibitor terms in the rates of the processes (pkpdsim.pbpk.placement).

PROTEINS `module-attribute` ¶

PROTEINS = load_proteins()

The proteins of the library by their id.

Protein `dataclass` ¶

Protein(sid, name, uniprot, ncit=None)

An enzyme or a transporter, named once with its annotation.

Attributes:

Name	Type	Description
`sid`	`str`	the id of the protein, also used in `f_<sid>`, `CYP3A4`.
`name`	`str`	the name of the protein.
`uniprot`	`str`	the UniProtKB accession of the human protein.
`ncit`	`str \| None`	the NCI Thesaurus code, if the thesaurus has a concept.

Inhibition `dataclass` ¶

Inhibition(protein, kind, ki, kiu=None, kinact=None)

The inhibition of a protein by a substance, declared on the inhibitor.

It acts on every process of the protein (pkpdsim.pbpk.placement): competitive on Km, uncompetitive on Vmax and Km, noncompetitive on Vmax, mixed on both (Segel 1975); a mechanism-based inhibition inactivates the protein (its turnover state, Mayhew 2000) and binds competitively with Ki = KI while it does. A substance inhibits a protein once.

Attributes:

Name	Type	Description
`protein`	`str`	the id of the inhibited protein (key of `PROTEINS`).
`kind`	`Literal['competitive', 'noncompetitive', 'uncompetitive', 'mixed', 'mechanism']`	the type of the inhibition.
`ki`	`Q`	the inhibition constant (of the unbound inhibitor, mM), the competitive one of a mixed inhibition, the KI of a mechanism-based inhibition.
`kiu`	`Q \| None`	the uncompetitive constant of a mixed inhibition, only there.
`kinact`	`Q \| None`	the maximal inactivation rate (1/min) of a mechanism-based inhibition, only there.

Induction `dataclass` ¶

Induction(protein, emax, ec50)

The induction of a protein by a substance, declared on the inducer.

It raises the synthesis of the protein, kdeg*(1 + Emax*I/(EC50 + I)) (Almond 2009), so its amount approaches 1 + Emax*I/(EC50 + I).

Attributes:

Name	Type	Description
`protein`	`str`	the id of the induced protein (key of `PROTEINS`).
`emax`	`Q`	the maximal increase of the expression (fold change - 1).
`ec50`	`Q`	the concentration of half-maximal induction (unbound, mM).

load_proteins ¶

load_proteins()

Load the protein table data/proteins.toml.

Returns:

Type	Description
`dict[str, Protein]`	The proteins by their id.

turnover ¶

turnover(organ)

Get the degradation rate constant of the proteins in an organ.

The values of CYP3A4 (data/proteins.toml, [turnover]): the liver, the small intestine, and the hepatic value for every other organ.

Parameters:

Name	Type	Description	Default
`organ`	`Organ`	the organ.	required

Returns:

Type	Description
`Value`	`kdeg` (1/min) with its source; the notes state the value of the
`Value`	source (1/h).

routes¶

The routes of administration and their dose states.

A dose is a dose state in mg, which an experiment sets or adds to (PKPDSimulationExperiment.add_doses: "PODOSE_<s> + 10.0"), and which is applied by a first order process, the conventions of the hand-written models:

intravenous: IVDOSE_<s> drains into the venous plasma Cve_<s> with the rate Kiv_<s> = ln(2)/ti_<s> (ti_<s> the half-life of the injection in s); a constant infusion Ri_<s> (mg/min) adds to the dose state;
oral tablet: PODOSE_<s> is the undissolved drug in the stomach (the first segment of the intestine), which dissolves into the stomach lumen with the dissolution rate of the formulation and empties undissolved with the stomach; in the next segments the undissolved drug is a species of its own, it dissolves there and leaves undissolved into the feces;
oral solution: SOLDOSE_<s> enters the stomach lumen dissolved with the fast rate Ka_sol_<s> (1/hr).

The dose in mg is converted to mmole with the molecular weight Mr_<s>. The dose states and the parameters of the formulations are parameters of the top model (route_objects); the oral doses are applied by the intestine, which reads them through ports and owns their reactions and the rate rules of the oral dose states (the top dose states replace its inputs, so the rules act on them).

The dissolution rate kdis (1/min) acts on the undissolved amount of every segment:

FirstOrderDissolution(k, fed, release): kdis = k (Ka_dis_<s>, 1/hr), times the factor of a modified-release formulation f_dis_release_<s> and (1 + FED*(f_dis_fed_<s> - 1)) of the fed state, of those which are set;
WeibullDissolution(t50, shape, lag): the fraction dissolved F = 1 - exp(-ln2*((t - lag)/t50)^shape) after the lag time, applied as its hazard kdis = ln2*shape/t50*((t - lag)/t50)^(shape - 1) on the undissolved amount, with the time since the dose t the mean age of the undissolved drug (age_dis_<s>, the state W_dis_<s> of the age-weighted amount divided by the undissolved amount): exact for one dose; doses which overlap share one clock, the amount-weighted mean age: both dissolve with the hazard of the mean age, the rest of the earlier dose as if it were younger (not at all while the mean age is below the lag time), the new dose as if it were older; a dose given after the earlier one has dissolved is exact again;
DoseDependentDissolution(k, dose50): kdis = k*D50/(D50 + D) with the undissolved amount D (mg) of all segments, a dissolution which saturates with the undissolved dose (solubility-limited), at most k*D50.

ORAL `module-attribute` ¶

ORAL = frozenset({'oral', 'oral_solution'})

The routes into the intestine.

Formulation ¶

Formulation = (
    FirstOrderDissolution
    | WeibullDissolution
    | DoseDependentDissolution
)

The dissolution of a tablet.

FirstOrderDissolution `dataclass` ¶

FirstOrderDissolution(k, fed=None, release=None)

The first order dissolution of a tablet.

Attributes:

Name	Type	Description
`k`	`Q`	the rate of the dissolution (1/hr).
`fed`	`Q \| None`	the factor of the dissolution rate in the fed state (`FED = 1`), the body parameter `f_dis_fed_<s>`; the rate is `k(1 + FED(fed - 1))`. No parameter if `None`. The single lumen has no fed state and raises.
`release`	`Q \| None`	the factor of a modified-release formulation, the body parameter `f_dis_release_<s>` (the given value, set by the experiments of such a formulation; 1 for the immediate-release tablet), which multiplies the rate. No parameter if `None`.

WeibullDissolution `dataclass` ¶

WeibullDissolution(t50, shape, lag=0.0)

The Weibull dissolution of a tablet.

The fraction dissolved 1 - exp(-ln2*((t - lag)/t50)^shape) after the lag time.

Attributes:

Name	Type	Description
`t50`	`Q`	the time of half dissolution after the lag time (min).
`shape`	`Q`	the shape of the Weibull function (1: first order).
`lag`	`Q`	the lag time (min).

DoseDependentDissolution `dataclass` ¶

DoseDependentDissolution(k, dose50)

The dissolution of a tablet which saturates with the undissolved dose.

kdis = k*dose50/(dose50 + D) with the undissolved amount D.

Attributes:

Name	Type	Description
`k`	`Q`	the rate of the dissolution of a small dose (1/hr).
`dose50`	`Q`	the undissolved amount of half the rate (mg).

Route `dataclass` ¶

Route(kind, substance, formulation=None)

The administration of a substance.

Attributes:

Name	Type	Description
`kind`	`Literal['iv', 'oral', 'oral_solution']`	intravenous, oral tablet (with dissolution) or oral solution.
`substance`	`str`	the id of the administered substance.
`formulation`	`Formulation \| None`	the dissolution of the tablet, the first order dissolution of the data (`Ka_dis`) if `None`.

iv `classmethod` ¶

iv(s)

Get the intravenous route of a substance: bolus and infusion.

oral `classmethod` ¶

oral(s, formulation=None)

Get the oral route of a substance as tablet, with a formulation.

oral_solution `classmethod` ¶

oral_solution(s)

Get the oral route of a substance given as solution.

dissolution_inputs ¶

dissolution_inputs(route)

Get the parameters of the top model which the dissolution of a tablet reads.

Parameters:

Name	Type	Description	Default
`route`	`Route`	an oral route (tablet).	required

Returns:

Type	Description
`list[tuple[str, UnitDefinition, str]]`	(id, unit, name) of every parameter of the formulation.

dissolution_reads_fed ¶

dissolution_reads_fed(route)

Check whether the dissolution of a tablet depends on the fed state.

is_weibull ¶

is_weibull(route)

Check whether a tablet dissolves by a Weibull function (it needs the age).

dissolution_rate ¶

dissolution_rate(route, undissolved, age)

Get the dissolution rate of a tablet (1/min) on its undissolved amount.

Parameters:

Name	Type	Description	Default
`route`	`Route`	an oral route (tablet).	required
`undissolved`	`str`	the undissolved amount of all segments (mg), formula.	required
`age`	`str`	the mean time since the dose of the undissolved drug (min), id.	required

Returns:

Type	Description
`str`	The formula and whether it reads a species (then the intestine makes
`bool`	it an assignment rule).

route_objects ¶

route_objects(route, substance)

Get the dose state of a route and its parameters in the top model.

The intravenous route applies its dose into the venous plasma; the oral routes are applied by the intestine.

Parameters:

Name	Type	Description	Default
`route`	`Route`	the route.	required
`substance`	`Substance`	the administered substance.	required

Returns:

Type	Description
`list[Sbase]`	The parameters (and for the intravenous route the rules and the
`list[Sbase]`	reaction) of the route.

pd¶

Pharmacodynamic and physiology components, coupled to the body by their ports.

A component is an sbmlutils model of the package (a PD model, a model of body weight or of the electrolytes) with declared ports. It reads quantities of the body through its input ports and changes quantities of the body through its output ports; the builder adds it as a comp ModelDefinition with a Submodel of the id of the model and generates the replacements, so the package writes no ReplacedElement:

an input: the element of the body (Carm_free_api, a species, an observer) replaces the element of the input port of the component, which reads it under its own id;
an output: the element of the output port of the component replaces the parameter of the body (f_cardiac_function), which every quantity of the body reads; the parameter is dynamic (PBPKDefinition.dynamic), so the quantities which depend on it are assignment rules and follow it during the simulation.

The flat model has the elements of the component prefixed by its id (<sid>__E), the replaced parameter of the body keeps its id.

PDComponent `dataclass` ¶

PDComponent(model, inputs, outputs)

A model with declared ports, connected to the body by name.

Two components are equal when their models have the same id and they have the same inputs and outputs (the sbmlutils Model compares by identity), so the component which two packages construct each for itself is one component of a coupled model (PBPKDefinition.combine).

Attributes:

Name	Type	Description
`model`	`Model`	the model of the component; its id is the id of its submodel and the prefix of its elements in the flat model.
`inputs`	`Mapping[str, str]`	the elements of the body which the component reads, by the id of the element of its input port: `{"C_drug": "Carm_free_api"}` reads the unbound arm vein concentration as `C_drug`.
`outputs`	`Mapping[str, str]`	the parameters of the body which the component changes, by the id of the element of its output port: `{"f_cardiac": "f_cardiac_function"}` replaces the cardiac function of the body by `f_cardiac`.

ports ¶

ports(model)

Get the ports of a model by the id of their element.

Parameters:

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

Returns:

Type	Description
`dict[str, tuple[str, PortType \| None]]`	The id and the type of the port of every element with a port
`dict[str, tuple[str, PortType \| None]]`	(`port=True` gives `<id>_port`, a `Port` its id and type) and of
`dict[str, tuple[str, PortType \| None]]`	every port of the model which names its element (`idRef`).

builder¶

The composition of a PBPK model from its definition, and its build.

The comp model has a top model and one submodel per organ:

the top model holds the physiology (covariates, volumes, flows), the blood pools (arterial, venous, portal; plasma C<pool>_<s> and kinetic blood cells C<pool>_bc_<s>), the parameters of the substances (Mr, fu, Kp or the factor fKp_<s> and the Kp_<o>_<s> of a Kp method, BP, ...), the sinks (urine, feces, bile), the dose states of the routes and the parameters the intestine reads (ka_<s>, FED);
every organ is a ModelDefinition with a Submodel (LI, KI, ...), the standard organ or a variant (pkpdsim.pbpk.variants); it reads the elements of the body through its ports, and its outflow concentrations replace the parameters Cout_<o>_<s> of the top model. The intestine (segmented by default, or single_lumen) replaces small and large intestine with one submodel GU, which owns the intestinal lumen and applies the oral doses.

Every port is declared by the organ (its Boundary) and every replacement is generated here from it; the flat model has the ids of the scheme (LI__Cpl_<s> in the organs, the ids of the top model unprefixed).

The sinks are those of pkpdsim.pbpk.sinks, the observers (unbound and blood concentrations, hepatic and arm vein) those of pkpdsim.pbpk.observers.

Every quantity which depends on parameters only (the physiology, the impairment, the compartments of the pools and the organs, fu, BP, the coefficients and exchanges of the organs) is a constant with an initial assignment, not an assignment rule: a change before the simulation (a change of an experiment, which sbmlsim applies with the initial assignments which read it) is followed, a change during the simulation is not. Only what reads a species (the outflow concentrations Cout_<o>_<s>, the observers) and the rate of an intravenous injection Kiv_<s> (of the dose protocol, which changes it between doses) are assignment rules. A parameter which changes during a simulation is named in PBPKDefinition.dynamic: every quantity downstream of it, in the top model and in the organs, is an assignment rule (_dynamic).

The top model holds the impaired organ function as well (pkpdsim.pbpk.impairment): the severities and their factors on the physiology, fu and the activity of the proteins of the liver.

A PD component (pkpdsim.pbpk.pd) is a further ModelDefinition with a Submodel of its id: the elements of the body replace its inputs, its outputs replace parameters of the body, which are dynamic.

Every element is annotated when it is created (pkpdsim.pbpk.annotation); an input of a component takes the annotation of the element of the body which replaces it, and the model the annotation of a PBPK model.

BuildResult `dataclass` ¶

BuildResult(comp_path, flat_path)

The files of a built model.

Attributes:

Name	Type	Description
`comp_path`	`Path`	the comp model, the organs as submodels.
`flat_path`	`Path`	the flattened model, which is simulated.

organ_component ¶

organ_component(definition, organ)

Get the component of an organ: its variant, the standard organ by default.

Parameters:

Name	Type	Description	Default
`definition`	`PBPKDefinition`	the definition.	required
`organ`	`Organ`	the organ.	required

Returns:

Type	Description
`OrganComponent`	The component.

Raises:

Type	Description
`ValueError`	if the variant of the organ is a name of no variant.

built_organs ¶

built_organs(definition)

Get the organs which are built as a submodel.

Parameters:

Name	Type	Description	Default
`definition`	`PBPKDefinition`	the definition.	required

Returns:

Type	Description
`list[Organ]`	Every organ but those the intestine replaces besides the small
`list[Organ]`	intestine (the large intestine).

organ_context ¶

organ_context(definition, organ, top=None, steady=None)

Get the context of an organ: every substance flows through every organ.

Parameters:

Name	Type	Description	Default
`definition`	`PBPKDefinition`	the definition.	required
`organ`	`Organ`	the organ.	required
`top`	`Mapping[str, tuple[str, UnitType]] \| None`	the parameters and compartments of the top model with their kind and unit, which a `Formula` of the organ may read.	`None`
`steady`	`SteadyPlan \| None`	the generated steady state of the definition (`pkpdsim.pbpk.stationary.steady_plan`), `None` for none.	`None`

Returns:

Type	Description
`OrganContext`	The substances with their parts in the organ, the chemistry and the
`OrganContext`	inhibitions and inductions of the substances.

compose ¶

compose(definition)

Compose the comp model of a definition.

Parameters:

Name	Type	Description	Default
`definition`	`PBPKDefinition`	the definition.	required

Returns:

Type	Description
`Model`	The comp model: the top model with one submodel per organ and one per
`Model`	PD component, the observers of the definition after those of the
`Model`	library, the creators of the definition as model history; the unit
`Model`	definitions of `U` and the units of the observers which `U` lacks.

Raises:

Type Description

ValueError

if the definition is invalid, an organ variant is unknown, an organ reads an element the body does not have, a route is given twice, an oral route, an apical transport of the small intestine or a readout has no intestine with a lumen, a PD component names a port or an element of the body which does not exist, a PD component or an observer reads an element of an organ which the organ does not expose, or an observer of the definition is invalid in the top model (observer_problems).

observer_problems ¶

observer_problems(definition)

Check the observers of a definition against the top model.

The model is composed without the observers of the definition (an element of an organ which an observer reads is exposed by the organ); an observer id must be no id of the body (nor of a submodel or model definition), every symbol of its formula a value of the top model (a parameter, species, compartment or reaction, never a submodel or model definition), an exposed element of an organ or another observer, and the observers must not read each other in a cycle (_observer_problems).

Parameters:

Name	Type	Description	Default
`definition`	`PBPKDefinition`	the definition, otherwise valid.	required

Returns:

Type	Description
`list[str]`	The problems, naming the observers and the ids.

Raises:

Type	Description
`ValueError`	if an observer reads an element of an organ which the organ does not expose.

build ¶

build(definition, output_dir)

Build a definition: the comp model and the flat model.

Parameters:

Name	Type	Description	Default
`definition`	`PBPKDefinition`	the definition.	required
`output_dir`	`Path`	the folder of the files `<sid>.xml` and `<sid>_flat.xml`.	required

Returns:

Type	Description
`BuildResult`	The paths of the comp and the flat model.

Raises:

Type	Description
`ValueError`	if the definition cannot be composed, or a model has SBML errors.

flat_model ¶

flat_model(comp_path, flat_path)

Validate a comp model and write its flat model.

The comp model is read once, validated without the units and flattened in memory; the flat model is validated with strict units. libsbml checks the units of a comp document only in its top model, not in the model definitions of the organs, so the flat model, which holds the math of every organ, is where the units are checked. The written file is checked, as create_model checks it: libsbml checks a constructed comp document differently from one it read.

The flat model depends on the content of the comp model alone, which the cache of the builds of the tests uses (tests/conftest.py).

Parameters:

Name	Type	Description	Default
`comp_path`	`Path`	the file of the comp model.	required
`flat_path`	`Path`	the file of the flat model.	required

Raises:

Type	Description
`ValueError`	if a model has SBML errors, or libsbml cannot flatten the comp model.

archive¶

The factory of a library model in one call: the files and the COMBINE archive.

A model package builds its PBPKDefinition with pkpdsim.pbpk.build and writes next to the SBML the differential equations as markdown, the antimony of the flat model, the two license texts and the COMBINE archive. create_archive does all of it, so the factory of a model is one call.

A model with a build per sex builds the one definition for every sex (sexes): the build of the sex of the definition keeps its id (<sid>.xml, <sid>_flat.xml, the master entry of the archive) and the build of another sex is the definition with that sex and the id <sid>_<sex>, e.g. <sid>_female_flat.xml next to the male <sid>_flat.xml. The model object holds both (PKPDModel(model_path=..., female_model_path=...)); its model_path is the male build, so a model with builds per sex keeps its definition male (the default), whose build is the master entry.

sex_definition ¶

sex_definition(definition, sex)

Get the definition of the build of a sex.

Parameters:

Name	Type	Description	Default
`definition`	`PBPKDefinition`	the definition of the model.	required
`sex`	`Sex`	the sex of the build.	required

Returns:

Type	Description
`PBPKDefinition`	The definition itself for its own sex, else the definition with the
`PBPKDefinition`	sex, the id `<sid>_<sex>`, e.g. `hctz_female`, and the name with the
`PBPKDefinition`	sex, `<name> (female)`.

create_archive ¶

create_archive(
    definition,
    model_output_dir,
    *,
    model,
    copyright,
    readme=None,
    extra_models=(),
    extra_files=(),
    sexes=None,
    figure=True,
)

Build a definition and write its files and the COMBINE archive.

Builds the definition into model_output_dir (build), writes the ODEs of the flat model as markdown (sbmlode) and its antimony, the texts of CC BY-SA 4.0 and MIT (with the copyright) into the parent of the directory and the archive <model>_model.omex there, with the README, the licenses, the comp model, the flat model (the master entry), the markdown, the antimony, the extra models and the extra files. With sexes every sex is built (sex_definition), each with its comp model, flat model, markdown and antimony in the archive; the flat model of the sex of the definition stays the master entry. With figure the figure of the definition (model_figure, an SVG schematic of the organs, routes, substances and processes) is written into model_output_dir as <sid>.svg and is an entry of the archive.

Parameters:

Name	Type	Description	Default
`definition`	`PBPKDefinition`	the definition of the model.	required
`model_output_dir`	`Path`	directory of the models; the licenses and the archive are written into its parent.	required
`model`	`str`	name of the model, the archive is `<model>_model.omex`.	required
`copyright`	`str`	copyright of the MIT license, e.g. `2024-2026 Matthias König`.	required
`readme`	`Path \| None`	the README of the model repository, left out of the archive if `None`.	`None`
`extra_models`	`Sequence[Path]`	further SBML files (in L3V2) which are entries of the archive, e.g. a submodel which is simulated on its own.	`()`
`extra_files`	`Sequence[Path]`	further files of other formats which are entries of the archive, e.g. the ODEs of an extra model (`.md`) or a figure (`.png`), with the format of their suffix (`EXTRA_FORMATS`, the antimony of `.ant` as the antimony of the flat model).	`()`
`sexes`	`Sequence[Sex] \| None`	the sexes to build, the sex of the definition among them and each once, e.g. `(Sex.MALE, Sex.FEMALE)`; `None` builds the sex of the definition only.	`None`
`figure`	`bool`	write the figure of the definition, `<sid>.svg` (the key `<sid>_svg`); one figure for all sexes, which have the same organs, substances and processes, its title names the builds.	`True`

Every file of the archive has one location rule: it is below the parent of model_output_dir, and its location in the archive is its path relative to it. The built models, their markdown and antimony are in model_output_dir (./models/<name> for the directory models of a model package), the licenses in the parent (./mit.txt), an extra model or file where it lies (./models/<sid>_fluid.xml, ./figures/<x>.png). The README alone is placed, as ./README.md of the archive, wherever the file lies.

Raises:

Type	Description
`ValueError`	if the stem of an extra model or the key of an extra file is the key of another entry, if an extra model or file is not below the parent of `model_output_dir` or the suffix of an extra file has no format, or if `sexes` leaves out the sex of the definition or names a sex twice (before anything is written).

Returns:

Name	Type	Description
	`dict[str, dict[str, Any]]`	The files with their entries in the COMBINE archive, by the keys of a
`factory`	`dict[str, dict[str, Any]]`	`README`, `cc-by`, `mit`, the sid of the definition, `<sid>_flat`,
	`dict[str, dict[str, Any]]`	`<sid>_flat_md`, `<sid>_flat_ant` (and the same keys of the id of the
	`dict[str, dict[str, Any]]`	build of every other sex, `<sid>_female_flat`), `<sid>_svg` of the
	`dict[str, dict[str, Any]]`	figure, the stem of every
	`dict[str, dict[str, Any]]`	extra model and `<stem>_<suffix>` of every extra file (`fluid_md`),
	`dict[str, dict[str, Any]]`	each `{"path": Path, "entry": ManifestEntry}`.

figure¶

The figure of a model: an SVG schematic of a definition.

model_figure(definition, path) draws the body of a definition as the COMBINE archive of a model carries it (create_archive(..., figure=True)):

the title, the substances (a chip in the color of the substance, its name and its mechanisms: binding, erythrocytes, distribution, baseline (an endogenous substance: with a given baseline, or produced with the baseline solved by the library), inhibitions and inductions), the routes, the PD components and the key;
the circulation: the venous blood on the left, the arterial blood on the right, the lung in series between them, the organs which the arterial blood perfuses and which drain into the venous blood, the liver with the hepatic artery and the portal vein, and the organs which drain into the portal vein; the variant of an organ is named under it;
in every organ a chip per substance, filled where the substance enters the tissue of the organ, dashed where it stays in the plasma, and the processes of the organ as badges: metabolism (MET, substrate, products and enzyme), transport (TRA, the side and the transporter), custom reaction (CUS, its equation), the excretion into the urine (URI, with the reabsorption), the slow pool (SLW, the exchange with its source, the tissue or the plasma);
the lumen of the intestine: its segments in the order of the transit to the feces, the oral routes (ORL), the absorption (ABS), the bile (BIL), the conversions in the lumen (CNV) and the feces (FEC).

The figure is pure python and deterministic: the same definition gives the same bytes. Its text is monospace and every label is placed by its width at CHAR_WIDTH per character, an upper bound of the advance of the monospace fonts it names (DejaVu Sans Mono 0.602 em), so a label stays inside its box and labels do not overlap, also with many substances: a row grows by lines instead of running out of its box.

CHAR_WIDTH `module-attribute` ¶

CHAR_WIDTH = 0.62

The width of a character in units of the font size: an upper bound of the advance of the monospace fonts of FONT (DejaVu Sans Mono and Liberation Mono 0.6 em, Menlo 0.602 em, Consolas 0.55 em).

FONT `module-attribute` ¶

FONT = "'DejaVu Sans Mono', Menlo, Consolas, 'Liberation Mono', monospace"

The fonts of the figure, monospace, so that CHAR_WIDTH bounds every label.

WIDTH `module-attribute` ¶

WIDTH = 1200

The width of the figure (px).

model_figure ¶

model_figure(definition, path, sexes=None)

Write the figure of a definition, an SVG schematic of the model.

The circulation with the organs, the substances in each organ, the routes and the processes (see the module), deterministic and without a dependency beyond the library. The builds of the sexes have the same organs, substances and processes, so one figure shows them all; its title names the builds (male build, male and female builds).

Parameters:

Name	Type	Description	Default
`definition`	`PBPKDefinition`	the definition of the model.	required
`path`	`Path`	the SVG file to write.	required
`sexes`	`Sequence[Sex] \| None`	the sexes which are built (`create_archive(..., sexes=...)`), the sex of the definition among them; `None` is the sex of the definition only.	`None`

Returns:

Type	Description
`Path`	The path of the figure.

Raises:

Type	Description
`ValueError`	if `sexes` leaves out the sex of the definition or names a sex twice.

slow_pool¶

The slow (deep) pool of a tissue.

A substance whose terminal phase is the slow release from a deep compartment of the tissues (a marker of the extracellular volume, a contrast agent in the days after a dose) has in each organ of the pool the species Cslow_<s> in the tissue compartment Vti and its exchange with the merged tissue (source=Part.TISSUE, the default),

J_slow_<s>: Cti_<s> <-> Cslow_<s> = kslow_<s> * Vti * (Kpslow_<s> * Cti_<s> - Cslow_<s>)

or with the plasma of the organ (source=Part.PLASMA), in parallel with the merged tissue: a deep extracellular space which the substance reaches through the capillary wall, not through the fast interstitium,

J_slow_<s>: Cpl_<s> <-> Cslow_<s> = kslow_<s> * Vti * (Kpslow_<s> * Cpl_<s> - Cslow_<s>)

with the exchange kslow_<s> per litre of tissue (1/min) in both forms, so the exchange of an organ follows the tissue volume of the individual, as the share of ftissue does, and the coefficient Kpslow_<s> of the pool to its source: at equilibrium Cslow = Kpslow*Cti (Cslow = Kpslow*Cpl), the pool holds Kpslow times the concentration of its source in the tissue volume. Both are constants of the top model, one value for every organ of the pool, which a fit changes.

The plasma form reads the total plasma concentration, as the Kp of a tissue does: Kpslow_<s> is relative to the total plasma and the rate has no fu, so a change of fu (the CKD profile of the binding) changes neither the equilibrium nor the rate of the pool of a bound substance.

SOURCES `module-attribute` ¶

SOURCES = (Part.TISSUE, Part.PLASMA)

What a slow pool exchanges with: the merged tissue or the plasma of the organ.

OrganCollection ¶

OrganCollection = (
    frozenset[Organ | str]
    | set[Organ | str]
    | list[Organ | str]
    | tuple[Organ | str, ...]
)

The organs as SlowPool.organs takes them: a frozenset, set, list or tuple of Organ members, values or names (as_organs).

SlowPool `dataclass` ¶

SlowPool(substance, organs, k, kp, source=TISSUE)

The slow (deep) pool of the tissue of a substance in some organs.

Attributes:

Name	Type	Description
`substance`	`str`	the id of the substance.
`organs`	`OrganCollection`	the organs with a pool, standard organs in which the substance has the merged tissue (`Mode.TISSUE`); a frozenset, set, list or tuple of members, values or names (`OrganCollection`), normalised to a frozenset of `Organ` members in `__post_init__`, which is what the field holds afterwards.
`k`	`Q`	the exchange between the tissue and the pool per litre of tissue (1/min), `kslow_<s>`: a number, a `Value` (fitted) or a `Formula`.
`kp`	`Q`	the concentration of the pool to that of its source at equilibrium (dimensionless), `Kpslow_<s>`.
`source`	`Part \| str`	what the pool exchanges with (`SOURCES`): the merged tissue `Cti_<s>` (`Part.TISSUE`, the default) or the plasma of the organ `Cpl_<s>` (`Part.PLASMA`, a deep space reached through the capillary wall in parallel with the merged tissue); a member, value or name, normalised to the `Part` member in `__post_init__`.

check_slow_pools ¶

check_slow_pools(pools, known)

Check the slow pools of a definition, each on its own.

A known substance, one pool per substance (its constants are shared by its organs), at least one organ, the tissue or the plasma as its source (SOURCES), k and kp positive in their units. That every organ is a standard organ in which the substance has the merged tissue is checked by PBPKDefinition.validate.

Parameters:

Name	Type	Description	Default
`pools`	`Iterable[SlowPool]`	the slow pools.	required
`known`	`set[str]`	the ids of the substances of the definition.	required

Returns:

Type	Description
`list[str]`	The problems, naming the substance.

pbpk¶

definition¶

Variants dataclass ¶

PBPKDefinition dataclass ¶

combine classmethod ¶

parameter_value ¶

validate ¶

substance¶

Binding dataclass ¶

Erythrocytes dataclass ¶

Mode ¶

PERFUSION class-attribute instance-attribute ¶

TISSUE class-attribute instance-attribute ¶

PERMEABILITY class-attribute instance-attribute ¶

Kp dataclass ¶

KpMethod dataclass ¶

ThresholdReabsorption dataclass ¶

Excretion dataclass ¶

Substance dataclass ¶

chemistry¶

REST module-attribute ¶

LINEAR module-attribute ¶

Fraction ¶

Stationary ¶

RateOf dataclass ¶

Rest ¶

FirstOrder dataclass ¶

MM dataclass ¶

Hill dataclass ¶

Direction ¶

Membrane ¶

BASOLATERAL class-attribute instance-attribute ¶

APICAL class-attribute instance-attribute ¶

Metabolism dataclass ¶

Transport dataclass ¶

Saturable dataclass ¶

CustomReaction dataclass ¶

check_kinetics ¶

check_rate_of ¶

check_products ¶

fraction_range ¶

check_stationary ¶

check_custom_parameters ¶

proteins¶

PROTEINS module-attribute ¶

Protein dataclass ¶

Inhibition dataclass ¶

Induction dataclass ¶

load_proteins ¶

turnover ¶

routes¶

ORAL module-attribute ¶

Formulation ¶

FirstOrderDissolution dataclass ¶

WeibullDissolution dataclass ¶

DoseDependentDissolution dataclass ¶

Route dataclass ¶

iv classmethod ¶

oral classmethod ¶

oral_solution classmethod ¶

dissolution_inputs ¶

dissolution_reads_fed ¶

is_weibull ¶

dissolution_rate ¶

route_objects ¶

pd¶

PDComponent dataclass ¶

ports ¶

builder¶

BuildResult dataclass ¶

organ_component ¶

built_organs ¶

organ_context ¶

compose ¶

observer_problems ¶

build ¶

flat_model ¶

archive¶

sex_definition ¶

create_archive ¶

Variants `dataclass` ¶

PBPKDefinition `dataclass` ¶

combine `classmethod` ¶

Binding `dataclass` ¶

Erythrocytes `dataclass` ¶

PERFUSION `class-attribute` `instance-attribute` ¶

TISSUE `class-attribute` `instance-attribute` ¶

PERMEABILITY `class-attribute` `instance-attribute` ¶

Kp `dataclass` ¶

KpMethod `dataclass` ¶

ThresholdReabsorption `dataclass` ¶

Excretion `dataclass` ¶

Substance `dataclass` ¶

REST `module-attribute` ¶

LINEAR `module-attribute` ¶

RateOf `dataclass` ¶

FirstOrder `dataclass` ¶

MM `dataclass` ¶

Hill `dataclass` ¶

BASOLATERAL `class-attribute` `instance-attribute` ¶

APICAL `class-attribute` `instance-attribute` ¶

Metabolism `dataclass` ¶

Transport `dataclass` ¶

Saturable `dataclass` ¶

CustomReaction `dataclass` ¶

PROTEINS `module-attribute` ¶

Protein `dataclass` ¶

Inhibition `dataclass` ¶

Induction `dataclass` ¶

ORAL `module-attribute` ¶

FirstOrderDissolution `dataclass` ¶

WeibullDissolution `dataclass` ¶

DoseDependentDissolution `dataclass` ¶

Route `dataclass` ¶

iv `classmethod` ¶

oral `classmethod` ¶

oral_solution `classmethod` ¶

PDComponent `dataclass` ¶

BuildResult `dataclass` ¶

CHAR_WIDTH `module-attribute` ¶

FONT `module-attribute` ¶

WIDTH `module-attribute` ¶

SOURCES `module-attribute` ¶

SlowPool `dataclass` ¶