pbpk experiment¶

The base of the simulation experiments of a model built on the PBPK library: the healthy GFR of an individual, the renal function of a measured clearance and the maps of the classes of a study onto the severities of the library, see Impairment.

The base of the simulation experiments of a model built on the library.

A model of the library has the impairments as the severities and the renal function of the library (CP_severity, HF_severity, f_renal_function, see pkpdsim.pbpk.impairment), so the classes of a study map onto other values than those of the hand-written models. The base of its experiments derives from PBPKSimulationExperiment instead of PKPDSimulationExperiment and binds the model object as usual:

# not executed
class GlimepirideSimulationExperiment(PBPKSimulationExperiment):
    pkpd_model = MODEL

The GFR of the library is GFR = GFR_base * f_renal_function, and GFR_base, the GFR of the individual at renal function 1, scales with its body surface area (and falls with heart failure and cirrhosis). healthy_gfr reads it from the flat model, PBPKSimulationExperiment.renal_function gives the renal function of a measured clearance (the simulated GFR is the measured one), and the classes of renal impairment keep their GFR in ml/min (ScaledRenalMap). All of them are of the build of the sex of the subjects (sex of the experiment, the female build for a study of women, or the sex of a simulation, simulation=, in a study of a group of each sex): the GFR of a woman is the GFR of the female build.

The outflow of the kidney is valid while the filtered plasma water (the GFR) and the net filtered plasma flow of every substance are below the plasma flow of the kidney (pkpdsim.pbpk.kidney_validity): PBPKSimulationExperiment refuses an experiment which simulates an individual outside of it, checked on the model of each task, and a renal function beyond it (renal_function, renal_function_limits).

The module imports sbmlsim; pkpdsim.pbpk exports its names lazily, so import pkpdsim.pbpk (a factory) imports no simulator.

ScaledRenalMap ¶

ScaledRenalMap(preset, gfr=None, reference=REFERENCE_GFR)

Bases: Mapping[str, float]

The renal function of the classes of renal impairment at a healthy GFR.

A preset of pkpdsim.impairment gives the renal function of a class relative to a healthy GFR of reference ml/min (101); the classes keep their GFR in ml/min, so a value is preset[class] * reference / gfr(). The GFR is evaluated on the first access to a value, so importing the experiments loads no model; the keys are those of the preset at once.

Without gfr the map is bound to the class it is an attribute of: a class attribute is a (non-data) descriptor, and the access through a class (or an instance) gives the map of that class, on its classmethod healthy_gfr, one map per class, created on the first access. So the base of the experiments of every model, and every subclass with another model object or another sex (a study of women gets the GFR of the female build), gets the GFR of its own model, and a model overrides the preset in its base:

# not executed
class HCTZSimulationExperiment(PBPKSimulationExperiment):
    pkpd_model = MODEL
    renal_map: ClassVar[Mapping[str, float]] = ScaledRenalMap(
        impairment.RENAL_FUNCTION
    )

The map of a class is of the sex of the class (sex); the map for another sex, e.g. the group of women of a study of men, is of_sex (see PBPKSimulationExperiment.renal_map_of, which takes the key of the simulation).

Get the classes of a preset at a healthy GFR.

Parameters:

Name	Type	Description	Default
`preset`	`Mapping[str, float]`	the renal function of the classes relative to `reference`.	required
`gfr`	`Callable[[], Quantity] \| None`	the healthy GFR (a quantity of a flow), called on the first access to a value; `None` for the `healthy_gfr` of the class the map is an attribute of.	`None`
`reference`	`float`	the healthy GFR the preset is relative to [ml/min].	`REFERENCE_GFR`

of_sex ¶

of_sex(sex)

Get the map of a class at the healthy GFR of the build of a sex.

Parameters:

Name	Type	Description	Default
`sex`	`Sex`	the sex.	required

Returns:

Type	Description
`ScaledRenalMap`	The map of the class this map is bound to, on its `healthy_gfr` of
`ScaledRenalMap`	the sex: this map for the sex of the class, else a map created on
`ScaledRenalMap`	the first call.

Raises:

Type	Description
`TypeError`	for a map with its own GFR (of one build) or a map which no class bound.

PBPKSimulationExperiment ¶

PBPKSimulationExperiment(
    sid=None,
    base_path=None,
    data_path=None,
    ureg=None,
    **kwargs,
)

Bases: PKPDSimulationExperiment

The base of the simulation experiments of a model built on the library.

The maps of the classes of a study onto the library: the renal function of the classes of impairment.RENAL_FUNCTION_GFR (the limits of the GFR and the end stage renal disease) at the healthy GFR of the model, the Child-Pugh classes as CP_severity (impairment.CHILD_PUGH) and the NYHA classes as HF_severity (impairment.HEART_FAILURE), with their colors. The classes of renal impairment keep their GFR in ml/min: the renal function of a class is its GFR over the healthy GFR of the model (ScaledRenalMap), unlike the eGFR of the library, which sets the factors of chronic kidney disease and is relative to the GFR per 1.73 m2 of the reference individual (pkpdsim.pbpk.impairment). A model overrides any attribute, e.g. the classes by the midpoints of the GFR (ScaledRenalMap(impairment.RENAL_FUNCTION)), its own map of the heart failure or a narrower renal_function_range.

The healthy GFR, the renal function of a clearance, the range of the renal functions and the renal classes are those of the build of the sex of the subjects: the sex of the experiment (sex, see PKPDSimulationExperiment), or of a simulation by its key, simulation= (sex_of, the sex of simulation_sexes), e.g. renal_function(60.0, simulation="po_women") and renal_map_of(simulation="po_women") for the group of women of a study of men; sex= gives a sex directly. An experiment whose simulation_sexes names another sex than sex refuses a call with neither, since the sex of the subjects is not the sex of the experiment for every simulation (the attribute renal_map stays the map of sex).

The initialization refuses an experiment which simulates an individual outside the validity of the kidney outflow (kidney_outflow): the filtered plasma water (the GFR) and the net filtered plasma flow of a substance must stay below the plasma flow of the kidney, at the start of every simulation and every point of a scan, each on the model its task runs (simulated_individuals; not checked: a change during a simulation, also of a dynamic id at its start, a dimension with a time, a scan over models and the draws of the fitted parameters of a run over them).

Attributes:

Name	Type	Description
`renal_function_range`	`tuple[float, float] \| None`	a narrower range of the renal functions the model supports, `None` (the default) for the range of the validity of the kidney outflow, from 0 (anuria, the substances leave by the other routes alone) to the renal function at which the GFR or the net filtered plasma flow of a substance reaches the plasma flow of the kidney (`renal_function_limits`); a model whose urine is not defined without filtration starts above 0. The validity holds within the range as well.

initialize ¶

initialize()

Initialize the experiment and check the kidney outflow of its individuals.

Raises:

Type	Description
`ValueError`	for a simulation of an individual outside the validity of the kidney outflow, naming the experiment, the simulation, the GFR and the plasma flow of the kidney.

equilibrated ¶

equilibrated(
    simulation: Simulation,
    *,
    resets: Mapping[str, Quantity | float] | None = None,
    model: str = "model",
    absolute_tolerance: float = EQUILIBRATION_TOLERANCES[0],
    relative_tolerance: float = EQUILIBRATION_TOLERANCES[1],
    max_time: float = EQUILIBRATION_TOLERANCES[2],
) -> Simulation

equilibrated(
    simulation: Scan,
    *,
    resets: Mapping[str, Quantity | float] | None = None,
    model: str = "model",
    absolute_tolerance: float = EQUILIBRATION_TOLERANCES[0],
    relative_tolerance: float = EQUILIBRATION_TOLERANCES[1],
    max_time: float = EQUILIBRATION_TOLERANCES[2],
) -> Scan

equilibrated(
    simulation: Simulation | Scan,
    *,
    resets: Mapping[str, Quantity | float] | None = None,
    model: str = "model",
    absolute_tolerance: float = EQUILIBRATION_TOLERANCES[0],
    relative_tolerance: float = EQUILIBRATION_TOLERANCES[1],
    max_time: float = EQUILIBRATION_TOLERANCES[2],
) -> Simulation | Scan

equilibrated(
    simulation,
    *,
    resets=None,
    model="model",
    absolute_tolerance=EQUILIBRATION_TOLERANCES[0],
    relative_tolerance=EQUILIBRATION_TOLERANCES[1],
    max_time=EQUILIBRATION_TOLERANCES[2],
)

Get a simulation which starts from the drug-free steady state of its condition.

The state of a model at its start is the steady state of the healthy reference individual; a condition of the simulation (an impairment, a covariate, a PD component with a homeostasis) moves a slow state away from it, which a study measures as the basal state of its subjects before the first dose. The simulation equilibrates first: the presimulation of sbmlsim (SteadyState) integrates the model with the changes before the initialization of the simulation, the condition, without the doses until the rates of change are within the tolerances, and the simulation starts from that state.

The doses of the changes before the initialization, the dose states and infusion rates of the library (PODOSE_<s>, IVDOSE_<s>, SOLDOSE_<s>, Ri_<s>), are given by a change at the start instead, after the equilibration; the doses of the changes at later times stay. A dose of zero moves as well, so a dimension of a scan over it replaces it at the start.
The sinks, whose amounts grow without a steady state (the urine and the feces of the library, Aurine_<s>, Afeces_<s>, the readouts of the intestine which nothing drains, the amount absorbed Aabs_<s> and the oral dose applied Aapp_<s> (GU__Aabs_<s>, GU__Aapp_<s> with the readout Fa_<s> alone), and what a PD component accumulates, resets), are set back at the start: they are in steady state when their rate is within the tolerances relative to their amount, which they reach as well. A state without an outflow which grows during the equilibration and is neither a sink of the library nor in resets is refused, named (growing_states, checked once per model file in a process). A reset names a species by its id; a species whose id is its concentration is set as [sid], as the zeros are.
The species which are 0 without a dose, of the substances without a baseline (the drugs and their metabolites) which start at 0 and which no reaction feeds from a species with a start, are set to exactly 0 at the start (drug_free_zeros): the presimulation leaves a residue of the rounding in them (1.5e-29 mM of hctz), which a pre-dose point of zero would count in the fold metrics. A species which a change of the condition or at the start sets keeps its value; an endogenous substance (a baseline, e.g. creatinine) keeps its equilibrated values.
The base <id>_0 of a delta observer (PBPKDefinition.deltas) is set at the start to the value after the equilibration, so the delta <id>_delta is 0 at the start of the simulation.
A model which reaches no steady state by max_time fails with the SteadyStateError of sbmlsim (within the ScanError of the run).

The presimulation is the choice over a hidden pre-run of a duration from a negative start (tested on a homeostasis of 7 days: the pre-run of 28 days leaves it 1.8 % off the steady state, the presimulation is exact), and its default tolerances are tighter than those of sbmlsim: the rates are per minute, the time unit of the model, so the relative tolerance of sbmlsim, 1e-6, stops a homeostasis of 7 days 5e-5 off; at 1e-10 a sink reaches the tolerance after 1e10 minutes, within max_time.

Every point of a scan equilibrates in its own condition; a dimension over a dose which the simulation does not give is refused (it would be a dose before the equilibration). The changes of a fit (the fitted parameters) and of a run over the draws of the fitted parameters are changes before the initialization as well, so they apply during the equilibration. The simulation runs on the build of its sex as every simulation of the experiment; the builds have the same ids. It is equilibrated_simulation(simulation, model_path) of pkpdsim.pbpk.equilibration on the file of the loaded model, the equilibration outside an experiment as well (the groups of a sensitivity analysis).

Parameters:

Name	Type	Description	Default
`simulation`	`Simulation \| Scan`	the simulation or the scan, in the condition.	required
`resets`	`Mapping[str, Quantity \| float] \| None`	the values at the start of the further states which grow without a steady state, e.g. the urine of a PD component.	`None`
`model`	`str`	the key of the loaded model whose ids are read, see `add_doses`.	`'model'`
`absolute_tolerance`	`float`	the absolute tolerance of the rates of the equilibration (per minute).	`EQUILIBRATION_TOLERANCES[0]`
`relative_tolerance`	`float`	the relative tolerance of the rates.	`EQUILIBRATION_TOLERANCES[1]`
`max_time`	`float`	the longest equilibration (minutes).	`EQUILIBRATION_TOLERANCES[2]`

Returns:

Type	Description
`Simulation \| Scan`	The equilibrated simulation or scan, a new object.

Raises:

Type	Description
`ValueError`	if the model is not loaded or not a file, the simulation has a presimulation, a dose is set before the initialization and by a change at the start, a state grows during the equilibration which is not set back, or a dimension of a scan sets a dose which the simulation does not give or varies simulations; the message is noted with the experiment.
`ScanError`	if the model reaches no steady state in the condition by `max_time` (a `SteadyStateError` of sbmlsim).

subjects_sex `classmethod` ¶

subjects_sex(sex=None, simulation=None)

Get the sex of the subjects of a call of the renal functions.

Parameters:

Name	Type	Description	Default
`sex`	`Sex \| None`	the sex, `None` for the sex of `simulation`.	`None`
`simulation`	`str \| None`	the key of the simulation whose subjects are meant (`sex_of`), `None` for the sex of the experiment (`sex`).	`None`

Returns:

Type	Description
`Sex`	`sex`, else the sex of the simulation, else the sex of the experiment.

Raises:

Type	Description
`ValueError`	for both `sex` and `simulation`, and for neither in an experiment whose `simulation_sexes` names another sex than `sex` (its subjects have no one sex).

healthy_gfr `classmethod` ¶

healthy_gfr(
    *,
    bw=None,
    height=None,
    hf_severity=0.0,
    cp_severity=0.0,
    sex=None,
    simulation=None,
)

Get the healthy glomerular filtration rate of an individual (ml/min).

healthy_gfr of the module for the build of the sex of the subjects (subjects_sex), cached for all experiments.

Parameters:

Name	Type	Description	Default
`bw`	`float \| None`	the body weight of the individual [kg], `None` for that of the model.	`None`
`height`	`float \| None`	the height of the individual [cm], `None` for that of the model.	`None`
`hf_severity`	`float`	the severity of heart failure `HF_severity` (0 to 4).	`0.0`
`cp_severity`	`float`	the severity of cirrhosis `CP_severity` (0 to 3).	`0.0`
`sex`	`Sex \| None`	the sex of the individual, `None` for the sex of `simulation`.	`None`
`simulation`	`str \| None`	the key of the simulation of the individual, `None` for the sex of the experiment (`sex`).	`None`

Returns:

Type	Description
`Quantity`	The GFR at renal function 1 in ml/min, a quantity.

Raises:

Type	Description
`TypeError`	if the class has no model object (`pkpd_model`).
`ValueError`	if the model object has no build of the sex, or the sex is not given in an experiment of both sexes (`subjects_sex`).

renal_function `classmethod` ¶

renal_function(
    clearance,
    *,
    bw=None,
    height=None,
    hf_severity=0.0,
    cp_severity=0.0,
    sex=None,
    simulation=None,
)

Get the renal function of a measured clearance.

The glomerular filtration rate of the model is f_renal_function * GFR_base, and GFR_base, the healthy rate of the individual of the simulation (healthy_gfr), scales with its body surface area and falls with the severity of heart failure and of cirrhosis. A measured clearance includes all of them, so the renal function is the clearance relative to the healthy rate of the individual of the study, and the simulated rate is the measured one; the simulation sets the same covariates.

Parameters:

Name	Type	Description	Default
`clearance`	`float`	measured clearance (creatinine clearance or GFR) [ml/min], not indexed to the body surface area.	required
`bw`	`float \| None`	the body weight of the simulation [kg], `None` for that of the model.	`None`
`height`	`float \| None`	the height of the simulation [cm], `None` for that of the model.	`None`
`hf_severity`	`float`	the severity of heart failure of the simulation.	`0.0`
`cp_severity`	`float`	the severity of cirrhosis of the simulation.	`0.0`
`sex`	`Sex \| None`	the sex of the subjects, `None` for the sex of `simulation`; the GFR of a woman is the GFR of the female build.	`None`
`simulation`	`str \| None`	the key of the simulation of the subjects, whose sex (`sex_of`) gives the build, `None` for the sex of the experiment (`sex`).	`None`

Returns:

Type	Description
`Quantity`	The renal function `f_renal_function`.

Raises:

Type	Description
`ValueError`	for a renal function outside of the validity of the kidney outflow (the message names the GFR and the plasma flow of the kidney) or of the `renal_function_range` of the model, if the model object has no build of the sex, or if the sex is not given in an experiment of both sexes (`subjects_sex`).

renal_function_limits `classmethod` ¶

renal_function_limits(
    *,
    bw=None,
    height=None,
    hf_severity=0.0,
    cp_severity=0.0,
    sex=None,
    simulation=None,
)

Get the range of the renal functions of an individual which the model supports.

From 0 to the smaller of the renal functions at which the filtered plasma water, the GFR, reaches the plasma flow of the kidney Qki*(1 - HCT) and at which the net filtered plasma flow of a filtered substance reaches the flow which carries it (kidney_outflow), the flows of the individual at renal function 1 (the GFR is GFR_base*f_renal_function, the net filtered plasma flow the GFR times the factors of the substance, which do not change above renal function 1, where the factors of chronic kidney disease are 1), the upper end excluded; within the renal_function_range of the model if it has one. The water is the tighter bound (fu <= 1, BP >= 1 - HCT); infinite for a model without a filtered substance.

Parameters:

Name	Type	Description	Default
`bw`	`float \| None`	the body weight of the individual [kg], `None` for that of the model.	`None`
`height`	`float \| None`	the height of the individual [cm], `None` for that of the model.	`None`
`hf_severity`	`float`	the severity of heart failure of the individual.	`0.0`
`cp_severity`	`float`	the severity of cirrhosis of the individual.	`0.0`
`sex`	`Sex \| None`	the sex of the individual, `None` for the sex of `simulation`.	`None`
`simulation`	`str \| None`	the key of the simulation of the individual, `None` for the sex of the experiment (`sex`).	`None`

Returns:

Type	Description
`tuple[float, float]`	The lowest and the highest renal function.

Raises:

Type	Description
`TypeError`	if the class has no model object (`pkpd_model`).
`ValueError`	if the model object has no build of the sex, or the sex is not given in an experiment of both sexes (`subjects_sex`).

renal_map_of `classmethod` ¶

renal_map_of(sex=None, *, simulation=None)

Get the renal classes of the subjects of a sex or of a simulation.

renal_map is of the sex of the experiment; the classes of the other sex, e.g. of the group of women of a study of men (renal_map_of(simulation="po_women")), are those of the same preset at the healthy GFR of the build of that sex (ScaledRenalMap.of_sex). A map which is no ScaledRenalMap is not relative to a healthy GFR and is the map of every sex.

Parameters:

Name	Type	Description	Default
`sex`	`Sex \| None`	the sex, `None` for the sex of `simulation`.	`None`
`simulation`	`str \| None`	the key of the simulation of the subjects (`sex_of`), `None` for the sex of the experiment (`sex`).	`None`

Returns:

Type	Description
`Mapping[str, float]`	The renal function of every class.

Raises:

Type	Description
`TypeError`	for a `ScaledRenalMap` with its own GFR (of one build) and another sex than the sex of the experiment.
`ValueError`	if the sex is not given in an experiment of both sexes (`subjects_sex`).

healthy_gfr ¶

healthy_gfr(
    model_path,
    *,
    bw=None,
    height=None,
    hf_severity=0.0,
    cp_severity=0.0,
)

Get the healthy glomerular filtration rate of an individual (ml/min).

The GFR of an individual at renal function 1 (GFR_base of the library, GFR = GFR_base * f_renal_function): it scales with the body surface area of the body weight and the height, the severity of heart failure lowers the renal blood flow and with it the GFR, and the cirrhosis lowers it by the hepatorenal factor of its Child-Pugh class. The GFR and its covariates are initial assignments, so it is read from a simulation of one minute with the covariates as changes before the initialization, which evaluates the initial assignments again (sbmlsim). It is cached per model file, its modification time and the individual, once for all experiments of a process; a model file which is created again is simulated again. The sex is no parameter of the model: the library builds the model of one sex, and the GFR of a woman is the GFR of the female build.

Parameters:

Name	Type	Description	Default
`model_path`	`Path`	the flat SBML model of the library, the build of the sex of the individual.	required
`bw`	`float \| None`	the body weight of the individual [kg], `None` for that of the model.	`None`
`height`	`float \| None`	the height of the individual [cm], `None` for that of the model.	`None`
`hf_severity`	`float`	the severity of heart failure `HF_severity` (0 to 4).	`0.0`
`cp_severity`	`float`	the severity of cirrhosis `CP_severity` (0 to 3).	`0.0`

Returns:

Type	Description
`Quantity`	The GFR at renal function 1 in ml/min, a quantity as the renal
`Quantity`	function of `PBPKSimulationExperiment.renal_function`.

molecular_weights ¶

molecular_weights(definition)

Get the molecular weights of a definition, for the conversion of the data.

The molecular weight Mr_<s> of every substance of the definition, and of a substance of the data which is no substance of the model (the substance of a measurement which the model reads in another form, e.g. a protein of a PD readout) as a parameter of the definition Mr_<x> in g/mole; the same numbers the model has. The base of the experiments of a model reads them instead of a copy:

# not executed
class TorasemideSimulationExperiment(PBPKSimulationExperiment):
    pkpd_model = MODEL
    Mr: ClassVar[Mapping[str, Quantity]] = molecular_weights(DEFINITION)

    def to_molar(self, dset: DataSet) -> DataSet:
        dset.unit_conversion("mean", 1 / self.Mr["tor"])

Parameters:

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

Returns:

Type	Description
`Mapping[str, Quantity]`	The molecular weight by the id of the substance (`tor`, without
`Mapping[str, Quantity]`	`Mr_`), a read-only mapping of quantities in g/mole.

Raises:

Type	Description
`ValueError`	for a molecular weight which is a formula, or a parameter `Mr_<x>` of another unit.

pbpk experiment¶

ScaledRenalMap ¶

of_sex ¶

PBPKSimulationExperiment ¶

initialize ¶

equilibrated ¶

subjects_sex classmethod ¶

healthy_gfr classmethod ¶

renal_function classmethod ¶

renal_function_limits classmethod ¶

renal_map_of classmethod ¶

healthy_gfr ¶

molecular_weights ¶

subjects_sex `classmethod` ¶

healthy_gfr `classmethod` ¶

renal_function `classmethod` ¶

renal_function_limits `classmethod` ¶

renal_map_of `classmethod` ¶