Skip to content

observables

Observables: what a scan computes from every simulation.

An observable reads the selections of roadrunner (S amount, [S] concentration, time, parameters, compartments, reactions) and other observables by id:

  • Formula(id, formula, unit=None): the math of PEtab with the reductions over the time of a simulation, max, min, mean and at, see sbmlsim.simulator.formula; a timecourse, or a value per simulation when it reads only values per simulation, e.g. max([glc]);
  • PK(id, selection, *, dose=None, route=None, options=None, parameters=None): the non-compartmental analysis of pkpdutils of a timecourse, a value per simulation <id>.<parameter> for every parameter, e.g. hctz.cmax;
  • Custom(id, function, unit, *, symbols, kind=SCALAR): a function of a module, called with the time points and the values of its symbols of every simulation.

The definitions are frozen and pickle. Simulator.run(model, scan, observables) compiles them against the models of the run, see sbmlsim.simulator.observables, and evaluates them in the workers on the native solution of every simulation.

ObservableKind

Bases: StrEnum

What an observable is per simulation.

Observable dataclass 

Observable(id)

An observable, the base of Formula, PK and Custom.

Attributes:

Name Type Description
id str

the id, which the result and the other observables use.

reads property 

reads

Get the selections and the observables it reads.

to_dict 

to_dict()

Get the definition as JSON types, the provenance of a result.

Formula dataclass 

Formula(id, formula, unit=None)

Bases: Observable

A formula of the math of PEtab with reductions over time, see the module.

Attributes:

Name Type Description
formula str

the formula over selections and the ids of other observables.
unit str | None

the unit of the values: the unit the formula has is converted into it; where pint cannot derive one, e.g. for piecewise or a comparison, it is the unit of the formula, which then needs it.

reads property 

reads

Get the selections and the observables the formula reads.

to_dict 

to_dict()

Get the definition as JSON types.

PK dataclass 

PK(
    id,
    selection,
    *,
    dose=None,
    route=None,
    options=None,
    parameters=None,
)

Bases: Observable

The non-compartmental analysis of a timecourse with pkpdutils.

Every parameter pkpdutils derives is a value per simulation <id>.<parameter>, e.g. hctz.cmax, hctz.auc_inf_obs, hctz.thalf, with the unit pkpdutils gives it, and <id>.flags the flags of the analysis (pkpdutils.NCAFlag).

Attributes:

Name Type Description
selection str

the timecourse, a selection of the model or the id of a timecourse observable, e.g. a concentration.
dose str | Quantity | None

the target of the model which the simulations dose: its values in the plan of every point are the doses and the times of these values their times, so the dose of a dimension and the changes of a multiple dosing are found; a quantity is a fixed dose at the start; None analyses without a dose and leaves out the parameters which need one.
route str | None

the route of the dose, a pkpdutils.Route or its name, e.g. "oral" or "iv_bolus"; a dose needs it.
options NCAOptions | None

the options of the analysis, a pkpdutils.NCAOptions.
parameters Sequence[str] | None

the parameters to keep, every parameter by default.

reads property 

reads

Get the timecourse the analysis reads.

to_dict 

to_dict()

Get the definition as JSON types.

Custom dataclass 

Custom(id, function, unit, *, symbols, kind=SCALAR)

Bases: Observable

A function of a module, called once per simulation.

function(time, values) gets the time points of a simulation, without padding, and values, its symbols to their values: an array of the length of time for a timecourse and a float for a value per simulation. It returns a float for a value per simulation and an array of the length of time for a timecourse.

Attributes:

Name Type Description
function Callable[[ndarray, dict[str, Any]], Any]

the function, defined at the top level of a module so that it pickles for the workers of a scan.
unit str

the unit of its values.
symbols Sequence[str]

the selections and observables it reads.
kind ObservableKind

a value per simulation (SCALAR) or a timecourse.

reads property 

reads

Get the symbols the function reads.

to_dict 

to_dict()

Get the definition as JSON types; the function as module:name.