Skip to content

result.scan

The result of a scan, see sbmlsim.simulator.Simulator.run.

A ScanResult wraps one xarray.Dataset:

  • dimensions: the dimensions of the scan in their order, then time when every simulation has the same output times and _point otherwise, i.e. (*dims, time) or (*dims, _point), the layout of the timecourses of pkpdutils;
  • variables: one per selection over (*dims, time) or (*dims, _point); in the ragged layout of _point every simulation keeps its own time points and the variable time over (*dims, _point) holds them, padded with NaN; status over the dimensions of the scan for a run with on_error="flag";
  • coordinates: the labels of every dimension, every changed target of a dimension of values along its dimension (<dimension>.<target> when the target is also a variable of the result, which keeps the plain name), and time on a grid;
  • attrs: dims, the dimensions of the scan in their order, units, the unit of every variable and coordinate, scan and integrator_settings, the provenance, changes, the times of the changes after the start of the simulations in the time of the result, and errors for a run with on_error="flag".

The output of a simulation has two time points at the time of a change after the start, the state before the change and the state after it, as at an event of the model; the time of a grid then appears twice. The idioms of xarray which need a unique index raise at such a time, e.g. ds.interp, ds.sel with method="nearest" and ds.reindex: ScanResult.interpolate puts a result on other times, sel(time=t) at a change selects both rows and isel one of them.

nca and to_timecourses hand a PK analysis and a timecourse over to pkpdutils, whose layout (*dims, time) the result has.

xarray does the rest: res["[X]"].sel(dose=10), res.ds.to_dataframe().

ScanResult 

ScanResult(ds)

The result of a scan, see the module.

Attributes:

Name Type Description
ds

the dataset.

Wrap a dataset which follows the layout of the module.

units property 

units

Get the unit of every variable and coordinate.

dims property 

dims

Get the dimensions of the scan which the result has, in their order.

ragged property 

ragged

Check whether every simulation keeps its own time points.

variables property 

variables

Get the variables of the selections, without time and status.

quantity 

quantity(key, ureg=None)

Get the values of a variable or coordinate with its unit.

The cv of a summary is dimensionless; a variable with a dimension statistic which holds statistics of different units needs a selection of the statistic first.

Parameters:

Name Type Description Default
key str

the variable or coordinate.

 required
ureg UnitRegistry | None

the unit registry of the quantity, the one of the package by default; e.g. the registry of a simulation experiment.

 None

Raises:

Type Description
ValueError

if the key holds labels, has no unit, or mixes units.

nca 

nca(observable)

Get the analysis of a PK observable as the result of pkpdutils.

The kept parameters of the observable, <id>.<parameter>, with their units and its flags over the dimensions of the scan. A point which failed has NaN parameters and the flags NCAFlag.NO_DATA, which pkpdutils gives a sample without data.

Parameters:

Name Type Description Default
observable str

the id of the PK observable.

 required

Returns:

Type Description
NCAResult

The pkpdutils.NCAResult.

Raises:

Type Description
KeyError

if the result does not keep the flags of the observable.

to_timecourses 

to_timecourses(key, **kwargs)

Get a timecourse of the result as the timecourses of pkpdutils.

pkpdutils takes a time once: of the states before and after a change at its time (changes of the attributes) the timecourse has the state after it, as a PK observable analyses it.

Parameters:

Name Type Description Default
key str

the variable, a timecourse.

 required
**kwargs Any

the other arguments of Timecourses.from_arrays, e.g. dose and route.

 {}

Returns:

Type Description
Timecourses

The pkpdutils.Timecourses over the dimensions of the scan.

Raises:

Type Description
ValueError

if the variable is no timecourse of the result.

sel 

sel(**indexers)

Select by labels, see xarray.Dataset.sel.

isel 

isel(**indexers)

Select by positions, see xarray.Dataset.isel.

time_points 

time_points()

Get the times of the grid, or the union of the times of the simulations.

A time which a simulation has twice, the states before and after a change or an event of the model at it, is twice in the union, so an interpolation onto the union keeps the jump, see interpolate.

interpolate 

interpolate(times)

Get the result on a grid of times.

Every simulation is interpolated linearly onto the times, see sbmlsim.result.timecourse.grid_weights; a time outside of a simulation is NaN. A simulation has the states before and after a change and an event of the model at its time, and time points closer than the resolution of its time (sbmlsim.simulator.plan.time_tolerance of its first and last time) are one jump: a time of the grid before a change is interpolated toward the state before it, the time of a change (changes of the attributes) sees the state after it, and the first of two equal times of the grid the state before it. The variables without a time stay as they are.

Parameters:

Name Type Description Default
times ArrayLike | Quantity

the times of the grid, numbers in the time unit of the result or a quantity.

 required

Returns:

Type Description
ScanResult

The result with the dimension time.

Raises:

Type Description
ValueError

if the times are a quantity and the result has no unit of time or another one, see time_magnitudes.

summary 

summary(
    dims=None,
    statistics=STATISTICS,
    quantiles=(),
    times=None,
)

Get statistics of the variables over dimensions of the scan.

A result in the ragged layout is interpolated onto the union of its time points first, or onto times; the union has a time point per step of every simulation, so it is refused above MAX_UNION_ELEMENTS elements (points of the scan times time points).

sd is the sample standard deviation and cv the ratio of sd and mean; a quantile q is the statistic q<q>, e.g. q0.05. NaN, e.g. of a failed point, is skipped. The unit of a variable is the unit of its statistics, except of cv, a ratio, which statistic_units in the attributes records.

Parameters:

Name Type Description Default
dims str | Sequence[str] | None

the dimensions to reduce, every dimension of the scan by default.

 None
statistics Sequence[str]

statistics of STATISTICS.

 STATISTICS
quantiles Sequence[float]

quantiles between 0 and 1.

 ()
times ArrayLike | Quantity | None

the times to interpolate onto before, numbers in the time unit of the result or a quantity; the union of the time points of a ragged result by default.

 None

Returns:

Type Description
ScanResult

The result with the dimension statistic instead of the reduced
ScanResult

dimensions.

Raises:

Type Description
ValueError

if a dimension is no dimension of the scan, a statistic is unknown, a quantile is outside of [0, 1] or the union of the time points of a ragged result is too large.

to_netcdf 

to_netcdf(path)

Write the result as netCDF4, the attributes as JSON.

The attributes must be JSON serializable, numpy scalars and arrays are written as numbers and lists.

from_netcdf classmethod 

from_netcdf(path)

Read a result written by to_netcdf.

Raises:

Type Description
ValueError

if the file has no attributes of a result.

time_magnitudes 

time_magnitudes(times, unit, owner='The model')

Get times as numbers in a unit of time.

Parameters:

Name Type Description Default
times ArrayLike | Quantity

numbers in the unit or a quantity.

 required
unit str | None

the unit of time of a model or a result; None, empty or dimensionless if it has none.

 required
owner str

what has the unit, for a message.

 'The model'

Returns:

Type Description
ndarray

The times, one dimensional.

Raises:

Type Description
ValueError

if the times are a quantity and the owner has no unit of time, or one the quantity cannot be converted to.