nca.auc¶

Vectorized trapezoid areas of timecourses.

Every function works on (N, n) arrays, one row per curve, without a loop over the rows. Missing points (NaN in the time or the value) are moved to the end of every row by pack_valid, so that the segments between consecutive valid points are the columns of the arrays segment_areas returns.

The trapezoid rules are the ones of Gabrielsson & Weiner (2016, ch. 2.8) and of the Phoenix WinNonlin NCA, compared against alternative numerical integration schemes by Yeh & Kwan (1978), Chiou (1978) and Purves (1992): on a segment from (t1, c1) to (t2, c2) with dt = t2 - t1 the linear rule gives the area dt (c1 + c2) / 2 and the first moment dt (t1 c1 + t2 c2) / 2; the logarithmic rule, exact for a mono-exponential decline, gives the area dt (c1 - c2) / L and the moment dt (t1 c1 - t2 c2) / L + dt² (c1 - c2) / L² with L = ln(c1 / c2).

take_rows ¶

take_rows(a, idx)

Element idx[i] of row i.

Parameters:

Name	Type	Description	Default
`a`	`ndarray`	array `(N, n)`	required
`idx`	`ndarray`	one column index per row `(N,)`	required

Returns:

Type	Description
`ndarray`	The selected elements `(N,)`.

pack_valid ¶

pack_valid(t, c)

Move the valid points of every row to the front, keeping their order.

Parameters:

Name	Type	Description	Default
`t`	`ndarray`	times of shape `(N, n)`	required
`c`	`ndarray`	values of shape `(N, n)`	required

Returns:

Type	Description
`ndarray`	The packed times, the packed values (both padded with `NaN`) and the
`ndarray`	number of valid points per row.

segment_areas ¶

segment_areas(tp, cp, n_valid, method)

Areas and first moments of the segments between consecutive packed points.

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 `(N,)`	required
`method`	`AUCMethod`	trapezoid rule	required

Returns:

Type	Description
`ndarray`	The areas and the first moments, both of shape `(N, n - 1)`; a segment
`ndarray`	beyond the valid points of its row is 0.

auc_aumc ¶

auc_aumc(tp, cp, n_valid, method, t_start=None, t_end=None)

Area and first moment of every row, optionally only over a time window.

A segment counts as a whole or not at all, so the window covers the intended interval exactly when a point of the packed arrays lies on each of its bounds; interpolate_at and insert_point add such a point.

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
`method`	`AUCMethod`	trapezoid rule	required
`t_start`	`ndarray \| None`	per row, only segments starting at or after this time count	`None`
`t_end`	`ndarray \| None`	per row, only segments ending at or before this time count	`None`

Returns:

Type	Description
`tuple[ndarray, ndarray]`	`auc` and `aumc` of shape `(N,)`.

time_above_threshold ¶

time_above_threshold(tp, cp, n_valid, threshold)

Total time the linearly interpolated curve is above a threshold, per 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
`threshold`	`float`	the threshold	required

Returns:

Type	Description
`ndarray`	The total time above the threshold `(N,)`.

interpolate_at ¶

interpolate_at(tp, cp, n_valid, t_query, method)

Value of every row at a query time by interpolation between the bracketing points.

Linear interpolation, or logarithmic interpolation on a segment the trapezoid method treats logarithmically. NaN outside the observed times of a 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
`t_query`	`ndarray`	one query time per row `(N,)`	required
`method`	`AUCMethod`	trapezoid rule	required

Returns:

Type	Description
`ndarray`	The interpolated values `(N,)`.

insert_point ¶

insert_point(tp, cp, n_valid, t_new, c_new)

Insert one point per row and repack in time order.

A row whose new time or value is NaN is left unchanged (its arrays are still one column wider).

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
`t_new`	`ndarray`	time of the new point per row	required
`c_new`	`ndarray`	value of the new point per row	required

Returns:

Type	Description
`tuple[ndarray, ndarray, ndarray]`	The packed times and values `(N, n + 1)` and the new counts.