nca.terminal¶

Vectorized terminal phase regression.

The elimination rate constant lambda_z is the negative slope of the linear regression of ln c on t over the points of the terminal phase (Gabrielsson & Weiner 2016, ch. 2.8; Phoenix WinNonlin NCA). Which points form the terminal phase is decided by TerminalPhase.method; BEST_FIT evaluates every window of consecutive points that ends at the last measurable point and takes the largest adjusted R², preferring more points within a tolerance, which is the rule of Phoenix.

All windows of all rows are evaluated at once: with suffix sums of x, y, x², xy and y² over the packed points the statistics of the window starting at index s are closed-form expressions of the sums from s to the end, so window_statistics returns (N, n) arrays without a loop over rows or windows.

TerminalFit `dataclass` ¶

TerminalFit(
    slope,
    intercept,
    r2,
    r2_adj,
    se_slope,
    n_points,
    t_first,
    t_last,
    start,
    flags,
    candidates=None,
)

Result of the terminal regression per row, NaN (and start = -1) without a fit.

Attributes:

Name	Type	Description
`slope`	`ndarray`	slope of `ln c` against `t` (`-lambda_z`)
`intercept`	`ndarray`	intercept of the regression, `ln c` at `t = 0`
`r2`	`ndarray`	coefficient of determination
`r2_adj`	`ndarray`	adjusted coefficient of determination
`se_slope`	`ndarray`	standard error of the slope
`n_points`	`ndarray`	number of points of the regression
`t_first`	`ndarray`	time of the first point of the regression
`t_last`	`ndarray`	time of the last point of the regression
`start`	`ndarray`	packed index of the first point of the window
`flags`	`ndarray`	`NCAFlag` bits `POSITIVE_SLOPE` and `TOO_FEW_POINTS`
`candidates`	`DataFrame \| None`	every candidate window of every row with the columns `row` (the index of the row), `start_time`, `n`, `r2_adj` and `slope`, `None` unless `TerminalPhase.keep_candidates` asked for it (`candidate_table`)

window_statistics ¶

window_statistics(x, y, valid)

Regression statistics of every window from an index to the end of the row.

Parameters:

Name	Type	Description	Default
`x`	`ndarray`	regressor `(N, n)`	required
`y`	`ndarray`	response `(N, n)`	required
`valid`	`ndarray`	which points enter the regression `(N, n)`	required

Returns:

Type	Description
`dict[str, ndarray]`	Arrays `(N, n)` keyed `n`, `slope`, `intercept`, `r2`, `r2_adj`,
`dict[str, ndarray]`	`se_slope`; column `s` describes the window `s..end`. Windows with
`dict[str, ndarray]`	fewer than 3 points are `NaN`.

terminal_fit ¶

terminal_fit(
    tp,
    cp,
    n_valid,
    tmax_idx,
    phase,
    manual_mask=None,
    exclude=None,
    windows=None,
)

Terminal log-linear regression of every row.

Parameters:

Name	Type	Description	Default
`tp`	`ndarray`	packed times `(N, n)`	required
`cp`	`ndarray`	packed values `(N, n)`	required
`n_valid`	`ndarray`	valid points per row	required
`tmax_idx`	`ndarray`	packed index of the maximum per row	required
`phase`	`TerminalPhase`	the selection rule and its parameters	required
`manual_mask`	`ndarray \| None`	packed points of the regression for `TerminalMethod.MANUAL`	`None`
`exclude`	`ndarray \| None`	packed points which may not enter the regression `(N, n)`, the values below the limit of quantification a BLQ rule kept or imputed (`pkpdutils.nca.options.BLQRules`)	`None`
`windows`	`ndarray \| None`	the terminal window of single rows `(N, 2)`, `NaN` for a row without one (`TerminalPhase.windows`). A row with a window regresses the points whose time lies in `[t_first, t_last]`, every other row follows `phase.method`.	`None`

Returns:

Type	Description
`TerminalFit`	The fit per row, with the table of every candidate window
`TerminalFit`	(`candidate_table`) when `phase.keep_candidates` is set.

Raises:

Type	Description
`ValueError`	`phase.method` is `TerminalMethod.MANUAL` and `manual_mask` is `None`.

candidate_table ¶

candidate_table(tp, y, regressable, tmax_idx, phase)

Every window the selection of the terminal phase may choose from.

A candidate is a window which starts at a point of the regression, holds at least phase.min_points regressable points and, with phase.exclude_cmax, starts after the maximum: the windows BEST_FIT ranks by the adjusted R², and the same set for the other rules, which pick one of them by a different criterion. A window whose first point cannot be regressed is left out, since its statistics are those of the window starting at the next regressable point (_collect). The slope is reported as it is, so a window of a still rising curve is in the table with a positive slope, which BEST_FIT never chooses.

Parameters:

Name	Type	Description	Default
`tp`	`ndarray`	packed times `(N, n)`	required
`y`	`ndarray`	the logarithms of the values `(N, n)`, `NaN` where there is none	required
`regressable`	`ndarray`	the points which may enter a regression `(N, n)`	required
`tmax_idx`	`ndarray`	packed index of the maximum per row	required
`phase`	`TerminalPhase`	the selection rule and its parameters	required

Returns:

Type	Description
`DataFrame`	One row per candidate window with the columns `row` (the index of the
`DataFrame`	row of the batch), `start_time` (the time of the first point of the
`DataFrame`	window), `n` (points of the window), `r2_adj` and `slope`; the rows
`DataFrame`	are ordered by row and by the start time within a row.

nca.terminal¶

TerminalFit dataclass ¶

window_statistics ¶

terminal_fit ¶

candidate_table ¶

TerminalFit `dataclass` ¶