Skip to content

result.timecourse

Result of a single timecourse simulation.

The simulator answers every Simulation with a TimecourseResult: the array of the selections which roadrunner returns, with a row per time point and a column per selection, and the names of the columns. sbmlsim.simulator.Simulator.run places the results of the simulations of a scan into a ScanResult.

It is deliberately not a data frame. A fit simulates its groups on every evaluation of the residuals and a scan simulates every combination of its dimensions, so building a frame per simulation, concatenating the frames and looking their columns up took a third of the time of the residuals and half of the time of a scan; the columns of a TimecourseResult are views into the array roadrunner returned.

TimecourseResult dataclass 

TimecourseResult(columns, values)

Values of the selections of a timecourse simulation.

Attributes:

Name Type Description
columns tuple[str, ...]

names of the columns, i.e., the timecourse selections.
values ndarray

values with a row per time point and a column per selection.

time property 

time

Get the time points, i.e., the column time.

concatenate classmethod 

concatenate(results)

Concatenate the results of consecutive timecourses.

Parameters:

Name Type Description Default
results Sequence[TimecourseResult]

results with the same columns, in the order of their time.

 required

Returns:

Type Description
TimecourseResult

The rows of all results.

Raises:

Type Description
ValueError

if there are no results or their columns differ.

GridWeights

Bases: NamedTuple

The linear interpolation from a common time axis onto a grid.

grid_weights 

grid_weights(
    time, grid, tolerance=0.0, changes=None, left=None
)

Get the indices and weights which interpolate time onto grid once.

The output of a simulation has two time points at the time of a change after the start, the states before and after the change, and two at the time of an event of the model, the states before and after the event (sbmlsim.model.event_rows): a jump. Two time points of an event which are a little apart, as the exact output of sbmlsim.simulator.executor has them, are a jump as well. A chain of jumps starts at a jump and has the time points after it at most tolerance apart, e.g. a change and an event closer than the resolution of the time and the first steps of CVODE after the last jump. A time of the grid sees:

  • before a chain, the value interpolated toward the state before it, also within tolerance before it if its first jump is a change, and whether or not a step of the integrator is that close to it;
  • at a change, at an event and inside a chain, the state after the last jump of the chain, not a step of the integrator after it;
  • at most tolerance before a chain whose first jump is an event, the state after the chain: CVODE locates an event a little after its time, at the end of the interval in which it finds the root of the trigger.

A time of the grid in left sees the state before the jump at it instead, the state before the chain, e.g. a data point of a fit which takes the state before a change; by default the first of two equal times of the grid, so a grid of the time points of a timecourse gives every row of it. The fit interpolates its data by the same rule.

Parameters:

Name Type Description Default
time ndarray

the time points, sorted; the ones which are not finite are no time points.

 required
grid ndarray

the times of the result.

 required
tolerance float

the resolution of the time of the simulation, see sbmlsim.simulator.plan.time_tolerance; 0 takes only a time point which appears twice as a jump.

 0.0
changes ndarray | None

the times of the changes after the start in the time of the time points, None for none.

 None
left ndarray | None

whether a time of the grid takes the state before a jump at it, a mask of the grid; None for the first of two equal times.

 None

Returns:

Type Description
GridWeights

The indices and weights.

apply_weights 

apply_weights(w, values)

Interpolate the last axis of values with the weights, NaN outside.

Values without a time point, e.g. of a ragged scan whose points all failed, are NaN at every time of the grid.

interpolate 

interpolate(
    time, values, grid, tolerance=0.0, changes=None
)

Interpolate a timecourse linearly onto a grid of times.

The time points of a simulation increase, a time of a change after the start appears twice, with the states before and after the change, and so does an event of the model. A time of the grid before a change is interpolated toward the state before it and the time of a change sees the state after it, the first of two equal times of the grid the state before it, see grid_weights. The padding (NaN) and the steady state after the end (inf) are no time points of the interpolation.

Parameters:

Name Type Description Default
time ndarray

the time points.

 required
values ndarray

the values, a row per time point, one or two dimensional.

 required
grid ndarray

the times of the result.

 required
tolerance float

time points at most this apart are a jump, see grid_weights.

 0.0
changes ndarray | None

the times of the changes after the start, see grid_weights.

 None

Returns:

Type Description
ndarray

The values at the times of the grid, a row per time; NaN outside of
ndarray

the finite time points and for a timecourse without any.

without_states_before 

without_states_before(time, values, changes)

Leave out the state before every change after the start.

The output of a simulation has the state before and the state after a change at its time; a timecourse of samples, e.g. of pkpdutils, has a time once, the state after the change. The first of the two rows at the time of a change is left out, the two rows of an event of the model stay.

Parameters:

Name Type Description Default
time ndarray

the time points (n, n_rows), padded with NaN.

 required
values ndarray

the timecourses, of the shape of time.

 required
changes Sequence[ndarray]

the times of the changes after the start of every timecourse, in the time of the time points.

 required

Returns:

Type Description
ndarray

The time points and the timecourses without the states before the
ndarray

changes, padded with NaN, which is the padding of every time point
tuple[ndarray, ndarray]

which is not finite as well.

plot_times 

plot_times(times, n=PLOT_POINTS, keep=())

Get the time points of a figure of simulations with their own time points.

The steps of the integrator are dense where the state changes, e.g. after a dose, and sparse where it does not; the union of the steps of many simulations has far more time points than a curve needs. n time points from the first to the last time are enough: three quarters at the quantiles of all time points together, so that they are dense where the simulations stepped densely, and a quarter equidistant, so that no phase without a change is left out. The times keep, e.g. of the changes, are added. Fewer distinct time points than n are returned as they are.

Parameters:

Name Type Description Default
times ndarray

the time points of all simulations, any shape, padded with NaN.

 required
n int

the number of time points.

 PLOT_POINTS
keep Sequence[float]

times which are added, within the first and the last time.

 ()

Returns:

Type Description
ndarray

The time points, sorted and distinct.

Raises:

Type Description
ValueError

if n is smaller than 2.