pk

The non-compartmental analysis of a PK observable, with pkpdutils.

A PK observable analyses one timecourse of every simulation of a chunk with pkpdutils.nca: the timecourses are handed over as Timecourses.from_arrays with the time points of every simulation (the padding with NaN is trimmed away in groups of the same length), and the doses the plan of every point assigns to the dose target. Every parameter pkpdutils derives is a value per simulation <id>.<parameter>, and <id>.flags the flags of the analysis (pkpdutils.NCAFlag).

Which parameters pkpdutils derives depends on the dosing (a multiple dosing adds the parameters of the dosing interval, a dose the clearance and the volume) and on the options. compile_pk finds them and their units by an analysis of a synthetic timecourse for every plan of a run, dosed at every time the plan assigns the dose target, a zero value included, so every point of the result has the same variables whatever the order of the values of a dimension; a point whose dose is zero has NaN for the parameters of that dose. The points of a chunk are analysed in groups of the same number of doses and of time points, each group trimmed to its time points, so no row is padded and a parameter does not depend on the chunking.

pkpdutils is imported when a PK observable is compiled or evaluated, not on the import of sbmlsim: it imports pandas, scipy and xarray, about a second.

DoseSpec `dataclass` ¶

DoseSpec(target, amount, unit)

Where the doses of a PK observable come from.

Attributes:

Name	Type	Description
`target`	`str \| None`	the target of the model whose values the plans assign, `None` for a fixed dose.
`amount`	`float`	the fixed dose at the start, ignored for a target.
`unit`	`str`	the unit of the amounts, for a target its unit in the model.

PKNode `dataclass` ¶

PKNode(
    id,
    selection,
    time_unit,
    unit,
    dose,
    route,
    options,
    parameters,
)

A PK observable compiled against the models of a run.

Attributes:

Name	Type	Description
`id`	`str`	the id of the observable.
`selection`	`str`	the timecourse it analyses.
`time_unit`	`str`	the unit of the time.
`unit`	`str`	the unit of the timecourse.
`dose`	`DoseSpec \| None`	where its doses come from, `None` without doses.
`route`	`str \| None`	the route of the doses, the name of a `pkpdutils.Route`.
`options`	`Any`	the `pkpdutils.NCAOptions`, `None` for the defaults.
`parameters`	`tuple[str, ...]`	the parameters it gives, `flags` among them.

outputs `property` ¶

outputs

Get the ids of the values of its parameters.

output ¶

output(parameter)

Get the id of the value of a parameter, <id>.<parameter>.

doses_of ¶

doses_of(plan, dose, *, zeros=False)

Get the times and the amounts of the doses of the plan of a point.

A fixed dose is one dose at the start. The doses of a target are the positive values the plan assigns to it: a value before the initialization at the start and the values of its changes at their times, where a change at the start replaces the value before the initialization; the values of a presimulation are no doses. The times are the times of the result, i.e. shifted by the time_shift of the plan.

Parameters:

Name	Type	Description	Default
`plan`	`Plan`	the plan of a point, with its values.	required
`dose`	`DoseSpec`	where the doses come from.	required
`zeros`	`bool`	whether a value which is not positive, e.g. the zero dose of a control, is a dose as well, so every time the plan assigns the target is a dose time; the probe of `compile_pk` counts them, the analysis of a point does not.	`False`

Returns:

Type	Description
`tuple[ndarray, ndarray]`	The times and the amounts, sorted by time.

Raises:

Type	Description
`ValueError`	if the plan assigns a formula to the target.

compile_pk ¶

compile_pk(
    observable, *, unit, time_unit, dose_unit, plans
)

Compile a PK observable, see the module.

Parameters:

Name	Type	Description	Default
`observable`	`PK`	the definition.	required
`unit`	`str`	the unit of its timecourse.	required
`time_unit`	`str`	the unit of the time of the model.	required
`dose_unit`	`str \| None`	the unit of the dose target in the model; `None` for a fixed dose or without a dose.	required
`plans`	`Sequence[Plan]`	the plans of the run, each with the values of a point, whose dose times decide the parameters: every assignment of the dose target is a dose of the probe, a zero value included, so the first point of a values dimension or a dimension with `at` which sets the target gives the parameters of the doses of every point.	required

Returns:

Type	Description
`tuple[PKNode, dict[str, str]]`	The compiled observable and the unit of each of its outputs.

Raises:

Type	Description
`ValueError`	if the timecourse or the dose target has no unit, the route is none of pkpdutils or an infusion, a plan doses by a formula, a simulation has no time span, there is no plan, or a parameter to keep is none pkpdutils derives.

evaluate_pk ¶

evaluate_pk(node, time, values, plans)

Analyse the timecourses of the points of a chunk.

The points are analysed in groups of the same number of doses and of the same number of time points, each group trimmed to that number, so pkpdutils sees no padding: it sums the rows pairwise, and padding would change the last bits of a parameter with the chunking.

Parameters:

Name	Type	Description	Default
`node`	`PKNode`	the observable.	required
`time`	`ndarray`	the time points `(n_points, n_rows)`, padded with `NaN`.	required
`values`	`ndarray`	the timecourse, of the shape of `time`.	required
`plans`	`Sequence[Plan]`	the plan of every point, with its values.	required

Returns:

Type	Description
`dict[str, ndarray]`	The output id of every parameter -> its values `(n_points, 1)`, `NaN`
`dict[str, ndarray]`	where pkpdutils gives no value for a point.

pk

DoseSpec dataclass ¶

PKNode dataclass ¶

outputs property ¶

output ¶

doses_of ¶

compile_pk ¶

evaluate_pk ¶

DoseSpec `dataclass` ¶

PKNode `dataclass` ¶

outputs `property` ¶