experiment.experiment¶

SimulationExperiments and helpers.

SimulationExperiment ¶

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

Generic simulation experiment.

Consists of models, datasets, simulations, tasks, results, processing, figures

SimulationExperiement.

:param sid: :param base_path: :param data_path: :param ureg: :param kwargs:

results `property` ¶

results

Access simulation results.

Results are mapped on tasks based on the task_ids. E.g. to get the results for the task with id 'task_glciv' use

    simexp.results["task_glciv"]
    self.results["task_glciv"]

initialize ¶

initialize()

Initialize SimulationExperiment.

Initialization must be separated from object construction due to the parallel execution of the problem later on. Certain objects cannot be serialized and must be initialized. :return:

Q ¶

Q(value, unit=None, model=None)

Create a quantity in a unit of pint and of the unit ids of the models.

The runner loads the models of an experiment before initialize, so the unit ids of a model are known in simulations() and later, e.g. self.Q(10, "mg_per_min"); a unit id is replaced by its expression, see UnitsInformation.quantity. Before the models are loaded Q takes the units of pint. sbmlsim.Q takes the units of pint only. A unit of pint, e.g. the units of a quantity, is taken as it is.

Parameters:

Name	Type	Description	Default
`value`	`Any`	the magnitude, a number or an array.	required
`unit`	`str \| PlainUnit \| None`	the unit, a string or a unit of pint, dimensionless without one.	`None`
`model`	`str \| None`	the id of the model whose unit ids the unit has. Without it a unit id must have the same expression in every model of the experiment which has it.	`None`

Returns:

Type	Description
`Quantity`	The quantity.

Raises:

Type	Description
`ValueError`	for a `model` which is no loaded model of the experiment, and without `model` for a unit id which models of the experiment define differently.
`UndefinedUnitError`	for a unit which is neither a unit of pint nor a unit id of the models.

models ¶

models()

Define model definitions.

The child classes fill out the information.

datasets ¶

datasets()

Define dataset definitions (experimental data).

The child classes fill out the information.

simulations ¶

simulations()

Define simulation definitions.

The child classes fill out the information.

observables ¶

observables()

Define the observables of the experiment, by their id.

A Formula, PK or Custom of sbmlsim.simulation.observables. A Data of a task reads an observable by its id and a parameter of a PK observable as <id>.<parameter>; a task computes the observables its data read, see _run_tasks. The child classes fill out the information.

tasks ¶

tasks()

Define task definitions.

The child classes fill out the information.

data ¶

data()

Define the data of the experiment, including functions of other data.

This determines the selection in the model.

The data of tasks, fit mappings and figures determines the selections of a simulation experiment; registering the data of a figure here is no longer needed. Registered data of a task which no figure or mapping reads still counts, e.g. via add_selections_data.

figures ¶

figures()

Figure definition.

The data the curves and areas of the figures read counts for the selections of the tasks, it needs no registration in data().

Most figures do not require access to concrete data, but only abstract data concepts.

figures_mpl ¶

figures_mpl()

Matplotlib figure definition.

Selections accessed in figures and analyses must be registered beforehand via the data of the experiment.

Most figures do not require access to concrete data, but only abstract data concepts.

A figure is styled with the settings of the experiment, FigureSettings.resolve(experiment=self.figure_settings), e.g. its fig_titlesize; the settings of a run (figure_settings= of run) do not reach this method.

fit_mappings ¶

fit_mappings()

Define fit mappings.

Mapping reference data on observables. Used for the optimization of parameters. The child classes fill out the information.

add_data ¶

add_data(d)

Add data to the tracked data.

add_selections_data ¶

add_selections_data(selections, task_ids=None)

Add selections to given tasks.

The data for the selections will be part of the results.

Selections are necessary to access data from simulations. Here these selections are added to the tasks. If no tasks are given, the selections are added to all tasks.

:param reset: drop and reset all selections.

run ¶

run(
    simulator,
    output_path=None,
    show_figures=False,
    save_results=False,
    figure_formats=None,
    reduced_selections=True,
    keep_results=True,
    on_error="raise",
    figure_settings=None,
)

Execute given experiment and store results.

A figure which failed in this run, and every figure of a failed experiment which this run did not write, leaves no file of an earlier run in the output path, so that no figure looks like one of this run.

Parameters:

Name	Type	Description	Default
`simulator`	`Simulator \| None`	the simulator of the tasks.	required
`output_path`	`Path \| None`	directory of the outputs (datasets, results, figures and the serialization), none are written without it.	`None`
`show_figures`	`bool`	show the matplotlib figures.	`False`
`save_results`	`bool`	write the results of the tasks into the output path.	`False`
`figure_formats`	`list[str] \| None`	formats of the figures, `STATIC_FORMAT` by default.	`None`
`reduced_selections`	`bool`	simulate only the selections the experiment uses.	`True`
`keep_results`	`bool`	keep the results of the tasks after the outputs are written. Without them an experiment holds only what its report needs, and a run of many experiments only the results of the one it runs; `results` then raises.	`True`
`on_error`	`Literal['raise', 'log']`	what an error does. `"raise"` (the default) raises it, so a user who runs one experiment sees it. `"log"` logs it with its traceback and records it in the result, which is what the `ExperimentRunner` uses: a failing figure is skipped and the others are written (`ExperimentResult.failed_figures`), an error of the experiment ends its run (`ExperimentResult.error`).	`'raise'`
`figure_settings`	`FigureSettings \| Mapping[str, Any] \| None`	the settings of the figures of the run, a `FigureSettings` or overrides of its defaults, which the `figure_settings` of the experiment and the settings of a figure override.	`None`

Returns:

Type	Description
`ExperimentResult`	The result of the experiment, which the report is created from.

Raises:

Type	Description
`ValueError`	if a key of `figure_settings` is no setting, also with `on_error="log"`.

scan_dimension ¶

scan_dimension(task, dim)

Get a dimension of the scan of a task by its id, None if it has none of it.

model_units ¶

model_units(task)

Get the units of the symbols of the model of a task, {} for a model which is not loaded.

evaluate_fit_mappings ¶

evaluate_fit_mappings()

Evaluate fit mappings.

to_json ¶

to_json(path=None, indent=2)

Convert experiment to JSON for exchange.

The experiment is encoded before the file is written, so a value which cannot be encoded leaves no truncated file.

:param path: path for file, if None JSON str is returned :return: :raises TypeError: for a value which ObjectJSONEncoder cannot encode

to_dict ¶

to_dict()

Convert to dictionary.

This is the basis for the JSON serialization.

save_datasets ¶

save_datasets(results_path)

Save datasets.

save_results ¶

save_results(results_path)

Save the result of every task as netCDF, see ScanResult.to_netcdf.

Parameters:

Name	Type	Description	Default
`results_path`	`Path`	directory of the files, `<sid>_<task>.nc`.	required

create_mpl_figures ¶

create_mpl_figures(
    on_error="raise", failed=None, figure_settings=None
)

Create matplotlib figures.

Parameters:

Name	Type	Description	Default
`on_error`	`Literal['raise', 'log']`	`"raise"` raises the error of a figure, `"log"` logs it, skips the figure and goes on with the next.	`'raise'`
`failed`	`dict[str, str] \| None`	collects the failed figures as `{key: error}`.	`None`
`figure_settings`	`FigureSettings \| Mapping[str, Any] \| None`	the settings of the run, see `run`.	`None`

Returns:

Type	Description
`dict[str, FigureMPL \| Figure]`	The figures by their key, without the failed ones.

show_mpl_figures ¶

show_mpl_figures(mpl_figures)

Show matplotlib figures.

The figures of the serializer are created without pyplot, so that rendering does not fill its global registry; a figure it does not manage cannot show itself. Showing is the one place which needs the state machine, so a figure gets a manager here and only here.

Parameters:

Name	Type	Description	Default
`mpl_figures`	`dict[str, FigureMPL]`	the figures to show.	required

save_mpl_figures ¶

save_mpl_figures(
    results_path,
    mpl_figures,
    figure_formats=None,
    on_error="raise",
    failed=None,
)

Save matplotlib figures.

Parameters:

Name	Type	Description	Default
`results_path`	`Path`	directory of the files.	required
`mpl_figures`	`dict[str, FigureMPL]`	the figures to save.	required
`figure_formats`	`list[str] \| None`	formats of the files, `svg` by default.	`None`
`on_error`	`Literal['raise', 'log']`	`"raise"` raises the error of a figure, `"log"` logs it and goes on with the next figure.	`'raise'`
`failed`	`dict[str, str] \| None`	collects the failed figures as `{key: error}`.	`None`

save_interactive_figures ¶

save_interactive_figures(
    results_path,
    on_error="raise",
    failed=None,
    figure_settings=None,
)

Write the figures as interactive pages.

The pages are drawn by plotly, see sbmlsim.plot.serialization_plotly: matplotlib draws the static images a publication needs and plotly the pages a reader zooms and hovers over. Both read the same Figure, so the two cannot disagree about what they show.

plotly is not a dependency of sbmlsim; a run which asks for the interactive figures without it says so and writes none.

Parameters:

Name	Type	Description	Default
`results_path`	`Path`	directory of the pages.	required
`on_error`	`Literal['raise', 'log']`	`"raise"` raises the error of a figure, `"log"` logs it and goes on with the next figure.	`'raise'`
`failed`	`dict[str, str] \| None`	collects the failed figures as `{key: error}`.	`None`
`figure_settings`	`FigureSettings \| Mapping[str, Any] \| None`	the settings of the run, see `run`.	`None`

Returns:

Type	Description
`dict[str, Path]`	The path of the page of every figure, empty without plotly.

close_mpl_figures `classmethod` ¶

close_mpl_figures(mpl_figures)

Close matplotlib figures.

A figure of the serializer is not in the registry of pyplot and is released when nothing refers to it any more, for which this is a no-op. A figure of figures_mpl() may well come from pyplot, and that one is closed here.

Parameters:

Name	Type	Description	Default
`mpl_figures`	`dict[str, FigureMPL]`	the figures to close.	required

ExperimentRunError ¶

ExperimentRunError(results)

Bases: Exception

One or more experiments or figures of a run failed.

Raised by ExperimentRunner.run_experiments(raise_on_failure=True) after every experiment ran.

Attributes:

Name	Type	Description
`results`		the results of all experiments of the run, empty in a copy which was pickled.
`failures`		the failed experiments and figures, one line each.

Create the error from the results of a run.

ExperimentResult `dataclass` ¶

ExperimentResult(
    experiment,
    output_path,
    error=None,
    failed_figures=dict(),
    figures=dict(),
    datasets=list(),
)

Result of a simulation experiment.

failed `property` ¶

failed

Check whether the experiment or one of its figures failed.

to_dict ¶

to_dict()

Conversion to dictionary.

Used in serialization and required for reports.

experiment.experiment¶

SimulationExperiment ¶

results property ¶

initialize ¶

Q ¶

models ¶

datasets ¶

simulations ¶

observables ¶

tasks ¶

data ¶

figures ¶

figures_mpl ¶

fit_mappings ¶

add_data ¶

add_selections_data ¶

run ¶

scan_dimension ¶

model_units ¶

evaluate_fit_mappings ¶

to_json ¶

to_dict ¶

save_datasets ¶

save_results ¶

create_mpl_figures ¶

show_mpl_figures ¶

save_mpl_figures ¶

save_interactive_figures ¶

close_mpl_figures classmethod ¶

ExperimentRunError ¶

ExperimentResult dataclass ¶

failed property ¶

to_dict ¶

results `property` ¶

close_mpl_figures `classmethod` ¶

ExperimentResult `dataclass` ¶

failed `property` ¶