model¶

The description of a PBPK/PD model, which the commands of pkpdsim work with.

A model package defines one PKPDModel in its __init__.py, next to its path constants:

# not executed
MODEL = PKPDModel(
    name="hctz",
    package=__name__,
    title="HCTZ PBPK/PD model",
    path=HCTZ_PATH,
    model_path=MODEL_PATH,
    data_paths=tuple(DATA_PATHS),
    factory=".models.factory:create_hctz_models",
    experiments=".simulations:EXPERIMENTS",
    fit_definitions=".fitting.fitting:FIT_DEFINITIONS",
)

The factory, the registry of the experiments and the fit definitions are references "module:attribute", resolved when they are used: the experiments import the __init__.py of their model, so the model object cannot import them, and importing a model package does not import its experiments. A module which starts with a dot is relative to package.

FigureSettings is the sbmlsim.plot.FigureSettings of sbmlsim with the formats of the figures and the resolution of the static images; the module therefore imports sbmlsim's plotting.

SimulatorSettings `dataclass` ¶

SimulatorSettings(
    *,
    absolute_tolerance=1e-10,
    relative_tolerance=1e-10,
    n_workers=1,
)

The integrator settings of the simulation experiments of a model.

All fields are keyword-only.

Attributes:

Name	Type	Description
`absolute_tolerance`	`float \| AbsoluteTolerance`	the absolute tolerance, one value for every state or an `AbsoluteTolerance` of sbmlsim with tolerances per kind and state.
`relative_tolerance`	`float`	the relative tolerance.
`n_workers`	`int \| None`	the processes of a scan: `1` runs serially, a number runs a pool of that many processes, `None` lets sbmlsim choose (a pool of every CPU for a scan of `sbmlsim.parallel.POOL_THRESHOLD` points or more, serially otherwise). A pool needs the guard `if __name__ == "__main__":` in a script which runs the model.

FigureSettings `dataclass` ¶

FigureSettings(*, formats=('svg', 'png'), savefig_dpi=None)

Bases: FigureSettings

The figures of the simulation experiments of a model.

The settings of sbmlsim's figures (sbmlsim.plot.FigureSettings: the resolution, the sizes of the panels, the fonts and the legends, with the defaults of sbmlsim) and what a model adds: the formats of the figures and the resolution of the static images. A run hands the settings of sbmlsim to every figure (sbmlsim_settings); an experiment (figure_settings) and a figure (Figure(settings=...)) override them. savefig_dpi is the savefig.dpi of matplotlib while the figures of a run are drawn (rc_params).

The fields of sbmlsim can be given by position, as in sbmlsim; formats and savefig_dpi only by keyword.

Attributes:

Name	Type	Description
`formats`	`Sequence[str]`	the formats of the figures, static images drawn by matplotlib (`svg`, `png`) and interactive pages drawn by plotly (`html`).
`savefig_dpi`	`float \| None`	the resolution of the static images, `None` keeps the one of matplotlib. An interactive page has 72 pixels per inch.

sbmlsim_settings ¶

sbmlsim_settings()

Get the settings of sbmlsim, without the formats and the resolution.

A plain sbmlsim.plot.FigureSettings, which sbmlsim compares with its defaults (a run with the defaults sets nothing).

rc_params ¶

rc_params()

Get the settings of matplotlib for a run, the resolution of the images.

ExtraAction `dataclass` ¶

ExtraAction(*, name, help, function, in_all=False)

An action a model adds to its run command, e.g. analyses of its own.

All fields are keyword-only.

Attributes:

Name	Type	Description
`name`	`str`	the value of `--action`.
`help`	`str`	what the action does, shown by `--help`.
`function`	`str`	reference to the function which runs the action; it is called with the model, the parsed arguments and the directory of the results. The arguments have the settings of the simulator of the run as `simulator` (`SimulatorSettings`, those of the model with the processes of `--workers`), which an action that simulates passes on, e.g. `model.run_experiments(..., simulator=options.simulator)` or `pkpdsim.run.create_simulator(options.simulator)`.
`in_all`	`bool`	run the action with `--action all`, after the simulations.

CheckSettings `dataclass` ¶

CheckSettings(
    *,
    not_registered=dict(),
    not_importable=dict(),
    one_at_a_time=None,
)

The known exceptions of the tests of a model, each with its reason.

All fields are keyword-only. The mappings are copied, so the settings do not change with the dictionaries they were created from, and the settings are hashable.

Attributes:

Name	Type	Description
`not_registered`	`Mapping[str, str]`	experiment classes which are defined but not in the group `all` of the registry on purpose, by class name.
`not_importable`	`Mapping[str, str]`	modules below the package which do not import in the test environment (an optional dependency), by their name relative to the package, e.g. `experiments.zonation.plot_pyvista`.
`one_at_a_time`	`str \| None`	why the tests run the registered experiments one at a time (the memory a run of all of them needs), `None` to run them together.

PKPDModel `dataclass` ¶

PKPDModel(
    *,
    name,
    package,
    title,
    path,
    model_path,
    factory,
    experiments=None,
    fit_definitions=None,
    data_paths=(),
    results_path=None,
    factory_path=None,
    archive_path=None,
    simulator=SimulatorSettings(),
    figures=FigureSettings(),
    reduced_selections=True,
    save_results=False,
    fit_identifiability=False,
    extra_actions=(),
    extra_arguments=None,
    checks=CheckSettings(),
)

A PBPK/PD model: what the commands, the verification and the tests need.

All fields are keyword-only, so their order is not API. The sequences (data_paths, extra_actions and the formats of the figures) are stored as tuples, so a list can be passed and the model is hashable, unless the absolute tolerance of the simulator is an AbsoluteTolerance, which is not hashable.

Attributes:

Name	Type	Description
`name`	`str`	the short name, the suffix of the commands (`run_<name>`).
`package`	`str`	the dotted name of the model package, `__name__` in its `__init__.py`; relative references are relative to it.
`title`	`str`	the title of the model in the output of the commands.
`path`	`Path`	the directory of the model package, the base path of its experiments.
`model_path`	`Path`	the SBML model the experiments simulate.
`factory`	`str`	reference to the function which creates the models; it is called with the output directory.
`experiments`	`str \| None`	reference to the registry of the experiments, groups of experiment classes by name with the group `all`.
`fit_definitions`	`str \| None`	reference to the fit problems by name (`sbmlsim.fit.cli.FitDefinition`).
`data_paths`	`Sequence[Path]`	the directories of the study data.
`results_path`	`Path \| None`	the directory of the results, `<path>/results` by default.
`factory_path`	`Path \| None`	the output directory of the factory, the directory of `model_path` by default.
`archive_path`	`Path \| None`	the COMBINE archive the factory creates, linked by the `factory` action.
`simulator`	`SimulatorSettings`	the integrator settings of the experiments.
`figures`	`FigureSettings`	the formats and settings of the figures.
`reduced_selections`	`bool`	simulate only the selections the experiments need.
`save_results`	`bool`	store the results of the simulations by default.
`fit_identifiability`	`bool`	the fit command analyses the identifiability of the fitted parameters by default.
`extra_actions`	`Sequence[ExtraAction]`	actions the model adds to its `run` command.
`extra_arguments`	`str \| None`	reference to a function which adds the options of the extra actions to the parser of the `run` command.
`checks`	`CheckSettings`	the known exceptions of the tests of the model, see `pkpdsim.testing`.

results_dir `property` ¶

results_dir

The directory of the results.

simulation_dir `property` ¶

simulation_dir

The directory of the results of the simulation experiments.

fit_dir `property` ¶

fit_dir

The directory of the results of the fits.

report_dir `property` ¶

report_dir

The directory of the reports of stored parameters.

identifiability_dir `property` ¶

identifiability_dir

The directory of the identifiability analyses of stored parameters.

factory_dir `property` ¶

factory_dir

The output directory of the factory.

load_factory ¶

load_factory()

Get the function which creates the models.

load_experiments ¶

load_experiments()

Get the registry of the experiments.

load_fit_definitions ¶

load_fit_definitions()

Get the fit problems by name.

create_models ¶

create_models(output_dir=None)

Create the models with the factory.

Parameters:

Name	Type	Description	Default
`output_dir`	`Path \| None`	the output directory, `factory_dir` by default.	`None`

Returns:

Type	Description
`Path`	The output directory.

run_experiments ¶

run_experiments(
    experiment_classes,
    output_dir,
    *,
    save_results=None,
    show_report=False,
    figure_formats=None,
    simulator=None,
)

Run simulation experiments and create their report.

See pkpdsim.run.run_experiments; a run with a failed experiment or figure raises sbmlsim.experiment.ExperimentRunError after its report is written.

run_simulation_experiments ¶

run_simulation_experiments(
    experiment_classes,
    output_dir,
    *,
    show_report=False,
    figure_formats=None,
    simulator=None,
)

Run simulation experiments and collect their figures.

See pkpdsim.run.run_simulation_experiments.

run_main ¶

run_main(args=None)

The command run_<name>, see pkpdsim.cli.run_command.

fit_main ¶

fit_main(args=None)

The command fit_<name>, see pkpdsim.cli.fit_command.

Returns nothing: a console script exits with the return value of the function it calls, and 1 for anything which is not None or an int.

report_main ¶

report_main(args=None)

The command report_<name>, see pkpdsim.cli.report_command.

identifiability_main ¶

identifiability_main(args=None)

The command identifiability_<name>, see pkpdsim.cli.

check_reference ¶

check_reference(reference)

Check that a reference has the form "module:attribute".

The module may start with dots (relative to a package), the attribute may be dotted (an attribute of an attribute).

Parameters:

Name	Type	Description	Default
`reference`	`str`	the reference to check.	required

Raises:

Type	Description
`ValueError`	if the reference does not have the form.

resolve ¶

resolve(reference, package=None)

Resolve a reference "module:attribute" to the object it names.

Parameters:

Name	Type	Description	Default
`reference`	`str`	the reference; a module which starts with a dot is relative to `package`.	required
`package`	`str \| None`	the package of relative references.	`None`

Returns:

Type	Description
`Any`	The object.

Raises:

Type	Description
`ValueError`	if the reference is malformed or relative without a package.
`AttributeError`	if the module has no such attribute; the message names the reference.

normalize_formats ¶

normalize_formats(formats)

Get figure formats as a lower-case tuple.

Raises:

Type	Description
`TypeError`	if the formats are a single string, e.g. `"svg"` instead of `("svg",)`; a string is a sequence of characters.

model¶

SimulatorSettings dataclass ¶

FigureSettings dataclass ¶

sbmlsim_settings ¶

rc_params ¶

ExtraAction dataclass ¶

CheckSettings dataclass ¶

PKPDModel dataclass ¶

results_dir property ¶

simulation_dir property ¶

fit_dir property ¶

report_dir property ¶

identifiability_dir property ¶

factory_dir property ¶

load_factory ¶

load_experiments ¶

load_fit_definitions ¶

create_models ¶

run_experiments ¶

run_simulation_experiments ¶

run_main ¶

fit_main ¶

report_main ¶

identifiability_main ¶

check_reference ¶

resolve ¶

normalize_formats ¶

SimulatorSettings `dataclass` ¶

FigureSettings `dataclass` ¶

ExtraAction `dataclass` ¶

CheckSettings `dataclass` ¶

PKPDModel `dataclass` ¶

results_dir `property` ¶

simulation_dir `property` ¶

fit_dir `property` ¶

report_dir `property` ¶

identifiability_dir `property` ¶

factory_dir `property` ¶