Skip to content

pbpk physiology

The physiology of the PBPK library: the reference physiology and its scaling, the populations, the impairment, the observers and the sinks, see Physiology, Impairment and Observers.

physiology

The standard human physiology and its scaling to an individual.

The physiology is a set of SBML parameters of the top model. The covariates of the individual (BW, HEIGHT, AGE) and the factors of organ function are constant parameters which an experiment changes before the simulation, as it changes BW today; everything else follows from them by initial assignments on constant parameters, which sbmlsim evaluates again after the changes of an experiment (a value which no rule recomputes during the integration keeps the compiled model small and fast to load):

  • the reference values of the sex of the build (ICRP 89, data/physiology_human.toml); the sex is chosen when the model is built, a study of both sexes uses one model per sex;
  • the default individual (BW, HEIGHT, AGE) is the reference individual of the sex of the population of the build (pkpdsim.pbpk.populations, ICRP 89 by default); the reference anatomy stays ICRP 89 for every population, the organs of another population's individual follow from the scaling;
  • body mass index, body surface area (Du Bois 1916) and fat-free mass (Janmahasatian 2005);
  • the tissues scale as in Huisinga 2012 (eqs. 9, 10, 12): brain is constant, skin scales with the body surface area, the other lean organs and the blood with the fat-free mass less brain and skin (SV_tis); adipose is the remainder of the body weight;
  • the cardiac output scales as the tissues, SV_tis (Huisinga 2012 eq. 13), and the organ flows are fractions of it, renormalised over the organs so that they sum to the cardiac output;
  • the GFR scales with the body surface area.

An organ volume is the volume of its tissue and its blood, M<o>/density + blood*Vblood; the body weight is the mass of the tissues without blood and of the blood, sum(M<o>) + Vblood*rho_blood. The vascular fraction of an organ volume is its blood, blood*Vblood/V<o>, so that the vascular spaces of the organs and the pools are the blood volume for every individual; the interstitial fraction is the interstitial fraction of the tissue without blood (Schmitt 2008) times the tissue share 1 - f_vas.

A covariate or a factor of organ function is an initial value: changed before the simulation (a change of an experiment, init(...) in roadrunner), every quantity which depends on it follows; changed during a simulation, nothing follows (unless the definition names it dynamic, see pkpdsim.pbpk.builder).

The impaired organ function (pkpdsim.pbpk.impairment) multiplies cardiac output, the blood flows, the GFR, the hematocrit and the kidney mass by its factors (factors of physiology_objects); without them the physiology is the healthy one.

LEAN_ORGANS module-attribute

LEAN_ORGANS = tuple(
    o for o in Organ if o is not Organ.ADIPOSE
)

The organs whose tissue mass scales with the individual; adipose is the rest.

DEFAULT_POPULATION module-attribute

DEFAULT_POPULATION = 'european_icrp'

The population of a model which does not choose one (pkpdsim.pbpk.populations).

AGE_DEFAULT module-attribute

AGE_DEFAULT = 40.0

The age of an individual if an experiment does not set it (yr).

MODEL_DEFAULT module-attribute

MODEL_DEFAULT = 'Model default without a source.'

The notes of a parameter whose value is a choice of the model, not data.

LIVER_DEFAULTS module-attribute

LIVER_DEFAULTS = {ids.F_SHUNT: 0.0, ids.F_FUNCTIONAL: 1.0}

The healthy liver: no portosystemic shunt, all tissue functional. The values at runtime are those of the hepatic impairment (pkpdsim.impairment), which sets them as an experiment sets a covariate.

Sex

Bases: StrEnum

The sex of a model build, the sex of its reference individual.

ReferenceIndividual dataclass

ReferenceIndividual(
    sex,
    bw,
    height,
    gfr,
    volumes,
    tissue_volumes,
    intracellular_volumes,
    lumen_volumes,
)

The reference individual of a sex (ICRP 89, data/physiology_human.toml).

The individual whose anatomy the physiology scales, the default individual of the populations of ICRP 89: a model which states a value of the hand-written models per litre of an organ or per kg of body weight converts it with these numbers instead of copies of them.

Attributes:

Name Type Description
sex Sex

the sex.

bw float

the body weight [kg], BW of the default individual.

height float

the height [cm], HEIGHT of the default individual.

gfr float

the healthy GFR [l/min], the GFR at renal function 1 of the default individual (GFR_base, the reference GFR GFR_ref of the sex at its own body surface area), which healthy_gfr of the build of the sex gives in ml/min; the GFR of a component which a model keeps outside the library (the fluid model of hctz) reads it instead of a copy.

volumes Mapping[Organ, float]

the organ volumes with their blood V<o> [l], M<o>/density + blood*Vblood as in the model.

tissue_volumes Mapping[Organ, float]

the tissue volumes without blood [l] (reference_tissue_volumes).

intracellular_volumes Mapping[Organ, float]

the volumes of the cells of the organs [l], V<o>*(1 - f_vas_<o> - f_int_<o>) as in the model (the tissue volume without its interstitial fraction), the intracellular space Vic of the full form (the hepatocytes of the liver, 1.3859 l of a man).

lumen_volumes Mapping[str, float]

the fluid volumes of the lumen segments of the segmented intestine by their token (ids.GUT_SEGMENTS) [l], Vlumen_<seg>, the same for both sexes (the small intestine du to ile2 0.105 l).

physiology_objects

physiology_objects(
    sex=MALE, factors=None, population=DEFAULT_POPULATION
)

The parameters and initial assignments of the standard human physiology.

Parameters:

Name Type Description Default
sex Sex

the sex of the model: its reference values and the default individual (BW, HEIGHT). A study of both sexes uses one model per sex.

MALE
factors Mapping[str, str] | None

the factors of the impaired organ function by the id of the quantity they multiply (pkpdsim.pbpk.impairment.physiology_factors): the formula of the quantity is multiplied by the factor (a formula); the hematocrit becomes HCT = HCT_ref * factor. None: the healthy physiology.

None
population str

the population (pkpdsim.pbpk.populations) whose reference individual of the sex is the default individual (BW, HEIGHT, AGE); the reference anatomy stays ICRP 89.

DEFAULT_POPULATION

Returns:

Type Description
list[Sbase]

The constant parameters and their initial assignments of the top model.

Raises:

Type Description
ValueError

if the reference individual leaves no mass for adipose, a unit of the data is not the unit of the model, a factor names no quantity of the physiology with an initial assignment, or the population is unknown.

reference_fractions

reference_fractions(organ)

The vascular and interstitial fraction of an organ volume of the reference individuals.

Parameters:

Name Type Description Default
organ Organ

the organ.

required

Returns:

Type Description
dict[Sex, tuple[float, float]]

(f_vas, f_int) of physiology_human.toml by sex.

normal_gfr

normal_gfr(sex)

The GFR per 1.73 m2 body surface area of a reference individual.

Parameters:

Name Type Description Default
sex Sex

the sex of the reference individual.

required

Returns:

Type Description
float

The reference GFR scaled to 1.73 m2 with the reference body surface

float

area (l/min), the GFR of the normal renal function.

reference_tissue_volumes

reference_tissue_volumes(sex)

The tissue volumes of the organs of a reference individual.

The tissue volume of an organ is its volume without its blood, V<o>*(1 - f_vas_<o>) = M<o>/density; adipose is the remainder of the body weight, as in the model.

Parameters:

Name Type Description Default
sex Sex

the sex of the reference individual.

required

Returns:

Type Description
dict[Organ, float]

The tissue volume (l) by organ.

reference_hematocrit

reference_hematocrit(sex)

The hematocrit of a reference individual.

Parameters:

Name Type Description Default
sex Sex

the sex of the reference individual.

required

Returns:

Type Description
float

The hematocrit of physiology_human.toml.

reference_individual cached

reference_individual(sex)

The reference individual of a sex.

Parameters:

Name Type Description Default
sex Sex

the sex of the reference individual.

required

Returns:

Type Description
ReferenceIndividual

Its body weight, height, healthy GFR, organ, cell and lumen volumes.

populations

The populations: the reference individual and the distributions of the covariates.

A population is a set of data of the library (data/populations/<key>.toml): the reference covariates of each sex (body weight, height and, where the data give it, the age), which become the default individual of a model, and the distributions of the covariates for a later sampler of virtual individuals. The reference anatomy stays ICRP 89 (data/physiology_human.toml): the organ volumes and flows of a population's reference individual follow from the covariate scaling of pkpdsim.pbpk.physiology (Huisinga 2012) at its body weight and height. The population is chosen when the model is built (PBPKDefinition.population), the European reference individuals of ICRP 89 are the default.

The distributions are data of the library and never SBML distrib uncertainties: run_simulation --uncertainty draws every parameter with a distrib uncertainty and must only draw the uncertainty of a fit.

The populations:

  • european_icrp: the ICRP 89 reference individuals (the default); ICRP 89 gives reference values, not distributions, so the population has none;
  • white_american_nhanes, black_american_nhanes, mexican_american_nhanes: adults of 20 to 49 years of the NHANES examinations 2013-2018 as preprocessed by httk (HTTK-Pop, Ring 2017), survey-weighted means and standard deviations;
  • east_asian_tanaka: the Asian Reference Man of Tanaka 1996 (Tables 9 and 10, 20 to 49 years) with the distributions of the Japanese of the same tables.

PK-Sim also offers a Japanese population (based on Japanese national statistics of 2015). Its primary data were not read, so the library has no japanese population; the Japanese data of Tanaka 1996 (1976 to 1988) are the distributions of east_asian_tanaka.

DEFAULT_POPULATION module-attribute

DEFAULT_POPULATION = 'european_icrp'

The population of a model which does not choose one (pkpdsim.pbpk.populations).

COVARIATES module-attribute

COVARIATES = (ids.BW, ids.HEIGHT, ids.AGE)

The covariates a population gives reference values for.

POPULATIONS module-attribute

POPULATIONS = _populations()

The populations by key.

Distribution dataclass

Distribution(kind, mean, sd, unit, source, notes=None)

The distribution of a covariate in a population.

Attributes:

Name Type Description
kind Literal['normal', 'lognormal']

normal or lognormal; the mean and the standard deviation are those of the covariate itself (not of its logarithm) for both.

mean float

the mean.

sd float

the standard deviation.

unit UnitDefinition

the unit of mean and standard deviation.

source str

the key of the source in data/sources.toml.

notes str | None

where the numbers come from.

Population dataclass

Population(key, name, source, reference, covariates)

A population: the reference individual and the covariate distributions per sex.

Attributes:

Name Type Description
key str

the key of the population, PBPKDefinition.population.

name str

the name.

source str

the key of the source of the population in data/sources.toml.

reference Mapping[Sex, Mapping[str, Value]]

the reference covariates (BW, HEIGHT, AGE) of each sex, the default individual of a model.

covariates Mapping[Sex, Mapping[str, Distribution]]

the distributions of the covariates of each sex.

population

population(key)

Get a population.

Parameters:

Name Type Description Default
key str

the key of the population.

required

Returns:

Type Description
Population

The population.

Raises:

Type Description
ValueError

if there is no population of the key.

impairment

The impaired organ function: parameter vectors on the physiology.

Impairment is never a structurally different model: three severities of the top model set factors on the quantities of the healthy physiology, the liver and the binding to plasma proteins (data/impairment.toml, every number with its source; a value which no publication read gives is a model choice):

  • CP_severity: liver cirrhosis, 0 healthy, 1, 2, 3 the Child-Pugh classes A, B, C; a severity between the classes interpolates every factor linearly (scans and fits use intermediate values). It sets the functional fraction f_functional and the portosystemic shunt f_shunt of the liver, the hepatic arterial and the renal blood flow, the cardiac output (cardiac index; the organs without a factor of their own close the cardiac output to it), the GFR, albumin and alpha-1-acid glycoprotein (and so fu) and the activity of the enzymes and transporters of the liver.
  • f_renal_function: chronic kidney disease by the GFR relative to healthy (the factor of the physiology); its GFR per 1.73 m2 (eGFR) gives the stage (normal, mild, moderate, severe, end stage), which sets the binding capacity of the plasma proteins (and so fu). The factors are piecewise linear in the eGFR through anchor points at the stage midpoints ([ckd] stage_anchor of the data, a model choice: continuous covariate for scans and fits; stage midpoints): 1 from 90 ml/min/1.73 m2, the mild value at 75, the moderate value at 45, the severe value at 22.5 and the end stage value at 7.5 and below, linear in between (from 90 to 75 from 1 to the mild value), so a scan or fit of f_renal_function sees no step. The binding to albumin and alpha-1-acid glycoprotein follows the CKD profile of its protein ([ckd.binding] of the data): albumin falls in concentration and in the binding function of its molecule, AAG rises in concentration; the binding to an unknown protein follows the binding capacity of the plasma proteins (plasma_protein). The switch CKD_hepatic (0 off, 1 on) adds the reduced activity of hepatic CYP2D6 and OATP1B. The tubular capacity of the kidney (every metabolism and transport of the kidney) follows f_renal_function continuously, 1 - f_tubular + f_tubular*f_renal_function with the share f_tubular 1 of the intact nephron hypothesis ([ckd] tubular_capacity of the data, a model choice; the kidney owns the factor, pkpdsim.pbpk.organ).
  • HF_severity: heart failure, 0 healthy, 1 to 4 the NYHA classes I to IV, interpolated: the blood flows of liver and portal organs, kidney and skin, adipose and muscle are reduced, the cardiac output is the sum of the flows, the GFR follows the renal blood flow (which is not monotonic in the class, NYHA IV above NYHA III, as measured by Leithe 1984).

The hematocrit (anaemia of cirrhosis and CKD, combined multiplicatively on the hematocrit of the sex of the build), the kidney volume and blood flow and the gastric emptying and small intestinal transit of CKD have their factors, which are 1 until a publication with the healthy reference is read (the data say why).

Each condition has its factors fcp_<key>, fckd_<key>, fhf_<key>; the factor of all conditions on a quantity is fimp_<id> (fimp_GFR, fimp_Qki, fimp_HCT), their product. Blood flows: every organ flow is its fraction of the cardiac output without impairment (CO_base) times fimp_Q<o>, and the cardiac output is CO_base times fimp_CO = sum fQ<o>*fimp_Q<o>, so the flows sum to it. Plasma binding (McNamara 2002): fu = 1/(1 + f*(1 - fu_ref)/fu_ref) with the binding factor f, the factor of the binding protein in cirrhosis (fimp_albumin, fimp_agp, 1 for an unknown protein) times the CKD factor of the binding: the CKD profile of the protein (fimp_albumin_ckd, fimp_agp_ckd, the product of its rows of [ckd.binding]), for an unknown protein one over the factor of the binding capacity fimp_plasma_protein (fu of a strongly bound substance rises by it). fu stays below 1. A binding with ckd=False (measured unchanged in renal impairment) leaves out the CKD factor, so f is the factor of the binding protein alone. The parameters of the CKD profile of a protein are created only when a substance binds to it with the CKD factor. Enzymes and transporters: a rate of a protein in the liver runs with f_<protein>*fimp_<protein>, the organ-local base activity (genotype, interactions of an experiment, LI__f_cyp3a4) times the input fimp_<protein> of the impairment (fimp_li_<protein> of the body), so both act multiplicatively.

All are initial assignments (pkpdsim.pbpk.physiology): set the severities before the simulation, as a covariate; a severity which changes during a simulation is named in PBPKDefinition.dynamic. f_shunt and f_functional stay parameters an experiment may set directly. All severities 0 give the healthy model: every factor is 1.

DATA module-attribute

DATA = 'impairment'

The data file of the impairment.

GASTRIC_EMPTYING module-attribute

GASTRIC_EMPTYING = ids.impairment_factor('t_stomach')

The factor on the transit time of the stomach, an input of the intestine.

SI_TRANSIT module-attribute

SI_TRANSIT = ids.impairment_factor('t_si')

The factor on the transit times of the small intestine, an input of the intestine.

organ_activity

organ_activity(organ, protein)

Get the local input of the impairment on a protein in an organ.

Parameters:

Name Type Description Default
organ Organ

the organ.

required
protein str

the protein of a process of the organ.

required

Returns:

Type Description
str | None

fimp_<protein> in the liver for a protein with data of impairment,

str | None

replaced by fimp_li_<protein> of the body; None elsewhere.

physiology_factors

physiology_factors()

Get the factors of the impairment on the quantities of the physiology.

Returns:

Type Description
dict[str, str]

The factor (formula) by the id of the quantity it multiplies, for

dict[str, str]

pkpdsim.pbpk.physiology.physiology_objects: the cardiac output (the

dict[str, str]

sum of the impaired flows), the flows, the GFR (at renal function 1,

dict[str, str]

GFR_base), the hematocrit and the

dict[str, str]

kidney mass.

unbound_fraction_notes

unbound_fraction_notes(s)

Get the notes of the fraction unbound in plasma of a substance.

The notes say what unbound_fraction gives: the reference fraction scaled with the binding protein under impairment, scaled with the binding capacity of chronic kidney disease alone (an unknown protein with the CKD factor), the reference fraction itself where no factor applies (an unknown protein without the CKD factor), or no binding.

Parameters:

Name Type Description Default
s Substance

the substance.

required

Returns:

Type Description
str

The notes of fu_<s>.

unbound_fraction

unbound_fraction(s)

Get the formula of the fraction unbound in plasma of a substance under impairment.

Parameters:

Name Type Description Default
s Substance

the substance.

required

Returns:

Type Description
str

fu_ref_<s> for a substance without binding, else the McNamara 2002

str

scaling 1/(1 + f*(1 - fu_ref)/fu_ref) with the binding factor f:

str

the factor of the binding protein in cirrhosis times the CKD profile

str

of the protein (fimp_albumin_ckd, fimp_agp_ckd); an unknown

str

protein has no factor of cirrhosis and its CKD factor is one over the

str

factor of the binding capacity fimp_plasma_protein, which raises fu

str

of a strongly bound substance by itself

str

(fu ~ fimp_plasma_protein*fu_ref), fu stays below 1; fu of a weakly

str

bound substance rises less (fu_ref 0.5 at a factor 2.5: 0.71, not

str

1.25). A binding with ckd=False has the factor of the binding

str

protein alone; with an unknown protein as well no factor applies and

str

the result is fu_ref_<s> itself.

ckd_unbound_fractions

ckd_unbound_fractions(s)

Get the fraction unbound of a substance at the CKD stages.

The fu of unbound_fraction without cirrhosis at the values of the stages mild, moderate, severe and end stage of the CKD factor of its binding (the profile of its protein, [ckd.binding], or one over the factor of the binding capacity plasma_protein of an unknown protein): the factors are linear in the eGFR between the anchors of the stages and constant below the end stage, so the fu of every renal function lies between these values (and the reference fu of renal function 1).

Parameters:

Name Type Description Default
s Substance

the substance.

required

Returns:

Type Description
dict[str, float]

The fu by stage; empty for a substance whose fu CKD does not change

dict[str, float]

(no binding, ckd=False) or whose fu is a Formula.

impairment_objects

impairment_objects(definition)

Get the parameters of the impaired organ function of the top model.

Parameters:

Name Type Description Default
definition PBPKDefinition

the definition (the proteins of the liver).

required

Returns:

Type Description
list[Sbase]

The severities, the factors of every condition and of all conditions

list[Sbase]

(initial assignments) and the initial assignments of f_shunt and

list[Sbase]

f_functional; the physiology reads the factors through

list[Sbase]

physiology_factors.

observers

The observers of a PBPK model: assignment rules of the top model, no states.

An observer reads the pool species and the outflow concentrations of the organs and changes nothing, so it conserves mass. Per substance <s>:

  • C<pool>_free_<s> = fu*C<pool>_<s>, the unbound plasma concentration of a pool (ar, ve, po);
  • C<pool>_blood_<s>, the blood concentration of a pool, (1-HCT)*C + HCT*C_bc: BP*C unless the blood cells are kinetic;
  • Chv_<s>, the hepatic vein: the outflow of the liver mixed with the portosystemic shunt by their flows, ((1-f_shunt)*Qh*Cout_li + f_shunt*(Qha*Car + Qpo*Cpo))/Qh, with Chv_free_<s> and Chv_blood_<s>;
  • Carm_<s> = sum w*C, the arm vein (peripheral venous) sampling site: the venous plasma outflows of organs and the arterial plasma mixed with the weights w_arm_<site> of a preset of data/arm_vein.toml (PBPKDefinition.arm_vein, by default the mix of skin and muscle of the PK-Sim documentation); Carm_free_<s> and Carm_blood_<s> as for the pools.

The tissue concentrations are the species of the organs themselves, their unbound concentrations Cu_<part>_<s> observers of the organs, the amounts in urine and feces the sink species, the urinary excretion rate Rurine_<s> an output of the kidney.

A definition adds observers of its own (Observer, PBPKDefinition.observers, e.g. the sum of two metabolites): parameters of the top model over the ids of the top model, appended after the observers of the library. An observer names a species or an unbound concentration of an organ by its flat id (MU__Cti_<s>, LI__Cu_ic_<s>, an amount MU__A<x>), which the organ exposes as a PD input is exposed (pkpdsim.pbpk.builder). An observer which reads a state, directly or through other observers (a species, an observer of the library, an output of an organ or a PD component, a dynamic parameter, time), is an assignment rule; an observer of constants only is a constant with an initial assignment, evaluated after the changes before the simulation (an assignment rule of constants would slow the compile of the model).

The intestine adds readouts on request (PBPKDefinition.readouts, intestine_readouts): the dissolved amount in its lumen Alumen_<s> and the summed fluxes of the absorption Rabs_<s>, the efflux into the lumen Reff_<s> and the loss to the feces Rfeces_<s>, outputs of the intestine as Rurine_<s> is one of the kidney.

TIME module-attribute

TIME = 'time'

The symbol of the simulation time in the symbols of a formula.

Observer dataclass

Observer(sid, formula, unit, name, notes=None)

An observer of a definition: a parameter of the top model with its formula.

Attributes:

Name Type Description
sid str

the id of the observer, an id of the top model.

formula str

the formula (SBML L3 infix) over the ids of the top model: the pools, the sinks, the observers of the library and of the definition, the covariates, the outputs of the organs, the readouts; and a species or an unbound concentration of an organ by its flat id (MU__Cti_<s>), which the organ exposes.

unit UnitDefinition

the unit of the formula; a unit which is no unit of U (the unit per body surface area ML_PER_MIN_1P73M2) is a unit definition of the model.

name str

the name of the observer.

notes str | None

the notes of the observer.

OrganOutput dataclass

OrganOutput(unit, name, kind, text, constant=False)

An output of an organ which replaces the parameter of the top model of its id.

The parameter is created by the composition (pkpdsim.pbpk.builder): an element of an organ which a PD component or an observer reads, a readout of the intestine.

Attributes:

Name Type Description
unit UnitType

the unit of the parameter.

name str

the name of the parameter.

kind str

the kind of its annotation (pkpdsim.pbpk.annotation.KINDS).

text str

the start of its notes, followed by organ <organ>, replaced by the output of the organ.

constant bool

the output is a constant of the organ (a constant of the generated steady state), not an assignment rule.

formula_symbols

formula_symbols(formula)

Get the ids a formula reads, with libsbml's parser of SBML L3 infix.

Parameters:

Name Type Description Default
formula str

the formula; the units of its numbers (1 dimensionless) and the names of its functions are no ids.

required

Returns:

Type Description
set[str]

The ids of the formula, time for the simulation time.

Raises:

Type Description
ValueError

if the formula cannot be parsed, with the message of libsbml.

formula_functions

formula_functions(formula)

Get the functions a formula calls which are no functions of SBML L3 infix.

Such a call (foo(x)) reads a function definition of the model; the models of the library define none.

Parameters:

Name Type Description Default
formula str

the formula.

required

Returns:

Type Description
set[str]

The names of the called functions which are no built-in functions

set[str]

(exp, piecewise, ...).

Raises:

Type Description
ValueError

if the formula cannot be parsed, with the message of libsbml.

definition_observer_objects

definition_observer_objects(observers, constant=())

Get the parameters and the rules of the observers of a definition.

The ids, the symbols of the formulas and whether an observer reads a state are checked when the model is composed (pkpdsim.pbpk.builder).

Parameters:

Name Type Description Default
observers Iterable[Observer]

the observers of the definition, their formulas over the ids of the top model.

required
constant Collection[str]

the ids of the observers which read constants only: a constant with an initial assignment, every other observer an assignment rule.

()

Returns:

Type Description
list[Sbase]

The parameters with their assignment rules or initial assignments,

list[Sbase]

annotated as observers.

readout_ids

readout_ids(substances)

Get the ids of the readouts of the intestine of substances.

Parameters:

Name Type Description Default
substances Iterable[str]

the substance ids.

required

Returns:

Type Description
dict[str, tuple[str, str]]

By readout id (Alumen_<s>, Rabs_<s>, Reff_<s>, Rfeces_<s>,

dict[str, tuple[str, str]]

Aabs_<s>, Fa_<s>), what it sums (lumen, absorption, efflux,

dict[str, tuple[str, str]]

feces, absorbed, fraction) and its substance.

intestine_readouts

intestine_readouts(md, readouts, substances)

Add the readouts of a definition to the model definition of its intestine.

Every readout is a parameter of the intestine with its assignment rule and an output port, which replaces the parameter of its id in the top model, as the urinary excretion rate of the kidney does. The sums are taken over the species and the reactions of the intestine, so that they hold for every intestine with a lumen (segmented, single lumen):

  • Alumen_<s>: the dissolved amount in the lumen, sum V*C of the lumen species Clumen_<seg>_<s> (mmole);
  • Rabs_<s>: the fluxes from a lumen species into the wall of the substance (the mucosa Cmu_<seg>_<s>, else a species of the wall), the absorption and an apical influx (mmole/min);
  • Reff_<s>: the fluxes from the wall into the lumen, the apical efflux (mmole/min);
  • Rfeces_<s>: the net flux of the intestine into the feces Afeces_<s> (mmole/min); with an intestine with a lumen every flux into the feces is one of the intestine, so it integrates to Afeces_<s>;
  • Aabs_<s>: the amount absorbed since the start, the integral of the fluxes of Rabs_<s>, a state of the intestine (mmole);
  • Fa_<s>: the gross absorbed fraction of the oral dose, Aabs_<s> over the oral dose given until then (the dose states PODOSE_<s> and SOLDOSE_<s> over Mr_<s> plus what the intestine applied of them, the state Aapp_<s>), 0 before a dose: before the first pass of the wall and the liver, so above the bioavailability; the absorption of a substance which reaches the lumen otherwise (the bile, an efflux) counts as well, so it can exceed 1.

Aabs_<s> and Aapp_<s> are states which nothing drains (accumulating states, which the equilibration sets back as it sets back the sinks).

Parameters:

Name Type Description Default
md ModelDefinition

the model definition of the intestine, changed in place.

required
readouts Sequence[str]

the readouts of the definition (PBPKDefinition.readouts).

required
substances Iterable[str]

the substance ids of the definition.

required

Returns:

Type Description
dict[str, OrganOutput]

The outputs by id.

Raises:

Type Description
ValueError

naming a readout of a substance without lumen species, or whose sum has no flux.

arm_vein_weights

arm_vein_weights(preset)

Get the weights of a preset of the arm vein.

Parameters:

Name Type Description Default
preset str

the name of the preset, e.g. pksim_default.

required

Returns:

Type Description
dict[Organ | Pool, Value]

The weight of every organ outflow or pool of the mix with its source.

Raises:

Type Description
ValueError

if the preset is unknown or names neither an organ nor a pool.

observer_objects

observer_objects(definition)

Get the observers of a definition.

Parameters:

Name Type Description Default
definition PBPKDefinition

the definition.

required

Returns:

Type Description
list[Sbase]

The weights of the arm vein and the parameters with their assignment

list[Sbase]

rules of every substance.

sinks

The sinks of the body: urine, feces and bile.

Every substance has the amounts in urine Aurine_<s> and feces Afeces_<s> (compartments of amounts, Vurine and Vfeces) and the bile Cbile_<s> in Vbile, which drains with first order k_bile into the duodenum of the intestine (pkpdsim.pbpk.variants.intestine, which owns the lumen and that transit); with the standard organs as intestine, which have no lumen, the bile drains into the feces.

sink_objects

sink_objects(definition, lumen=True)

Get the sinks of a definition.

Parameters:

Name Type Description Default
definition PBPKDefinition

the definition.

required
lumen bool

the intestine has a lumen, which takes the bile; without one the bile drains into the feces here.

True

Returns:

Type Description
list[Sbase]

The compartments, parameters and species of the top model, and the

list[Sbase]

transit of the bile into the feces without lumen.