Skip to content

nca.result

Units of the parameters and the result container of the NCA.

An NCAResult wraps an xarray.Dataset with one variable per parameter over the sample dimensions of the analysed batch, attrs["units"] on every variable and the integer variable flags (pkpdutils.nca.options.NCAFlag). The units are derived from the units of the input with pint: an area carries unit * time_unit, a rate 1 / time_unit, a clearance dose_unit / (unit * time_unit) converted to liter / hour (or per kilogram), a volume converted to liter (or per kilogram), see pkpdutils.units.

NCAResult 

NCAResult(ds)

Bases: ParameterResult

Parameters of a non-compartmental analysis as an xarray.Dataset.

One variable per parameter over the sample dimensions of the analysed Timecourses, attrs["units"] on every variable, the uncertainty variables of pkpdutils.nca.uncertainty and the integer variable flags (NCAFlag). See pkpdutils.result.ParameterResult for the interface.

dose property 

dose

The dose amount of every sample, None for a result without doses.

The coordinate dose_amount the analysis carries over from the batch: the first dose of a single dose sample and the last dose of a multiple dose one, the dose its parameters are divided by.

partial_aucs property 

partial_aucs

The named partial areas of the analysis with their intervals.

NCAOptions.partial_aucs as the analysis ran it, stored by nca in the attributes of the dataset: the name of every area to its (t_start, t_end), both relative to the first dose of the protocol. The figures read it to shade an area (pkpdutils.plot.plot_nca), and it is empty for an analysis which computed none.

Returns:

Type Description
dict[str, tuple[float, float]]

Name to interval, empty without named areas.

has_intervals property 

has_intervals

Whether the result carries the parameters of the single dosing intervals.

dose_normalized_parameters 

dose_normalized_parameters()

The parameters dose_normalized normalizes without being asked.

Returns:

Type Description
list[str]

The concentration and exposure parameters of the result, those
list[str]

whose unit expression is {unit} or ({unit}) * ({time})
list[str]

(DOSE_NORMALIZED_EXPRESSIONS), in the order of the dataset;
list[str]

a parameter which is itself dose normalized is left out.

dose_normalized 

dose_normalized(parameters=None)

A copy of the result with the dose normalized variables of its parameters.

The dose normalized variable of a parameter is the parameter divided by the dose of its sample,

\[x_\mathrm{dn} = \frac{x}{D},\]

with the unit of the parameter per dose unit; NaN where the sample has no positive dose (a placebo arm). It is the form ICH M13A (2024) asks for when strengths are compared, and the *D family of the CDISC codelist (Phoenix AUClast_D, Cmax_D; PKNCA pk.calc.dn).

The variable is named x_dn, except for auc_inf_obs, whose normalized variable is the auc_inf_dn every analysis already reports (DOSE_NORMALIZED_NAMES). Normalize before summarizing: the summary of a dimension carries no dose coordinate any more.

Parameters:

Name Type Description Default
parameters Sequence[str] | None

the parameters to normalize, the concentrations and exposures of the result by default (dose_normalized_parameters).

 None

Returns:

Type Description
NCAResult

A copy of the result with one dose normalized variable per
NCAResult

parameter added.

Raises:

Type Description
ValueError

if the result carries no dose (an analysis of a batch without doses), or if a name is not a parameter of the result.

exclude 

exclude(mask=None, *, reason='', **indexers)

A copy of the result with further samples marked as excluded.

The excluded samples stay in the result - to_dataframe reports every row and the excluded column says which - and are left out of summarize, summary_table, ParameterResult.sample and therefore of every statistic of pkpdutils.stats which reads a result, unless include_excluded=True asks for them. It is the record-level and subject-level exclusion a regulatory analysis documents (CDISC ADNCA carries the subject-level exclusion flags; PKNCA the exclude_nca_* rules), and the same mechanism pkpdutils.nca.options.Acceptance(exclude=True) uses.

Parameters:

Name Type Description Default
mask ArrayLike | DataArray | None

the samples to exclude, a boolean array over the sample dimensions or a boolean xarray.DataArray along them; None with indexers to name single samples.

 None
reason str

the text written into excluded_reason of the newly excluded samples; the reason of a sample which was already excluded is kept.

 ''
**indexers Any

a label or a list of labels per sample dimension, the values of its dimension coordinate (the positions for a dimension without one); a dimension without an indexer is excluded as a whole.

 {}

Returns:

Type Description
NCAResult

A copy of the result with excluded set and excluded_reason
NCAResult

written.

Raises:

Type Description
ValueError

if neither mask nor indexers are given, if both are, if the mask does not have the shape of the samples, if the name of an indexer is not a sample dimension, or if a label is not on its dimension.

terminal_windows 

terminal_windows()

The terminal window of every sample, keyed as TerminalPhase.windows.

lambda_z_t_first and lambda_z_t_last of every sample with a terminal phase, keyed by the sample label (the label of a result with one sample dimension, the tuple of labels of a result with several), so that

# not executed
reviewed = nca(batch, options=options.model_copy(
    update={"terminal": TerminalPhase(windows=result.terminal_windows())}
))

re-runs the analysis with exactly the windows of result. A sample without a terminal phase carries no window and follows TerminalPhase.method again, which reproduces its result as well.

Returns:

Type Description
dict[Any, tuple[float, float]]

Sample label to (t_first, t_last), in the times of the analysis
dict[Any, tuple[float, float]]

(relative to the reference dose of the sample).

intervals 

intervals()

The per-interval parameters as one row per sample and dosing interval.

The interval variables carry the dimension interval beyond the sample dimensions and are therefore point variables, which to_dataframe leaves out; this frame reports them with the sample coordinates and the number of the interval.

Returns:

Type Description
DataFrame

One row per sample and interval with the sample coordinates (the
DataFrame

dimension coordinates and the coordinates along them, such as the
DataFrame

weight of a subject), interval and every interval_* variable;
DataFrame

an empty frame for a single dose result.

parameter_unit cached 

parameter_unit(
    expression,
    *,
    unit,
    time_unit,
    dose_unit,
    amount_unit=None,
    volume_unit=None,
)

Unit of a parameter and the factor from its raw unit to the reported unit.

The unit of a parameter depends only on the strings of the signature, of which an analysis has a handful (PARAMETER_UNITS holds one expression per parameter), while the derivation costs several pint conversions; the result is therefore cached (pkpdutils.units.CACHE_SIZE entries).

Parameters:

Name Type Description Default
expression str

pint expression with the placeholders {unit}, {time}, {dose}, {amount} and {volume}, e.g. "({unit}) * ({time})"

 required
unit str

unit of the values

 required
time_unit str

unit of the times

 required
dose_unit str | None

unit of the doses, None without doses (an expression with {dose} then raises ValueError)

 required
amount_unit str | None

unit of an excreted amount, None outside the urinary excretion analysis (pkpdutils.nca.urine)

 None
volume_unit str | None

unit of a collected volume, None outside the urinary excretion analysis

 None

Returns:

Type Description
str

The canonical unit string and the factor a magnitude in the raw unit is
float

multiplied with to be in the canonical unit (volumes to liter,
tuple[str, float]

clearances to liter per hour, else 1).

Raises:

Type Description
ValueError

if expression uses a placeholder whose unit is None.