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), the build of the sex of the study (sex, the male build by default, the female build of a study of women; simulation_sexes for a study with a group of each sex), creates a task per simulation on the build of its sex (tasks), adds the selections to every task (data), loads the digitized data of the study (load_dataframe, with the unit of the geometric means, add_gmean_unit) 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.

A run over the draws of the fitted parameters (run_simulation <package> --uncertainty) gives every experiment the setting uncertainty, a pkpdsim.uncertainty.UncertaintyRun: initialize runs every simulation over the draws and turns the curves of the simulations into bands (pkpdsim.uncertainty.apply_uncertainty), so an experiment needs no code of its own for it. A figure which an experiment draws itself (figures_mpl) reads uncertainty and draws the bands of the draws, e.g. with pkpdsim.scan.point_band.

A dose after the first one adds to its dose state (add_doses): the rest of the earlier doses which is not yet dissolved, absorbed or infused stays, which a change of the dose state to the dose would discard (pkdb_models#105).

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`	`Sequence[str]`	the molecular weights of the substances, for the conversion of the data (a `NamedTuple` of the model). The base does not declare it: its type is the `NamedTuple` of the model, which the base of the model declares, and the narrowing of a declared class attribute is an invalid override of a mutable attribute (ty).
`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`.
`sex`	`Sex`	the sex of the subjects of the study, the build of the model object its simulations run (`PKPDModel.model_paths`): the male build by default, the female build for a study of women. A group whose majority is women is simulated on the female build, a mixed group without a majority of women on the male one (the study module states it). A model without a female build refuses a female experiment.
`simulation_sexes`	`Mapping[str, Sex]`	the sex of single simulations which differs from `sex`, by the key of the simulation, e.g. the group of women of a study of a group of men and a group of women. The models of an experiment are loaded before its simulations are created, so the sexes are declared and not computed by `simulations`.

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.

uncertainty `property` ¶

uncertainty

The draws of the fitted parameters of a run over them, None otherwise.

Raises:

Type	Description
`TypeError`	if the setting `uncertainty` is no `UncertaintyRun`.

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.

With the setting uncertainty every simulation runs over the draws of the fitted parameters and the curves of the simulations become bands, see pkpdsim.uncertainty.apply_uncertainty.

Raises:

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

across ¶

across()

Get the dimension of the draws of the fitted parameters, None without.

The dimension over which a run over the draws (uncertainty) varies the fitted parameters, which a figure or an analysis of a scan of the experiment leaves out of its own dimensions or makes a band of, e.g. pkpdsim.scan.point_band(result, ..., across=self.across()).

add_function ¶

add_function(plot, task_id, y, label, color, linestyle='-')

Add a function of the results of a task over the time to a plot.

A curve of the line width of the curves of the selections (add_data, 2.0); in a run over the draws of the fitted parameters (uncertainty) the band of the draws instead, with the quantiles of the run: the function is no selection of a task, which the run makes a band of itself.

Parameters:

Name	Type	Description	Default
`plot`	`Plot`	the plot.	required
`task_id`	`str`	the task whose results the function reads.	required
`y`	`Data`	the function, a `Data` of a function of the selections of the task.	required
`label`	`str \| None`	the label of the curve or the band, `None` for none.	required
`color`	`str`	the color.	required
`linestyle`	`str \| None`	the line style of the curve, `None` for the default of sbmlsim (the curve has no line style of its own).	`'-'`

data_unit_names ¶

data_unit_names()

Get the names of the units of the data, defining the units of data_units once.

The loaders rename the units of the data with these names; a table which a model reads itself, e.g. the data of a figure of a scan, is renamed with them by rename_units. initialize calls it first; a call without initialize defines the units on its first call.

Returns:

Type	Description
`Mapping[str, str]`	The name of a unit in the data -> the name of its definition,
`Mapping[str, str]`	read-only.

Raises:

Type	Description
`ValueError`	for a definition which `define_unit` refuses.

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.

sex_of `classmethod` ¶

sex_of(simulation)

Get the sex of the subjects of a simulation: simulation_sexes, else sex.

A class method, since the sexes are declared: the class methods of an experiment (the renal function of a group, pkpdsim.pbpk) resolve the sex of a simulation by its key as well.

Parameters:

Name	Type	Description	Default
`simulation`	`str`	the key of the simulation.	required

Returns:

Type	Description
`Sex`	The sex, whose build the simulation runs.

Raises:

Type	Description
`ValueError`	for a sex which is no `Sex`.

model_id ¶

model_id(sex)

Get the key of the build of a sex among the models of the experiment.

The build of sex is model, the model of an experiment without builds per sex; the build of another sex is model_<sex>, e.g. model_female in a study of men with a group of women.

Parameters:

Name	Type	Description	Default
`sex`	`Sex`	the sex.	required

Returns:

Type	Description
`str`	The key of the model.

models ¶

models()

Get the builds of the model object which the experiment simulates.

The build of sex as model and the build of every other sex of simulation_sexes as model_<sex> (model_id), without changes; a model without builds per sex has the one model model. Only the builds which the experiment simulates are loaded.

Raises:

Type	Description
`ValueError`	if the model object has no build of a sex of the experiment, naming the experiment.

tasks ¶

tasks()

Get a task for every simulation, on the build of the sex of the simulation.

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

Raises:

Type	Description
`ValueError`	if `simulation_sexes` names a simulation which the experiment does not have.

add_doses ¶

add_doses(times, doses, model='model')

Get doses at times which add to their dose states.

A dose is given by its dose state, e.g. PODOSE_hctz, from which a rate rule dissolves, absorbs or infuses it. A change of the dose state to the dose (Change(times, {"PODOSE_hctz": Q(10, "mg")})) discards what is left of the earlier doses; the change of this method adds the dose ("PODOSE_hctz + 10.0", a formula in the unit of the dose state in the model), so repeated doses keep the rest of the earlier ones. The first dose is usually a change before the initialization (preinit_changes), which may set the state. The models are loaded before simulations(), where the doses are created.

Parameters:

Name	Type	Description	Default
`times`	`float \| Quantity \| Sequence[float \| Quantity]`	the times of the doses, in the time unit of the simulation or quantities.	required
`doses`	`Mapping[str, Quantity]`	the dose state and the dose, e.g. `{"PODOSE_hctz": Q(10, "mg")}`.	required
`model`	`str`	the key of the model whose units the dose states have.	`'model'`

Returns:

Type	Description
`Change`	The change of the dose states at the times.

Raises:

Type	Description
`ValueError`	if the model is not loaded.

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.

The geometric means get their unit (add_gmean_unit), the units of the data are renamed (data_units, rename_units).

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.

The geometric means get their unit (add_gmean_unit), the units of the data are renamed (data_units, rename_units). The rows without a substance (a bile flow, a blood pressure) are in no frame, they are in the table of load_dataframe.

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.

add_gmean_unit ¶

add_gmean_unit(df)

Give the geometric means of a table of the data their unit, gmean_unit.

The unit of a row of the tables of PK-DB is the unit of all its statistics, but sbmlsim (DataSet.from_df) reads it as the unit of mean, value and median only, so that a curve of the geometric means (yid="gmean") has no unit. The column gmean_unit is the unit of the rows with a geometric mean, which sbmlsim reads as the unit of gmean (and converts the rows of other units into the first). The geometric SD gsd and the gcv are ratios without a unit. A table without geometric means or with a gmean_unit stays as it is.

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	the table, changed in place.	required

Returns:

Type	Description
`DataFrame`	The table.

experiment¶

PKPDSimulationExperiment ¶

uncertainty property ¶

initialize ¶

across ¶

add_function ¶

data_unit_names ¶

to_sid ¶

sex_of classmethod ¶

model_id ¶

models ¶

tasks ¶

add_doses ¶

default_changes ¶

data ¶

load_dataframe ¶

load_dataframes_by_substance ¶

figures_by_sid staticmethod ¶

to_sid ¶

define_unit ¶

rename_units ¶

add_gmean_unit ¶

uncertainty `property` ¶

sex_of `classmethod` ¶

figures_by_sid `staticmethod` ¶