experiment¶

The base class of the simulation experiments of a model.

The base of the experiments of a model derives from PKPDSimulationExperiment and binds it to the model object; the experiments of the model derive from that base:

# not executed
from sbmlsim import Q


class HctzSimulationExperiment(PKPDSimulationExperiment):
    pkpd_model = MODEL
    selections = ("time", "[Cve_hctz]", "Aurine_hctz")
    Mr: ClassVar[MolecularWeights] = MolecularWeights(hctz=Q(297.74, "g/mole"))

The base simulates the model of the model object (models), creates a task per simulation (tasks), adds the selections to every task (data), loads the digitized data of the study (load_dataframe) and has the classes of impaired organ function (pkpdsim.impairment) and the labels of the pharmacokinetic parameters (pkpdsim.pk) as defaults. A model overrides what it does differently.

The keys of an experiment are SIds (sbmlsim checks them): to_sid gives the SId of a text, e.g. of a label of the data, and the method to_sid of the base checks that no two texts of an experiment give the same SId. A unit which the data use and sbmlsim does not define (an international unit is specific to a substance) is defined under a name of the model and the substance, data_units.

PKPDSimulationExperiment ¶

PKPDSimulationExperiment(
    sid=None,
    base_path=None,
    data_path=None,
    ureg=None,
    **kwargs,
)

Bases: SimulationExperiment

The base of the simulation experiments of a model.

Attributes:

Name	Type	Description
`pkpd_model`	`PKPDModel`	the model object of the model, set once in the base of its experiments.
`selections`	`Sequence[str]`	the selections of every task, see `data`.
`Mr`	`tuple[Quantity, ...]`	the molecular weights of the substances, for the conversion of the data (a `NamedTuple` of the model).
`labels`	`Mapping[str, str]`	the labels of the observables by id.
`units`	`Mapping[str, str]`	the units of the observables by id.
`renal_map`	`Mapping[str, float]`	the factor of the renal function by class.
`renal_colors`	`Mapping[str, str]`	the color of a class of the renal function.
`cirrhosis_map`	`Mapping[str, float]`	the degree of cirrhosis by class.
`cirrhosis_colors`	`Mapping[str, str]`	the color of a class of the cirrhosis.
`cardiac_map`	`Mapping[str, float]`	the factor of the cardiac output by class.
`cardiac_colors`	`Mapping[str, str]`	the color of a class of the cardiac function.
`pk_labels`	`Mapping[str, str]`	the label of a pharmacokinetic parameter.
`pk_units`	`Mapping[str, str]`	the unit of a pharmacokinetic parameter.
`data_units`	`Mapping[str, str]`	the units of the data which the experiment reads under a name of its own, see `define_unit`.

Create the experiment, see SimulationExperiment.

The units of the data (data_units) are defined by initialize, so a definition which is refused fails the initialization of this experiment, which a run reports, and not the creation, which stops a run of sbmlsim before any experiment ran.

Raises:

Type	Description
`TypeError`	if no base of the experiments sets `pkpd_model`. This is an error of the definition of the classes, which every experiment of the base has, so it stops a run.

initialize ¶

initialize()

Define the units of the data and initialize the experiment.

The units of data_units are defined before the data are read, see SimulationExperiment.initialize.

Raises:

Type	Description
`ValueError`	for a definition of `data_units` which `define_unit` refuses; the runner reports the experiment as failed.

to_sid ¶

to_sid(text)

Get the SId of a text as a key of the experiment, see to_sid.

The keys of an experiment are unique across its datasets, simulations, tasks, figures and fit mappings, so two texts which give one SId in an experiment are an error: one entry would replace the other.

Parameters:

Name	Type	Description	Default
`text`	`str`	the text, e.g. a label of the data.	required

Returns:

Type	Description
`str`	The SId.

Raises:

Type	Description
`ValueError`	if another text of the experiment gave the same SId.

models ¶

models()

Get the SBML model of the model object, without changes.

tasks ¶

tasks()

Get a task of the model for every simulation.

initialize creates the simulations before the tasks, so they are not created a second time.

default_changes ¶

default_changes()

Get the changes of every simulation of the experiments, none.

The parameters are part of the model and are not changed in the simulations: a parameter which is fitted must not be set by a simulation, it would override the value of the fit.

data ¶

data()

Add the selections to every task; returns no further data.

load_dataframe ¶

load_dataframe(fig_id, study=None, *, na_values=None)

Load the digitized data of a figure or table of a study.

Parameters:

Name	Type	Description	Default
`fig_id`	`str`	the id of the figure or table in the study, e.g. `Fig1`.	required
`study`	`str \| None`	the study, the id of the experiment by default.	`None`
`na_values`	`Sequence[str] \| Mapping[str, Sequence[str]] \| None`	additional strings of missing values, for every column or by column, e.g. `{"time": ["NR"]}`, see `pandas.read_csv`.	`None`

Raises:

Type	Description
`ValueError`	if the experiment has no `data_path` or a definition of `data_units` is refused.

load_dataframes_by_substance ¶

load_dataframes_by_substance(fig_id, study=None)

Load the digitized data of a figure or table by substance.

Parameters:

Name	Type	Description	Default
`fig_id`	`str`	the id of the figure or table in the study, e.g. `Fig1`.	required
`study`	`str \| None`	the study, the id of the experiment by default.	`None`

Raises:

Type	Description
`ValueError`	if the experiment has no `data_path` or a definition of `data_units` is refused.

figures_by_sid `staticmethod` ¶

figures_by_sid(*figures)

Get figures by their id, which every figure of the experiments has.

Raises:

Type	Description
`ValueError`	for a figure without an id.

to_sid ¶

to_sid(text)

Get the SId of a text, e.g. of a label of the data, as a key of an experiment.

A decimal point between two digits becomes p (0.5mg is 0p5mg) and every other character which an SId does not allow becomes _ (po 2.5 mg is po_2p5_mg, µg/ml is _g_ml). One character becomes one character, and an SId stays as it is. The function maps characters, so a part of a key gives the same part of the SId of the key (f"task_po_{to_sid(dose)}"). Whether a whole key is a valid SId, i.e. not empty and not starting with a digit, is not checked here (the text of a part of a key may start with a digit): sbmlsim checks every key when the experiment initializes and names all invalid ones.

Parameters:

Name	Type	Description	Default
`text`	`str`	the text.	required

Returns:

Type	Description
`str`	The SId.

define_unit ¶

define_unit(ureg, definition)

Define a unit in a registry once, e.g. the international unit of a substance.

The registry of sbmlsim, one per process, ignores a redefinition, so a second model which defined a name with another value would silently get the first one. A name which is defined already must therefore have the same value (compared in base units); a name of the model and the substance, e.g. IU_ramipril_renin, keeps the models apart.

Parameters:

Name	Type	Description	Default
`ureg`	`UnitRegistry`	the unit registry, the one of the experiments.	required
`definition`	`str`	`"<name> = <expression>"` in the syntax of pint, e.g. `"IU_ramipril_renin = 0.6 * microgram"` or `"IU_apixaban_antixa = count"`.	required

Returns:

Type	Description
`str`	The name of the unit.

Raises:

Type	Description
`ValueError`	if the definition is not `<name> = <expression>` with an identifier as the name, pint cannot evaluate the expression (e.g. an unknown unit in it, pint's `UndefinedUnitError`) or the name is defined with another value.

rename_units ¶

rename_units(df, names)

Rename units in the unit columns of a table of the data.

A name is replaced where it is a unit of a unit expression, alone or after a metric prefix: with {"IU": "IU_x"}, IU/ml is IU_x/ml and µIU/ml is µIU_x/ml; IU_per_ml and 2IU stay. The unit columns are unit and every column whose name ends with _unit; a missing value stays missing.

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	the table, changed in place.	required
`names`	`Mapping[str, str]`	the name in the data -> the new name.	required

Returns:

Type	Description
`DataFrame`	The table.

experiment¶

PKPDSimulationExperiment ¶

initialize ¶

to_sid ¶

models ¶

tasks ¶

default_changes ¶

data ¶

load_dataframe ¶

load_dataframes_by_substance ¶

figures_by_sid staticmethod ¶

to_sid ¶

define_unit ¶

rename_units ¶

figures_by_sid `staticmethod` ¶