Skip to content

observables

The observables of a run, compiled against its models and evaluated.

compile_observables orders the observables of a run by what they read, checks every symbol against the model, derives the kind (a timecourse or a value per simulation) and the unit of every observable and gives an ObservableGraph: frozen, picklable and free of pint, so the chunks of a scan carry it into the workers. A run without observables has the graph of the selections of its model, each a timecourse of its own name (identity_graph).

ObservableGraph.evaluate computes the observables on the native solutions of the points of a chunk, stacked into arrays (n_points, n_rows) padded with NaN: a timecourse is such an array, a value per simulation an array (n_points, 1) while the graph is evaluated and (n_points,) in its result. The observables are evaluated before any interpolation onto a grid, so the reductions and the analysis of a PK observable are as exact as the output of the simulation. An observable which no kept observable needs is not evaluated, and the selections only it reads are not selected.

FormulaNode dataclass 

FormulaNode(id, formula, kind, factor)

A Formula observable compiled against the models of a run.

Attributes:

Name Type Description
id str

the id of the observable.
formula str

the formula.
kind ObservableKind

a timecourse or a value per simulation.
factor float

the factor from the derived unit of the formula into its declared unit, 1 without a conversion; evaluate applies it to the values of the formula, so every observable which reads it sees the unit of the observable.

CustomNode dataclass 

CustomNode(id, function, kind, symbols)

A Custom observable compiled against the models of a run.

Attributes:

Name Type Description
id str

the id of the observable.
function Callable[[ndarray, dict[str, Any]], Any]

the function of a module.
kind ObservableKind

a timecourse or a value per simulation.
symbols tuple[str, ...]

what it reads.

ObservableError 

ObservableError(row, message)

Bases: RuntimeError

An observable failed on the points of a chunk.

Attributes:

Name Type Description
row

the row of the point which failed in the arrays of the chunk, None for every point.
message

the error.

Create the error, the arguments pickle.

ObservableGraph dataclass 

ObservableGraph(
    nodes, selections, kinds, units, keep, outputs, doses=()
)

The observables of a run, see the module.

Attributes:

Name Type Description
nodes tuple[Node, ...]

the observables the kept ones need, in the order of what they read.
selections tuple[str, ...]

the selections of roadrunner the nodes read, without time.
kinds dict[str, ObservableKind]

the kind of every symbol and output: time and the selections are timecourses.
units dict[str, str]

the unit of every symbol and output, for a formula the declared unit if it has one (the values of evaluate are in it), else the derived one.
keep tuple[str, ...]

the outputs of the result, in order.
outputs tuple[str, ...]

every output: the ids of the formulas and customs and the parameters of the PK observables; the selections without observables.
doses tuple[str, ...]

the dose targets of the PK observables the run evaluates, whose units the models of a run share.

timecourses property 

timecourses

Get the kept timecourses.

scalars property 

scalars

Get the kept values per simulation.

evaluate 

evaluate(time, columns, plans)

Evaluate the observables on the points of a chunk, see the module.

Parameters:

Name Type Description Default
time ndarray

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

 required
columns Mapping[str, ndarray]

the selections, arrays of the shape of time.

 required
plans Sequence[Plan]

the plan of every point, with its values, which gives the doses of the PK observables and the resolution of the time which at takes as a jump (evaluate_reduced); without plans only a time which appears twice is a jump.

 required

Returns:

Type Description
dict[str, ndarray]

The kept outputs: a timecourse (n_points, n_rows), a value per
dict[str, ndarray]

simulation (n_points,).

Raises:

Type Description
ObservableError

if an observable fails for a point or for all.

identity_graph 

identity_graph(selections, units=None, keep=None)

Get the graph of a run without observables.

Every selection is a timecourse of its own name.

Parameters:

Name Type Description Default
selections Sequence[str]

the selections, without time.

 required
units Mapping[str, str] | None

the unit of the time and of every selection, "" by default.

 None
keep Sequence[str] | None

the selections of the result, every one by default.

 None

Returns:

Type Description
ObservableGraph

The graph.

Raises:

Type Description
ValueError

if keep names no selection.

compile_observables 

compile_observables(
    observables, model, *, keep=None, plans=()
)

Compile the observables of a run against its first model, see the module.

Parameters:

Name Type Description Default
observables Sequence[Observable] | None

the observables; None or none for the selections of the model, see identity_graph.

 required
model RoadrunnerSBMLModel

the loaded model, whose selections and units they read.

 required
keep Sequence[str] | None

the outputs of the result, every output by default; the id of a PK observable keeps all its parameters, a selection of the model is kept as a timecourse of its own name next to the observables.

 None
plans Sequence[Plan]

the plans of the run, each with the values of a point, whose dosing decides the parameters of the PK observables.

 ()

Returns:

Type Description
ObservableGraph

The graph.

Raises:

Type Description
TypeError

if the observables are no sequence of observables or keep is a string.
ValueError

for two observables of one id; an id which is a selection of the model; a symbol which is neither an observable nor a selection; a cycle; a time of at which is a timecourse; a unit which cannot be derived without unit= or not be converted into it; a time of at which has not the time unit of the model; a formula which mixes units of one dimension at different scales; a PK observable which does not fit the model (see compile_pk); or a keep which names no output.

A declared unit is the unit of the observable: the values are converted when the formula is evaluated and the observables which read it see them in that unit. A formula which adds units of one dimension at different scales is refused, but a comparison or a piecewise, which pint cannot evaluate, is not checked for mixed scales.