scan¶
The results of the scans of a model: the dimension, the timecourse of a point, the state after a change.
sbmlsim 0.9 returns a scan as a ScanResult with the layout (*dims, time)
and, at the time of a change after the start, the states before and after it.
The PK of the scans of a model (<model>_pk.py) and its own figures read the
timecourse of one point of a scan as sbmlsim 0.8 gave it, with the state after
a change only, so that their numbers and figures stay the same:
# not executed
dim = single_dimension(res)
for k in range(res.ds.sizes[dim]):
time, values = point_timecourse(res, "[Cve_hctz]", **{dim: k})
state_after_changes(res) gives the whole result in that form, for the figures
which read the arrays of a result instead of one point; a ragged result of
several simulations on the time points of a figure (plot_times), not on the
union of their steps.
A simulation without steps or times outputs the steps of the integrator, a
scan of such simulations is ragged: every point keeps its own time points
((*dims, _point), padded with NaN). start_values(res, key) and
end_values(res, key) give the first and the last value of a variable at every
point of a scan in both layouts, e.g. the dose or the scanned parameter at the
start and the amount in the urine at the end.
A run over the draws of the fitted parameters adds the dimension of the draws to
every result (pkpdsim.uncertainty); scan_dimensions(res, across) gives the
dimensions of the scan without it, and point_band(res, key, across, quantiles,
**point) the quantiles and the median of the draws at a point of the scan.
Get the dimension of a scan of one dimension.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
res
|
ScanResult
|
the result of the scan. |
required |
Returns:
| Type | Description |
|---|---|
str
|
The id of the dimension. |
Raises:
| Type | Description |
|---|---|
ValueError
|
if the scan has no dimension or several. |
Get the dimensions of a scan without the dimension of the draws.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
res
|
ScanResult
|
the result of the scan. |
required |
across
|
str | None
|
the dimension of the draws, |
None
|
Returns:
| Type | Description |
|---|---|
list[str]
|
The ids of the dimensions, in the order of the result. |
Get a result with the state after a change at its time, every time once.
The output of sbmlsim 0.9 has the states before and after a change at its
time; the figures and analyses of a model read the state after it, as
sbmlsim 0.8 gave it. The result is interpolated onto its time points
without the repeated ones (ScanResult.interpolate, which gives the state
after a change at its time). It is the result of point_timecourse for all
points of a scan at once, as a ScanResult; a result without a change is
unchanged.
A ragged result of several simulations (the steps of the integrator, a
simulation without steps or times) is interpolated onto the time points
of a figure instead (sbmlsim.result.timecourse.plot_times: a few hundred,
dense where the simulations stepped densely, with the times of the
changes), not onto the union of the steps of all its simulations, whose
size grows with the square of the number of simulations: a scan of 11
points over 100 draws took more than 40 GB.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
res
|
ScanResult
|
the result of a simulation or a scan. |
required |
Returns:
| Type | Description |
|---|---|
ScanResult
|
The result on its time points, each time once. |
Get the value of a variable at the start of every point of a scan.
The first output of every simulation, on a grid (time) and in the ragged
layout of the steps of the integrator (_point) alike.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
res
|
ScanResult
|
the result of the scan, positional only. |
required |
key
|
str
|
the variable, a timecourse, positional only. |
required |
Returns:
| Type | Description |
|---|---|
DataArray
|
The values over the dimensions of the scan, with their coordinates. |
Raises:
| Type | Description |
|---|---|
ValueError
|
if the variable is no timecourse. |
Get the value of a variable at the end of every point of a scan.
The last output of every simulation: the last time of a grid (time), the
last time before the padding of every point of a ragged result (_point);
a point whose simulation failed has NaN.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
res
|
ScanResult
|
the result of the scan, positional only. |
required |
key
|
str
|
the variable, a timecourse, positional only. |
required |
Returns:
| Type | Description |
|---|---|
DataArray
|
The values over the dimensions of the scan, with their coordinates. |
Raises:
| Type | Description |
|---|---|
ValueError
|
if the variable is no timecourse. |
Get the timecourse of a variable at one point of a scan, as sbmlsim 0.8 gave it.
At the time of a change after the start the timecourse has the state after
the change only (sbmlsim.result.timecourse.without_states_before), and a
result whose simulations have different times loses its padding.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
res
|
ScanResult
|
the result of the scan, positional only. |
required |
key
|
str
|
the variable, a timecourse, positional only, so that a dimension
of any name, also |
required |
**point
|
int
|
the position of the point along every dimension of the scan,
e.g. |
{}
|
Returns:
| Type | Description |
|---|---|
tuple[ndarray, ndarray]
|
The time points and the values. |
Raises:
| Type | Description |
|---|---|
ValueError
|
if a dimension of the scan has no position, a position names no dimension of the scan, or the variable is no timecourse. |
Get the band of the draws of a variable at one point of a scan.
The timecourse of every draw is the one of point_timecourse. Draws
with different time points (the steps of the integrator, a simulation
without steps or times) are interpolated linearly onto the time points
of a figure (sbmlsim.result.timecourse.plot_times: a few hundred, dense
where the draws stepped densely, with the times of the changes), NaN
outside of the times of a draw; a draw whose simulation failed (NaN) is
ignored.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
res
|
ScanResult
|
the result of the scan, positional only. |
required |
key
|
str
|
the variable, a timecourse, positional only. |
required |
across
|
str
|
the dimension of the draws. |
required |
quantiles
|
tuple[float, float]
|
the lower and the upper quantile. |
(0.05, 0.95)
|
**point
|
int
|
the position of the point along every other dimension. |
{}
|
Returns:
| Type | Description |
|---|---|
tuple[ndarray, ndarray, ndarray, ndarray]
|
The time points, the lower quantile, the median and the upper quantile. |
Raises:
| Type | Description |
|---|---|
ValueError
|
if the result has no dimension |