nca¶

The non-compartmental analysis.

nca analyses a Timecourses batch, nca_single one Timecourse. The numerics run in compute_parameters on (N, n) arrays, one row per curve, with the times relative to the dose; the rows are the flattened sample dimensions of the batch and the results are reshaped back into an xarray.Dataset over the same dimensions (NCAResult).

Definitions follow Gabrielsson & Weiner (2016, ch. 2.8) and the Phoenix WinNonlin NCA, see docs/nca.md:

AUC(0-tlast) and AUMC(0-tlast) by the trapezoid rule of AUCMethod
lambda_z from the terminal log-linear regression (TerminalPhase), t½ = ln 2 / lambda_z
AUC(0-inf) = AUC(0-tlast) + Clast / lambda_z (observed or predicted Clast)
AUMC(0-inf) = AUMC(0-tlast) + Clast tlast / lambda_z + Clast / lambda_z²
MRT = AUMC(0-inf) / AUC(0-inf), minus half the infusion duration
thalf_eff = ln 2 * MRT, the effective half-life. The formula is the one of PKNCA (Denney et al. 2015), whose pk.calc.thalf.eff reads

#' @details thalf.eff is `log(2)*mrt`.
pk.calc.thalf.eff <- function(mrt) {
  log(2)*mrt
}

and whose interval columns thalf.eff.obs, thalf.eff.pred and thalf.eff.iv.* all evaluate it with the mean residence time they name. It is reported by every concentration analysis, single dose and multiple dose, and it uses the MRT of the row, the infusion correction included - CL = Dose / AUC(0-inf), Vz = CL / lambda_z, Vss = CL MRT (intravenous)

unit_expression ¶

unit_expression(name)

Unit expression of a result variable, derived variables from their parameter.

Parameters:

Name	Type	Description	Default
`name`	`str`	name of a variable of the result, e.g. `"auc_last"`, `"auc_last_se"` or `"n"`.	required

Returns:

Type	Description
`str`	The unit expression of `PARAMETER_UNITS`, the one of the parameter a
`str`	derived variable belongs to, the expression of a parameter per dose for
`str`	a dose normalized variable `x_dn` (`NCAResult.dose_normalized`), or
`str`	`"dimensionless"` for `n` and the dimensionless derived variables.

Raises:

Type	Description
`KeyError`	if the name belongs to no known parameter.

positive_dose ¶

positive_dose(dose_amount)

The dose amounts, NaN where a row carries no positive dose.

A dose of 0 is the encoding of a placebo arm (Dose.amount is non-negative). The parameters which divide by the dose - the clearance, the volumes and the dose normalized exposure - are not defined for it, so the amount is NaN there and every one of them follows; the analysis reports this in a debug log and sets no flag, since a zero dose is a property of the data and not a finding of the analysis.

Parameters:

Name	Type	Description	Default
`dose_amount`	`ndarray`	the reference dose per row `(N,)`	required

Returns:

Type	Description
`ndarray`	The amounts with the non-positive ones replaced by `NaN`.

bolus_c0 ¶

bolus_c0(tp, cp, n_valid, options)

Concentration at time 0 of an intravenous bolus, per row.

With C0Method.LOG_BACK_EXTRAPOLATION the first two samples are extrapolated back to the dose,

\[C_0 = \exp\left(\ln C_1 - \frac{\ln C_2 - \ln C_1}{t_2 - t_1} t_1\right),\]

the estimate of Gabrielsson & Weiner (2016, ch. 2.8). The back extrapolation needs two samples which decline, so it is used when the row carries two valid points, both values are positive, the second value is below the first and the second time is after the first; in every other case the first observed value is used, which is the documented fallback chain of Phoenix WinNonlin ("if the regression yields a slope >= 0, or at least one of the first two y-values is zero ... then the first observed y-value is used"). C0Method.FIRST_VALUE always takes the first value and C0Method.NONE estimates nothing: c0 is NaN, no point is inserted and the areas start at the first sample.

The inserted point never enters the terminal regression, which reads the observed values, and the rule of a row is reported in c0_method (C0_NONE, C0_BACK_EXTRAPOLATION, C0_FIRST_VALUE). For an extravascular single dose the value at the dose time is 0 and for a steady state interval the minimum observed value of the interval (pkpdutils.nca.intervals), neither of them an estimate of C0.

Parameters:

Name	Type	Description	Default
`tp`	`ndarray`	packed times `(N, n)`, relative to the dose	required
`cp`	`ndarray`	packed values `(N, n)`	required
`n_valid`	`ndarray`	valid points per row `(N,)`	required
`options`	`NCAOptions`	the options, `c0_method` is used	required

Returns:

Type	Description
`ndarray`	The estimate per row `(N,)` and the rule which produced it, one of
`ndarray`	`C0_NONE`, `C0_BACK_EXTRAPOLATION` and `C0_FIRST_VALUE` per row.

resolve_lloq ¶

resolve_lloq(options, lloq, n_rows)

The limit of quantification of every row.

Parameters:

Name	Type	Description	Default
`options`	`NCAOptions`	the options, `lloq` is the limit of the whole analysis	required
`lloq`	`ndarray \| None`	the limit of every row `(N,)` (the per-sample `lloq` of the batch), `None` without one	required
`n_rows`	`int`	number of rows `N`	required

Returns:

Type	Description
`ndarray \| None`	One limit per row, `None` when neither the options nor the batch name
`ndarray \| None`	one. `NCAOptions.lloq` wins over the per-sample limit; a row whose
`ndarray \| None`	limit is `NaN` has none.

apply_blq ¶

apply_blq(c, lloq, rules)

Apply the rules for the values below the limit of quantification.

The rules are read by position (first, middle, last) or against the maximum (before_tmax, after_tmax), see BLQRules; a position without a rule drops its values. A row without a single measurable value is first on the positional axis and after_tmax on the tmax axis.

Parameters:

Name	Type	Description	Default
`c`	`ndarray`	values `(N, n)` in the time order of the curve	required
`lloq`	`ndarray \| None`	limit of quantification per row `(N,)`, `None` for no limit	required
`rules`	`BLQRules`	the rules	required

Returns:

Type	Description
`ndarray`	The values, the rows in which a value was dropped or imputed
`ndarray`	(`NCAFlag.BLQ_TRUNCATED`) and the mask of the values below the limit
`ndarray`	which are still part of the curve, imputed or kept (`(N, n)`); the
`tuple[ndarray, ndarray, ndarray]`	terminal regression leaves those out unless
`tuple[ndarray, ndarray, ndarray]`	`BLQRules.terminal_regression`.

packed_mask ¶

packed_mask(t, c, mask)

A mask of the original columns of a row in the layout of pack_valid.

Parameters:

Name	Type	Description	Default
`t`	`ndarray`	times `(N, n)`, as they are packed	required
`c`	`ndarray`	values `(N, n)`, as they are packed	required
`mask`	`ndarray`	the mask over the original columns `(N, n)`	required

Returns:

Type	Description
`ndarray`	The mask over the packed columns `(N, n)`; a column which is not a
`ndarray`	valid point is `False`.

compute_parameters ¶

compute_parameters(
    t,
    c,
    *,
    dose_amount,
    dose_time,
    dose_duration,
    route,
    options,
    lloq=None,
    windows=None,
    single_dose=True,
)

Single dose parameters of every row of (N, n) time and value arrays.

Parameters:

Name	Type	Description	Default
`t`	`ndarray`	times `(N, n)`, `NaN` for missing points	required
`c`	`ndarray`	values `(N, n)`, `NaN` for missing values	required
`dose_amount`	`ndarray \| None`	dose per row `(N,)`, `None` without doses (`NaN` for a row without a dose in a batch which has them)	required
`dose_time`	`ndarray \| None`	time of the dose per row, `None` for 0; a row without a dose carries `NaN` and its times are kept as they are, so that the dose-independent parameters of the row are still computed	required
`dose_duration`	`ndarray \| None`	infusion duration per row (`NaN` without infusion), `None` for none	required
`route`	`Route \| None`	route of the batch, `None` without doses	required
`options`	`NCAOptions`	the options	required
`lloq`	`ndarray \| None`	limit of quantification per row `(N,)`, `None` for none; `NCAOptions.lloq` wins over it (`resolve_lloq`)	`None`
`windows`	`ndarray \| None`	the terminal window `(t_first, t_last)` of single rows `(N, 2)` in the times of the analysis, `NaN` for a row without one (`TerminalPhase.windows`, `sample_windows`)	`None`
`single_dose`	`bool`	whether the rows are single dose curves. An infusion which starts at the dose is 0 there, so a zero is inserted at the dose time of a single dose row whose first sample comes later (the `insert_point` call of the `IV_INFUSION` branch below, which `_insert_dose_value` does for a partial area); the same row of a steady state interval starts at its trough and nothing is inserted (`pkpdutils.nca.steady_state.compute_steady_state` passes `False`)	`True`

Returns:

Type	Description
`dict[str, ndarray]`	One `(N,)` array per parameter (see `PARAMETER_UNITS`) and `flags`.

candidate_variables ¶

candidate_variables(candidates, *, n_rows)

The candidate windows of the terminal regression as variables of one row.

The table of pkpdutils.nca.terminal.candidate_table becomes the (1, K) arrays candidate_t_first, candidate_n_points and candidate_r2_adj of a single curve, which _to_result writes over the dimension candidate. Only an analysis of one row carries them: the windows of a row are a table of their own and the rows of a batch need not have equally many of them, so a batch would need a padded extra dimension which every later step (the uncertainty, the summary, the tables) would have to carry along.

Parameters:

Name	Type	Description	Default
`candidates`	`DataFrame \| None`	the table, `None` unless `TerminalPhase.keep_candidates`	required

Other Parameters:

Name	Type	Description
`n_rows`	`int`	number of rows of the analysis

Returns:

Type	Description
`dict[str, ndarray]`	The three arrays, or nothing for a batch of several rows and for a row
`dict[str, ndarray]`	without a single candidate window.

extra_dimension ¶

extra_dimension(name)

The extra dimension of a variable with one column per interval or per candidate.

The per-interval parameters (interval_*) carry the extra dimension interval, the candidate windows of the terminal regression (candidate_*) the extra dimension candidate.

Parameters:

Name	Type	Description	Default
`name`	`str`	the name of a two dimensional variable of the analysis.	required

Returns:

Type	Description
`str`	`CANDIDATE_DIM` for a candidate variable, else `INTERVAL_DIM`.

reserved_variables ¶

reserved_variables(values)

Every name the result of an analysis can carry, for the name of a partial area.

A named partial area (NCAOptions.partial_aucs) becomes a variable of the result and may not take a name the analysis writes itself. At the point where the areas are computed the parameters are known, while flags, n, the status variables, the uncertainty variables of a group batch and the summary variables of pkpdutils.result.ParameterResult.summarize are written afterwards, so their names are derived here. The extra dimensions of the result (interval, candidate, extra_dimension) are reserved as well, a variable cannot share its name with a dimension.

Parameters:

Name	Type	Description	Default
`values`	`dict[str, ndarray]`	the parameters of the rows so far	required

Returns:

Type	Description
`set[str]`	The names of the parameters, of `flags` and `n`, of the boolean and
`set[str]`	text variables, of every derived variable of a parameter
`set[str]`	(`pkpdutils.result.UNCERTAINTY_SUFFIXES` and `SUMMARY_SUFFIXES`) and
`set[str]`	of the extra dimensions of the parameters.

evaluate_acceptance ¶

evaluate_acceptance(values, acceptance, *, n_rows)

Which rows meet every threshold of Acceptance, and the flag of the others.

A threshold which is None is not checked; a row which does not carry the value of a threshold which is set (a row without a terminal phase has no adjusted \(R^2\) and no span) fails it. Without a single threshold every row is accepted, which is the default analysis.

The extrapolated fraction is checked on the predicted variant, \((\mathrm{AUC}_{0\text{-}\infty,\mathrm{pred}} - \mathrm{AUC}_{0\text{-}t_\mathrm{last}}) / \mathrm{AUC}_{0\text{-}\infty,\mathrm{pred}}\), as PKanalix and Phoenix WinNonlin do, while the warning flag NCAFlag.EXTRAPOLATION_HIGH of NCAOptions.extrapolation_warning reads the observed variant auc_extrap_fraction.

Parameters:

Name	Type	Description	Default
`values`	`dict[str, ndarray]`	the parameters of the rows, which carry `lambda_z_r2_adj`, `lambda_z_span`, `lambda_z_n_points`, `auc_last` and `auc_inf_pred`	required
`acceptance`	`Acceptance`	the thresholds	required

Other Parameters:

Name	Type	Description
`n_rows`	`int`	number of rows `N`

Returns:

Type	Description
`ndarray`	The accepted rows `(N,)` and the flags of the rows which are not
`ndarray`	(`NCAFlag.NOT_ACCEPTED`).

reference_dose ¶

reference_dose(
    dose_amount, dose_time, dose_duration, *, last
)

Pick one dose per row from the (N, n_dose) dose arrays of a batch.

A row carries the dosing protocol of its sample, the doses at the front and the remaining columns NaN (pkpdutils.timecourse.Timecourses). The core of the analysis works with one reference dose per row: the first dose of the protocol for the single dose analysis and the last dose for the steady state analysis. A 1-D array is taken as one dose per row already.

Parameters:

Name	Type	Description	Default
`dose_amount`	`ndarray \| None`	the amounts `(N, n_dose)`, `None` without doses	required
`dose_time`	`ndarray \| None`	the times `(N, n_dose)`, `None` without doses	required
`dose_duration`	`ndarray \| None`	the infusion durations `(N, n_dose)`, `None` for none	required

Other Parameters:

Name	Type	Description
`last`	`bool`	whether to pick the last dose of every protocol instead of the first

Returns:

Type	Description
`ndarray \| None`	The amount, the time and the duration of the reference dose, each
`ndarray \| None`	`(N,)` or `None` where the input is `None`. A row without a dose - a
`ndarray \| None`	subject of an exchange format whose dose records are missing - gets
`tuple[ndarray \| None, ndarray \| None, ndarray \| None]`	`NaN`: `compute_parameters` then leaves its times unshifted and reports
`tuple[ndarray \| None, ndarray \| None, ndarray \| None]`	its dose-independent parameters, the dose-dependent ones being `NaN`.

is_multiple_dose ¶

is_multiple_dose(
    dose_amount, dose_time, options, *, n_rows
)

Which rows of a batch are analysed as multiple dose rows.

A row whose protocol holds more than one dose is analysed over its dosing intervals (compute_steady_state), every other row as a single dose curve (compute_parameters); options.tau (a steady state curve given with its last dose only) puts every row on the multiple dose path. The decision is taken per row, so a batch mixing the protocols reports the single dose parameters of its single dose rows and the steady state parameters of its multiple dose rows, each row NaN in the variables of the other path.

Parameters:

Name	Type	Description	Default
`dose_amount`	`ndarray \| None`	dose amounts `(N, n_dose)`, `None` without doses	required
`dose_time`	`ndarray \| None`	dose times `(N, n_dose)`, `None` without doses	required
`options`	`NCAOptions`	the options, `tau` is used	required

Other Parameters:

Name	Type	Description
`n_rows`	`int`	number of rows `N`

Returns:

Type	Description
`ndarray`	The boolean mask of the multiple dose rows `(N,)`.

dose_counts ¶

dose_counts(dose_time, n_rows)

Number of doses of the protocol of every row.

Parameters:

Name	Type	Description	Default
`dose_time`	`ndarray \| None`	dose times `(N, n_dose)`, `NaN` padded, `None` without doses	required
`n_rows`	`int`	number of rows `N`	required

Returns:

Type	Description
`ndarray`	The count per row `(N,)`, 0 for a batch without doses.

chunk_bounds ¶

chunk_bounds(n_rows, n_chunks)

Split n_rows rows into n_chunks contiguous ranges of nearly equal size.

The ranges are the ones numpy.array_split cuts (the first n_rows % n_chunks of them are one row longer) and they are contiguous, so a chunk of an array is a slice and therefore a view: a chunked analysis does not copy the batch before it starts.

Parameters:

Name	Type	Description	Default
`n_rows`	`int`	number of rows to split, 0 or more	required
`n_chunks`	`int`	number of ranges, 1 or more	required

Returns:

Type	Description
`list[tuple[int, int]]`	The `(start, stop)` of every range, in row order; a range is empty if
`list[tuple[int, int]]`	there are fewer rows than chunks.

merge_rows ¶

merge_rows(parts, counts)

Stack the parameters of row groups which need not carry the same variables.

A group which does not report a variable of another group is NaN in it (0 in the integer variables flags and c0_method, whose 0 is "none" in both cases), so that the result of a batch is the union of the variables of its groups: a single dose row of a mixed batch carries NaN in the steady state variables and a multiple dose row NaN in cl, vz, vss, auc_inf_dn and cmax_dn; n_doses, which describes the protocol of a row and not the path it took, is filled in for every row of the batch by run_rows. The variables are ordered after the group which reports the most of them.

Parameters:

Name	Type	Description	Default
`parts`	`list[dict[str, ndarray]]`	one mapping of variable name to `(n_k,)` or `(n_k, K)` array per group, in the row order of the batch	required
`counts`	`list[int]`	number of rows `n_k` of every group	required

Returns:

Type	Description
`dict[str, ndarray]`	One array per variable of the union, stacked over the rows.

Raises:

Type	Description
`ValueError`	if a variable has a different second dimension in two groups.

run_rows ¶

run_rows(
    t,
    c,
    *,
    dose_amount,
    dose_time,
    dose_duration,
    route,
    options,
    lloq=None,
    windows=None,
    routes=None,
)

Run the core on (N, n) arrays in chunks, serially or in the worker pool.

The rows are cut into about one chunk per worker, none of them longer than options.chunk_rows rows, which bounds the memory of the vectorized core (pkpdutils.parallel.split_rows). A chunk is a contiguous range of rows, so it is a slice of the input arrays and not a copy of them.

options.n_workers decides how many workers run them (pkpdutils.parallel.resolve_workers): None is automatic and stays in the calling thread below pkpdutils.parallel.NCA_WORKER_THRESHOLD rows, 1 is serial and any other number is taken as given. The chunks of a parallel run are mapped in order over the shared thread pool (pkpdutils.parallel.executor), since the core is vectorized numpy and releases the GIL for most of its time: the chunks are neither pickled nor copied and the pool starts in half a millisecond. The temporaries of the core then live for as many chunks as run at once, so a run holds up to min(n_workers, len(chunks)) * options.chunk_rows rows of them instead of chunk_rows.

The dose arrays carry the dosing protocol of every row, (N, n_dose) padded with NaN. A row whose protocol holds more than one dose, and every row of an analysis with options.tau, is analysed over the dosing intervals (is_multiple_dose, pkpdutils.nca.steady_state.compute_steady_state); a single dose row is reduced to the one dose of its protocol (reference_dose). A 1-D array (N,) is one dose per row. A batch mixing the two carries the union of the variables, every row NaN in the variables of the other path (merge_rows).

Parameters:

Name	Type	Description	Default
`t`	`ndarray`	times `(N, n)`	required
`c`	`ndarray`	values `(N, n)`	required
`dose_amount`	`ndarray \| None`	dose amounts per row `(N, n_dose)`, `None` without doses	required
`dose_time`	`ndarray \| None`	dose times per row `(N, n_dose)`, `None` for 0	required
`dose_duration`	`ndarray \| None`	infusion durations per row `(N, n_dose)`, `None` for none	required
`route`	`Route \| None`	route of the batch	required
`options`	`NCAOptions`	the options	required
`lloq`	`ndarray \| None`	limit of quantification per row `(N,)`, `None` for none; `NCAOptions.lloq` wins over it (`resolve_lloq`)	`None`
`windows`	`ndarray \| None`	the terminal window of single rows `(N, 2)`, `NaN` for a row without one (`TerminalPhase.windows`, `sample_windows`)	`None`
`routes`	`ndarray \| None`	the route of every row `(N,)`, for a batch whose samples were given different ones (`Timecourses.routes`); `None` for the one route of `route`. The rows are grouped by route and every group is run on its own, so that the parameters which depend on the route (`c0`, `cl` against `cl_f`, `tlag`, the value at the dose time) follow the row; the result is the union of the variables of the groups (`merge_rows`), every row `NaN` in the variables of the other routes.	`None`

Returns:

Type	Description
`dict[str, ndarray]`	One `(N,)` array per parameter and `flags`, and one `(N, K)` array per
`dict[str, ndarray]`	per-interval parameter of a multiple dose batch (`K` dosing intervals).

nca ¶

nca(timecourses, *, options=None)

Non-compartmental analysis of a batch of timecourses.

The rows are analysed in chunks of at most options.chunk_rows rows, in the calling thread or, for a large batch or an explicit options.n_workers, in the shared thread pool (run_rows); a multiple dose analysis is chunked the same way.

A sample whose dosing protocol holds more than one dose (and every sample of an analysis with options.tau) is analysed over its dosing intervals: the point parameters are computed from the last dose on, the per-interval parameters (interval_* over the dimension interval) over every dosing interval and the steady state parameters from the last one, see pkpdutils.nca.steady_state. The decision is taken per sample, so a batch mixing single dose and multiple dose subjects reports cl/cl_f for the single dose samples and cl_ss/cl_ss_f for the multiple dose ones; every sample is NaN in the variables of the other path.

A batch of group curves (sd or se per point) also carries the uncertainty of every parameter, by default from the parametric bootstrap (options.uncertainty, pkpdutils.nca.uncertainty): x_sd, x_se, x_ci_low, x_ci_high, under BootstrapSpread.SD draws also x_pi_low, x_pi_high, and, for log-normal parameters, x_geomean, x_geocv. The delta method can add NCAFlag.DELTA_WINDOW_CHANGE to the flags of a sample.

A batch whose samples were given by different routes (the coordinate route, Timecourses.routes) is analysed per route: the rows are grouped and every group runs on its own, so that c0, cl against cl_f, tlag and the value at the dose time follow the row rather than the batch. The result carries the union of the variables, every sample NaN in the variables of the other routes.

NCAOptions.units converts the named variables of the result to the reporting units at the end (pkpdutils.result.ParameterResult.to_units); the analysis itself runs in the units of the batch.

Parameters:

Name	Type	Description	Default
`timecourses`	`Timecourses`	the batch	required

Other Parameters:

Name	Type	Description
`options`	`NCAOptions \| None`	the options, defaults for `None`

Returns:

Type	Description
`NCAResult`	The parameters, their uncertainty variables and the number of subjects
`NCAResult`	`n` over the sample dimensions of the batch.

row_routes ¶

row_routes(timecourses, n_rows)

The route of a batch, or the route of every one of its rows.

A batch which carries the coordinate route along a sample dimension was given by several routes (Timecourses.routes), and the analysis follows the route of every row rather than one route of the batch. A batch with one route keeps the fast path: the route is one value and the rows run in one group.

Parameters:

Name	Type	Description	Default
`timecourses`	`Timecourses`	the batch.	required
`n_rows`	`int`	number of rows of the flattened batch.	required

Returns:

Type	Description
`Route \| None`	The one route of the batch and `None`, or `None` and the route of every
`ndarray \| None`	row `(N,)`.

dose_times ¶

dose_times(
    dose_amount,
    dose_time,
    dose_duration,
    options,
    *,
    n_rows,
)

The time of the first and of the reference dose of every row.

The named partial areas are relative to the first dose of the protocol while the point parameters of a row are relative to its reference dose (the last dose of a multiple dose row, reference_dose_amount), so the two times are what translates between the two frames.

Parameters:

Name	Type	Description	Default
`dose_amount`	`ndarray \| None`	dose amounts `(N, n_dose)`, `None` without doses	required
`dose_time`	`ndarray \| None`	dose times `(N, n_dose)`, `None` without doses	required
`dose_duration`	`ndarray \| None`	infusion durations `(N, n_dose)`, `None` for none	required
`options`	`NCAOptions`	the options, `tau` is used by `is_multiple_dose`	required

Other Parameters:

Name	Type	Description
`n_rows`	`int`	number of rows `N`

Returns:

Type	Description
`ndarray`	The time of the first dose and the time of the reference dose per row,
`ndarray`	both 0 where the row carries no dose.

reference_dose_amount ¶

reference_dose_amount(
    dose_amount,
    dose_time,
    dose_duration,
    options,
    *,
    n_rows,
)

The dose amount every row is analysed against.

The first dose of the protocol for a single dose row and the last one for a multiple dose row (is_multiple_dose), the dose the parameters of the row are divided by (cl, cl_ss, the dose normalized variables of pkpdutils.nca.result.NCAResult.dose_normalized).

Parameters:

Name	Type	Description	Default
`dose_amount`	`ndarray \| None`	dose amounts `(N, n_dose)`, `None` without doses	required
`dose_time`	`ndarray \| None`	dose times `(N, n_dose)`, `None` without doses	required
`dose_duration`	`ndarray \| None`	infusion durations `(N, n_dose)`, `None` for none	required
`options`	`NCAOptions`	the options, `tau` is used by `is_multiple_dose`	required

Other Parameters:

Name	Type	Description
`n_rows`	`int`	number of rows `N`

Returns:

Type	Description
`ndarray \| None`	The amount per row `(N,)`, `None` for a batch without doses.

nca_single ¶

nca_single(timecourse, *, options=None)

Non-compartmental analysis of one timecourse.

Parameters:

Name	Type	Description	Default
`timecourse`	`Timecourse`	the curve	required

Other Parameters:

Name	Type	Description
`options`	`NCAOptions \| None`	the options, defaults for `None`

Returns:

Type	Description
`NCAResult`	The parameters, without sample dimensions.

area_between ¶

area_between(
    t, c, start, end, *, route, options, routes=None
)

Area of every row between two times, with the bounds interpolated.

The core of partial_auc and of the named partial areas of NCAOptions.partial_aucs: the values at the two bounds are interpolated with the trapezoid rule of options.auc_method (pkpdutils.nca.auc.interpolate_at), the value at the dose is added when the route allows it (_insert_dose_value) and the area is summed with the same rule.

Parameters:

Name	Type	Description	Default
`t`	`ndarray`	times `(N, n)`, relative to the dose of the interval	required
`c`	`ndarray`	values `(N, n)`	required
`start`	`ndarray`	start of the interval per row `(N,)`	required
`end`	`ndarray`	end of the interval per row `(N,)`	required

Other Parameters:

Name	Type	Description
`route`	`Route \| None`	route of the batch, which decides the value at the dose
`options`	`NCAOptions`	the options, `auc_method` and `c0_method` are used
`routes`	`ndarray \| None`	the route of every row `(N,)` for a batch of several routes (`Timecourses.routes`), which wins over `route`

Returns:

Type	Description
`ndarray`	The area per row and the rows whose observed range covers both bounds;
`ndarray`	the area of a row which is not covered is meaningless.

named_partial_aucs ¶

named_partial_aucs(
    t, c, values, *, route, options, shift=None, routes=None
)

The named partial areas of NCAOptions.partial_aucs of every row.

The area between the two times of the interval, both relative to the first dose of the protocol. An interval which reaches beyond the last measurable value is completed with the terminal regression, as Phoenix WinNonlin does for a partial area past Tlast: the tail from \(t_\mathrm{last}\) to \(t_\mathrm{end}\) of

\[\hat C(t) = \hat C_\mathrm{last}\, e^{-\lambda_z (t - t_\mathrm{last})} \quad\text{is}\quad \frac{\hat C_\mathrm{last}}{\lambda_z} \left(1 - e^{-\lambda_z (t_\mathrm{end} - t_\mathrm{last})}\right),\]

and the row is reported in the returned mask (NCAFlag.PARTIAL_EXTRAPOLATED); without a terminal phase such a row is NaN. AUC(0-72), the primary exposure of a drug with a long half-life in ICH M13A (2024), and the pAUC of the modified release guidances are intervals of this kind.

Parameters:

Name	Type	Description	Default
`t`	`ndarray`	times `(N, n)`, relative to the first dose of the protocol	required
`c`	`ndarray`	values `(N, n)`	required
`values`	`dict[str, ndarray]`	the parameters of the rows so far, which carry `tlast`, `clast_pred` and `lambda_z`	required

Other Parameters:

Name	Type	Description
`route`	`Route \| None`	route of the batch
`options`	`NCAOptions`	the options, `partial_aucs` and `auc_method` are used
`shift`	`ndarray \| None`	the time of the reference dose of every row relative to the first dose `(N,)`, which puts `tlast` into the times of `t`; `None` for a single dose analysis, where they are the same
`routes`	`ndarray \| None`	the route of every row `(N,)` for a batch of several routes (`Timecourses.routes`), which wins over `route`

Returns:

Type	Description
`dict[str, ndarray]`	One `(N,)` array per named area and the rows whose area was completed
`ndarray`	with the terminal regression; a row which reaches beyond the last
`tuple[dict[str, ndarray], ndarray]`	measurable value without a terminal phase is `NaN` and is not among
`tuple[dict[str, ndarray], ndarray]`	them, since nothing was extrapolated.

sample_windows ¶

sample_windows(timecourses, phase)

The terminal window of every row of a batch, NaN for a row without one.

TerminalPhase.windows is keyed by the sample label: the label of a batch with one sample dimension, the tuple of labels of a batch with several, and the string "*" for every sample the mapping does not name.

Parameters:

Name	Type	Description	Default
`timecourses`	`Timecourses`	the batch	required
`phase`	`TerminalPhase`	the terminal phase options, `windows` is read	required

Returns:

Type	Description
`ndarray \| None`	The windows `(N, 2)` in the order of the rows of the analysis, or
`ndarray \| None`	`None` when no window is given.

Raises:

Type	Description
`ValueError`	if a key of `windows` is no label of the batch (and is not `"*"`).

sample_keys ¶

sample_keys(ds, sample_dims)

The label of every sample of a dataset, in the row order of the analysis.

The label of a batch with one sample dimension is the value of its coordinate (the integer position without one), the label of a batch with several is the tuple of the values, in the order of the dimensions. The values are python objects, so that they compare equal to the keys a user writes (TerminalPhase.windows, NCAResult.terminal_windows).

Parameters:

Name	Type	Description	Default
`ds`	`Dataset`	the dataset of the batch or of a result	required
`sample_dims`	`tuple[str, ...]`	the sample dimensions, in the order the samples are enumerated	required

Returns:

Type	Description
`list[Any]`	One label per sample, in C order of `sample_dims`; a batch without
`list[Any]`	sample dimensions gives one label `()`.

partial_auc ¶

partial_auc(timecourses, t_start, t_end, *, options=None)

Area under the curve of every sample between two times relative to the first dose.

The values at the bounds are interpolated with the trapezoid rule of options.auc_method (pkpdutils.nca.auc.interpolate_at) and the area is summed with the same rule; a sample whose observed range does not cover [t_start, t_end] gives NaN.

An interval which starts before the first sample of a curve but not before its dose - AUC(0-12) of a schedule whose first sample is at 0.5 h - is the common request, and the value at the dose comes from the route: 0 for an extravascular dose (nothing is absorbed yet, so the area up to the first sample is the triangle below it, the convention of Phoenix AUC(0-t)), the back-extrapolated c0 for an intravenous bolus (bolus_c0, the estimate compute_parameters uses for the single dose areas) and NaN for an infusion, whose curve rises over the infusion in a way no extrapolation of the samples describes, and for a batch without a route.

Only options.auc_method and options.c0_method are used: the area is read from the values as they are, so lloq, blq and kind do not apply and no uncertainty is propagated.

Parameters:

Name	Type	Description	Default
`timecourses`	`Timecourses`	the batch	required
`t_start`	`float`	start of the interval, in the time unit of the batch, relative to the first dose of the protocol	required
`t_end`	`float`	end of the interval, greater than `t_start`	required

Other Parameters:

Name	Type	Description
`options`	`NCAOptions \| None`	the options, defaults for `None`

Returns:

Type	Description
`DataArray`	The areas over the sample dimensions, named `auc_partial`, with the unit of `auc_last`.

Raises:

Type	Description
`ValueError`	if `t_end <= t_start`, or if a sample dimension or a coordinate of the batch collides with `auc_partial` (`check_coordinate_collision`).