pymixef.pharmacometrics.pk module

Closed-form pharmacokinetic helpers and residual-error models.

The PK functions use amount, time, clearance, and volume on any mutually consistent unit system. Returned concentrations have units of amount/volume. Inputs are NumPy-broadcastable and output ordering follows the input time array. Times before a dose (including lag time) return zero.

class pymixef.pharmacometrics.pk.AdditiveError(sigma, variance_floor=np.float64(2.2250738585072014e-308))[source]

Bases: _ErrorOperations

Gaussian additive residual standard deviation.

Parameters:

  • sigma (float | int | floating | str | Any)

  • variance_floor (float)

sigma: float | int | floating | str | Any
variance_floor: float
variance(prediction, parameters=None)[source]
Parameters:

  • prediction (ArrayLike)

  • parameters (Mapping[str, float] | None)

Return type:

NDArray[float64]

to_dict()[source]
Return type:

dict[str, Any]

class pymixef.pharmacometrics.pk.CombinedError(additive_sigma, proportional_sigma, power=1.0, variance_floor=np.float64(2.2250738585072014e-308))[source]

Bases: _ErrorOperations

Independent additive and prediction-dependent Gaussian errors.

Component variances are added; standard deviations are not.

Parameters:

  • additive_sigma (float | int | floating | str | Any)

  • proportional_sigma (float | int | floating | str | Any)

  • power (float | int | floating | str | Any)

  • variance_floor (float)

additive_sigma: float | int | floating | str | Any
proportional_sigma: float | int | floating | str | Any
power: float | int | floating | str | Any
variance_floor: float
classmethod from_components(first, second)[source]
Parameters:
Return type:

CombinedError

variance(prediction, parameters=None)[source]
Parameters:

  • prediction (ArrayLike)

  • parameters (Mapping[str, float] | None)

Return type:

NDArray[float64]

to_dict()[source]
Return type:

dict[str, Any]

class pymixef.pharmacometrics.pk.LogNormalError(sigma)[source]

Bases: object

Multiplicative log-normal observation error.

log(observed) ~ Normal(log(prediction), sigma). logpdf includes the Jacobian for density on the original observation scale.

Parameters:

sigma (float | int | floating | str | Any)

sigma: float | int | floating | str | Any
variance(prediction, parameters=None)[source]
Parameters:

  • prediction (ArrayLike)

  • parameters (Mapping[str, float] | None)

Return type:

NDArray[float64]

logpdf(observed, prediction, parameters=None)[source]
Parameters:

  • observed (ArrayLike)

  • prediction (ArrayLike)

  • parameters (Mapping[str, float] | None)

Return type:

NDArray[float64]

simulate(prediction, *, rng=None, parameters=None)[source]
Parameters:

  • prediction (ArrayLike)

  • rng (Generator | None)

  • parameters (Mapping[str, float] | None)

Return type:

NDArray[float64]

to_dict()[source]
Return type:

dict[str, Any]

class pymixef.pharmacometrics.pk.ObservationError(*args, **kwargs)[source]

Bases: Protocol

Protocol implemented by residual-error declarations.

variance(prediction, parameters=None)[source]
Parameters:

  • prediction (ArrayLike)

  • parameters (Mapping[str, float] | None)

Return type:

NDArray[float64]

to_dict()[source]
Return type:

dict[str, Any]

class pymixef.pharmacometrics.pk.OneCompartmentPK(clearance, volume)[source]

Bases: object

Reusable parameter bundle for one-compartment closed forms.

Parameters:

  • clearance (float)

  • volume (float)

clearance: float
volume: float
iv_bolus(time, dose, **kwargs)[source]
Parameters:

  • time (ArrayLike)

  • dose (float)

  • kwargs (float)

Return type:

Any

infusion(time, **kwargs)[source]
Parameters:

  • time (ArrayLike)

  • kwargs (float)

Return type:

Any

oral(time, dose, absorption_rate, **kwargs)[source]
Parameters:

  • time (ArrayLike)

  • dose (float)

  • absorption_rate (float)

  • kwargs (float)

Return type:

Any

exception pymixef.pharmacometrics.pk.PKValidationError[source]

Bases: ValueError

Raised when PK parameters are outside their mathematical domain.

code = 'PK-INVALID-001'
class pymixef.pharmacometrics.pk.PowerError(sigma, power=1.0, variance_floor=np.float64(2.2250738585072014e-308))[source]

Bases: _ErrorOperations

Gaussian residual SD sigma * abs(prediction) ** power.

Parameters:

  • sigma (float | int | floating | str | Any)

  • power (float | int | floating | str | Any)

  • variance_floor (float)

sigma: float | int | floating | str | Any
power: float | int | floating | str | Any
variance_floor: float
variance(prediction, parameters=None)[source]
Parameters:

  • prediction (ArrayLike)

  • parameters (Mapping[str, float] | None)

Return type:

NDArray[float64]

to_dict()[source]
Return type:

dict[str, Any]

class pymixef.pharmacometrics.pk.ProportionalError(sigma, variance_floor=np.float64(2.2250738585072014e-308))[source]

Bases: _ErrorOperations

Gaussian residual SD equal to sigma * abs(prediction).

Parameters:

  • sigma (float | int | floating | str | Any)

  • variance_floor (float)

sigma: float | int | floating | str | Any
variance_floor: float
variance(prediction, parameters=None)[source]
Parameters:

  • prediction (ArrayLike)

  • parameters (Mapping[str, float] | None)

Return type:

NDArray[float64]

to_dict()[source]
Return type:

dict[str, Any]

class pymixef.pharmacometrics.pk.TwoCompartmentPK(clearance, central_volume, intercompartmental_clearance, peripheral_volume)[source]

Bases: object

Reusable parameter bundle for two-compartment closed forms.

Parameters:

  • clearance (float)

  • central_volume (float)

  • intercompartmental_clearance (float)

  • peripheral_volume (float)

clearance: float
central_volume: float
intercompartmental_clearance: float
peripheral_volume: float
iv_bolus(time, dose, **kwargs)[source]
Parameters:

  • time (ArrayLike)

  • dose (float)

  • kwargs (float)

Return type:

Any

infusion(time, **kwargs)[source]
Parameters:

  • time (ArrayLike)

  • kwargs (float)

Return type:

Any

oral(time, dose, absorption_rate, **kwargs)[source]
Parameters:

  • time (ArrayLike)

  • dose (float)

  • absorption_rate (float)

  • kwargs (float)

Return type:

Any

class pymixef.pharmacometrics.pk.TwoCompartmentRates(k10, k12, k21, alpha, beta)[source]

Bases: object

Micro- and macro-rate constants for a linear two-compartment model.

Parameters:

  • k10 (float)

  • k12 (float)

  • k21 (float)

  • alpha (float)

  • beta (float)

k10: float
k12: float
k21: float
alpha: float
beta: float
pymixef.pharmacometrics.pk.additive(sigma)[source]

Declare an additive Gaussian error model.

Parameters:

sigma (float | int | floating | str | Any)

Return type:

AdditiveError

pymixef.pharmacometrics.pk.combined(additive_sigma, proportional_sigma, *, exponent=1.0)[source]

Declare an additive-plus-power residual-error model.

Parameters:

  • additive_sigma (float | int | floating | str | Any)

  • proportional_sigma (float | int | floating | str | Any)

  • exponent (float | int | floating | str | Any)

Return type:

CombinedError

pymixef.pharmacometrics.pk.interval_censored_loglikelihood(lower, upper, prediction, error, *, parameters=None)[source]

Stable log probability for an interval-censored observation.

Parameters:

  • lower (ArrayLike)

  • upper (ArrayLike)

  • prediction (ArrayLike)

  • error (ObservationError)

  • parameters (Mapping[str, float] | None)

Return type:

NDArray[float64]

pymixef.pharmacometrics.pk.left_censored_loglikelihood(limit, prediction, error, *, parameters=None)[source]

Stable log-CDF contribution for observations below limit.

Parameters:

  • limit (ArrayLike)

  • prediction (ArrayLike)

  • error (ObservationError)

  • parameters (Mapping[str, float] | None)

Return type:

NDArray[float64]

pymixef.pharmacometrics.pk.lognormal(sigma)[source]

Declare an original-scale log-normal error model.

Parameters:

sigma (float | int | floating | str | Any)

Return type:

LogNormalError

pymixef.pharmacometrics.pk.one_compartment_bolus(time, *, dose, clearance, volume, bioavailability=1.0, lag=0.0)

Concentration after a single IV bolus in a one-compartment model.

Parameters:

  • time (ArrayLike)

  • dose (float)

  • clearance (float)

  • volume (float)

  • bioavailability (float)

  • lag (float)

Return type:

float | NDArray[float64]

pymixef.pharmacometrics.pk.one_compartment_infusion(time, *, clearance, volume, dose=None, rate=None, duration=None, bioavailability=1.0, start=0.0)[source]

Concentration for a finite constant-rate one-compartment infusion.

Supply any two consistent values among dose, rate, and duration. If all three are supplied, dose == rate * duration is checked.

Parameters:

  • time (ArrayLike)

  • clearance (float)

  • volume (float)

  • dose (float | None)

  • rate (float | None)

  • duration (float | None)

  • bioavailability (float)

  • start (float)

Return type:

float | NDArray[float64]

pymixef.pharmacometrics.pk.one_compartment_iv_bolus(time, *, dose, clearance, volume, bioavailability=1.0, lag=0.0)[source]

Concentration after a single IV bolus in a one-compartment model.

Parameters:

  • time (ArrayLike)

  • dose (float)

  • clearance (float)

  • volume (float)

  • bioavailability (float)

  • lag (float)

Return type:

float | NDArray[float64]

pymixef.pharmacometrics.pk.one_compartment_iv_infusion(time, *, clearance, volume, dose=None, rate=None, duration=None, bioavailability=1.0, start=0.0)

Concentration for a finite constant-rate one-compartment infusion.

Supply any two consistent values among dose, rate, and duration. If all three are supplied, dose == rate * duration is checked.

Parameters:

  • time (ArrayLike)

  • clearance (float)

  • volume (float)

  • dose (float | None)

  • rate (float | None)

  • duration (float | None)

  • bioavailability (float)

  • start (float)

Return type:

float | NDArray[float64]

pymixef.pharmacometrics.pk.one_compartment_oral(time, *, dose, clearance, volume, absorption_rate, bioavailability=1.0, lag=0.0)[source]

Concentration after a first-order oral dose.

The numerically stable limiting expression is used when absorption and elimination rate constants are nearly equal.

Parameters:

  • time (ArrayLike)

  • dose (float)

  • clearance (float)

  • volume (float)

  • absorption_rate (float)

  • bioavailability (float)

  • lag (float)

Return type:

float | NDArray[float64]

pymixef.pharmacometrics.pk.power(sigma, exponent)[source]

Declare a power residual-error model.

Parameters:

  • sigma (float | int | floating | str | Any)

  • exponent (float | int | floating | str | Any)

Return type:

PowerError

pymixef.pharmacometrics.pk.proportional(sigma)[source]

Declare a proportional Gaussian error model.

Parameters:

sigma (float | int | floating | str | Any)

Return type:

ProportionalError

pymixef.pharmacometrics.pk.right_censored_loglikelihood(limit, prediction, error, *, parameters=None)[source]

Stable log-survival contribution for observations above limit.

Parameters:

  • limit (ArrayLike)

  • prediction (ArrayLike)

  • error (ObservationError)

  • parameters (Mapping[str, float] | None)

Return type:

NDArray[float64]

pymixef.pharmacometrics.pk.two_compartment_bolus(time, *, dose, clearance, central_volume, intercompartmental_clearance, peripheral_volume, bioavailability=1.0, lag=0.0)

Central concentration after a single two-compartment IV bolus.

Parameters:

  • time (ArrayLike)

  • dose (float)

  • clearance (float)

  • central_volume (float)

  • intercompartmental_clearance (float)

  • peripheral_volume (float)

  • bioavailability (float)

  • lag (float)

Return type:

float | NDArray[float64]

pymixef.pharmacometrics.pk.two_compartment_infusion(time, *, clearance, central_volume, intercompartmental_clearance, peripheral_volume, dose=None, rate=None, duration=None, bioavailability=1.0, start=0.0)[source]

Central concentration during and after a finite two-compartment infusion.

Parameters:

  • time (ArrayLike)

  • clearance (float)

  • central_volume (float)

  • intercompartmental_clearance (float)

  • peripheral_volume (float)

  • dose (float | None)

  • rate (float | None)

  • duration (float | None)

  • bioavailability (float)

  • start (float)

Return type:

float | NDArray[float64]

pymixef.pharmacometrics.pk.two_compartment_iv_bolus(time, *, dose, clearance, central_volume, intercompartmental_clearance, peripheral_volume, bioavailability=1.0, lag=0.0)[source]

Central concentration after a single two-compartment IV bolus.

Parameters:

  • time (ArrayLike)

  • dose (float)

  • clearance (float)

  • central_volume (float)

  • intercompartmental_clearance (float)

  • peripheral_volume (float)

  • bioavailability (float)

  • lag (float)

Return type:

float | NDArray[float64]

pymixef.pharmacometrics.pk.two_compartment_iv_infusion(time, *, clearance, central_volume, intercompartmental_clearance, peripheral_volume, dose=None, rate=None, duration=None, bioavailability=1.0, start=0.0)

Central concentration during and after a finite two-compartment infusion.

Parameters:

  • time (ArrayLike)

  • clearance (float)

  • central_volume (float)

  • intercompartmental_clearance (float)

  • peripheral_volume (float)

  • dose (float | None)

  • rate (float | None)

  • duration (float | None)

  • bioavailability (float)

  • start (float)

Return type:

float | NDArray[float64]

pymixef.pharmacometrics.pk.two_compartment_oral(time, *, dose, clearance, central_volume, intercompartmental_clearance, peripheral_volume, absorption_rate, bioavailability=1.0, lag=0.0)[source]

Central concentration after first-order absorption into two compartments.

Parameters:

  • time (ArrayLike)

  • dose (float)

  • clearance (float)

  • central_volume (float)

  • intercompartmental_clearance (float)

  • peripheral_volume (float)

  • absorption_rate (float)

  • bioavailability (float)

  • lag (float)

Return type:

float | NDArray[float64]

pymixef.pharmacometrics.pk.two_compartment_rates(*, clearance, central_volume, intercompartmental_clearance, peripheral_volume)[source]

Calculate microconstants and hybrid exponents alpha and beta.

Parameters:

  • clearance (float)

  • central_volume (float)

  • intercompartmental_clearance (float)

  • peripheral_volume (float)

Return type:

TwoCompartmentRates

On this page
Show Source