Pharmacokinetics

Non-compartmental pharmacokinetic analysis (NCA). AUC computation (linear, log-linear, linear-up/log-down), Cmax, Tmax, half-life, clearance, and volume of distribution.

Validates against R packages: PKNCA, NonCompart.

Non-compartmental pharmacokinetic analysis (NCA).

NCA is required for every PK study: AUC, Cmax, half-life, clearance, and volume of distribution. Self-contained, well-defined, formulaic calculations.

Phase 1: NCA only. Compartmental/PopPK is Phase 4+.

Validates against: R packages PKNCA, NonCompart.

class pystatsbio.pk.NCASolution(result)[source]

Bases: SolutionReprMixin

Public result of an NCA fit — a Solution wrapping Result[NCAParams].

Exposes every NCA parameter as a read-only property plus the uniform .backend_name / .timing / .warnings / .info metadata and a Jupyter _repr_html_ (via SolutionReprMixin).

Parameters:

result (Result[NCAParams])

property backend_name: str
property timing: dict[str, float] | None
property warnings: tuple[str, ...]
property info: dict
property auc_last: float
property auc_inf: float | None
property auc_pct_extrap: float | None
property cmax: float
property tmax: float
property half_life: float | None
property lambda_z: float | None
property lambda_z_r_squared: float | None
property clearance: float | None
property vz: float | None
property aumc_last: float

Area under the first moment curve to the last measurable concentration.

property aumc_inf: float | None

AUMC extrapolated to infinity (None if lambda_z is not estimable).

property mrt: float | None

Mean residence time = AUMC_inf / AUC_inf (None if lambda_z unavailable).

property dose: float | None
property route: str
property auc_method: str
property n_points: int
property n_terminal: int
summary()[source]

Human-readable PK summary.

Return type:

str

class pystatsbio.pk.NCAParams(auc_last, auc_inf, auc_pct_extrap, cmax, tmax, half_life, lambda_z, lambda_z_r_squared, clearance, vz, aumc_last, aumc_inf, mrt, dose, route, auc_method, n_points, n_terminal)[source]

Bases: object

Computed payload of a non-compartmental pharmacokinetic analysis.

Parameters:
auc_last: float
auc_inf: float | None
auc_pct_extrap: float | None
cmax: float
tmax: float
half_life: float | None
lambda_z: float | None
lambda_z_r_squared: float | None
clearance: float | None
vz: float | None
aumc_last: float
aumc_inf: float | None
mrt: float | None
dose: float | None
route: str
auc_method: str
n_points: int
n_terminal: int
exception pystatsbio.pk.LambdaZEstimationError(message, *, iterations=0, reason='terminal-phase log-linear fit failed')[source]

Bases: ConvergenceError

Raised when the terminal elimination rate constant cannot be estimated.

This is not a programming error — it signals that the concentration-time profile does not contain enough terminal phase data to fit a reliable log-linear slope. Subclasses ConvergenceError (a fit-quality failure, per the pystatsbio constitution B3), so it is catchable both as LambdaZEstimationError and as the library-wide ConvergenceError.

Parameters:

  • message (str)

  • iterations (int)

  • reason (str)

pystatsbio.pk.nca(time, concentration, *, dose=None, route='ev', auc_method='linear-up/log-down', lambda_z_n_points=None)[source]

Non-compartmental pharmacokinetic analysis.

Parameters:

  • time (array) – Time points (non-negative, no duplicates).

  • concentration (array) – Plasma concentration values (non-negative).

  • dose (float or None) – Administered dose (needed for CL and Vz).

  • route (str) – 'iv' (intravenous bolus) or 'ev' (extravascular / oral).

  • auc_method (str) – 'linear' (linear trapezoidal), 'log-linear' (log-linear trapezoidal), 'linear-up/log-down' (linear up, log-linear down – the default, recommended by FDA guidance).

  • lambda_z_n_points (int or None) – Number of terminal points for half-life estimation. If None, automatically selects the best terminal phase (maximum adjusted r-squared with >= 3 points).

Returns:

Solution wrapping all NCA parameters (AUC, Cmax/Tmax, half-life, clearance, volume of distribution, and a summary method), with the uniform .backend_name/.timing/.warnings/.info accessors.

Return type:

NCASolution

Notes

CPU-only. PK data is always small (typically 10-20 time points per subject).

Validates against: R NonCompart::sNCA(). (PKNCA uses a different default terminal-slope selection and is not a validated reference for this module.)

Notes

If the terminal phase cannot be fitted (too few positive post-Cmax points, or no true elimination phase), lambda_z — and everything derived from it (half_life, auc_inf, auc_pct_extrap, clearance, vz) — is None, and the reason is reported in .warnings. Callers must check for None.