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.

A model whose studies include women has a female build next to the male one (female_model_path, the factory builds both from one definition, see pkpdsim.pbpk.create_archive): model_path stays the male build, the model of every caller which does not ask for a sex, and an experiment chooses the build of the sex of its subjects (pkpdsim.experiment.PKPDSimulationExperiment.sex).

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,
    jit_optimization=None,
)

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.
`jit_optimization`	`str \| None`	the optimization level with which LLJIT compiles the model for the runs of its experiments and the tests of `pkpdsim.testing` (`sbmlsim.model.model_roadrunner.JitOptimization`, `"O0"` to `"O3"`), `None` for the level of sbmlsim (`O2`, or the environment variable `SBMLSIM_JIT_OPTIMIZATION`). `"O0"` compiles a model with large initial assignments several times faster (the creatinine model in 4.5 s instead of 24 s) and simulates a little slower. The problems of the fits, their reports and the identifiability analysis (`run_fit`, `run_report`, `run_identifiability`, `pkpdsim.testing.start_fits`, `pkpdsim-verify fits`) load their models at the level, in the process and in every worker of a pool: their fit definitions carry it (`pkpdsim.fit.at_level`), and a problem carries its level into its workers, so neither the environment of the process nor that of a forkserver matters; `pkpdsim-verify dump` runs at it, and a test of a model loads its model at it with `PKPDModel.load_roadrunner`.

FigureSettings `dataclass` ¶

FigureSettings(*, formats=('svg',), 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`); SVG only by default, a run draws other formats on request (`--formats svg,png`).
`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,
    battery=dict(),
)

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.
`battery`	`Mapping[str, str]`	the checks of the battery of the builds which fail, by the id of the check (`pkpdsim.credibility.battery.BATTERY_CHECKS`, e.g. `steady_state`), see `pkpdsim.testing.check_battery`; a credibility assessment shows a known failure with its reason and still fails it.

PKPDModel `dataclass` ¶

PKPDModel(
    *,
    name,
    package,
    title,
    path,
    model_path,
    female_model_path=None,
    factory,
    experiments=None,
    fit_definitions=None,
    credibility=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(),
    fits=(),
    fits_path=None,
    release=None,
)

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 of the model.
`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, the male build: the model of every experiment and every caller which does not ask for a sex.
`female_model_path`	`Path \| None`	the female build of the model, `None` for a model without one; an experiment of women (`sex` of `pkpdsim.experiment.PKPDSimulationExperiment`) simulates it. The builds have the same ids, so a fit applies one parameter set to both, see `model_paths`.
`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`).
`credibility`	`str \| None`	reference to the declaration of the contexts of use (`pkpdsim.credibility.Credibility`), `None` for a model without one.
`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`.
`fits`	`Sequence[str]`	the ids of the adopted fits, whose records in `fits_dir` give the fitted values and their uncertainty, see `pkpdsim.uncertainty`.
`fits_path`	`Path \| None`	the folder of the adopted fits, `fits` next to the output directory of the factory by default.
`release`	`ReleaseSettings \| None`	the release metadata, see `pkpdsim.release.settings`; a model without it cannot be released.

model_paths `property` ¶

model_paths

The builds of the model by sex, the male build first.

A model is built for one sex (the reference values of the PBPK library are those of a sex, pkpdsim.pbpk.PBPKDefinition.sex); a model with a female build has both, a model without one the male build only. The builds have the same ids, so the changes of an experiment and the parameters of a fit apply to both.

results_dir `property` ¶

results_dir

The directory of the results.

simulation_dir `property` ¶

simulation_dir

The directory of the results of the simulation experiments.

uncertainty_dir `property` ¶

uncertainty_dir

The directory of the results of the experiments over the draws of the fits.

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.

credibility_dir `property` ¶

credibility_dir

The directory of the credibility assessments.

factory_dir `property` ¶

factory_dir

The output directory of the factory.

fits_dir `property` ¶

fits_dir

The folder of the adopted fits, next to the output of the factory.

model_path_of ¶

model_path_of(sex)

Get the build of a sex.

Parameters:

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

Returns:

Type	Description
`Path`	The SBML model of the sex.

Raises:

Type	Description
`ValueError`	if the model has no build of the sex.

load_roadrunner ¶

load_roadrunner(sex=MALE)

Load the build of a sex in roadrunner at the level of the model.

The model is compiled with LLJIT at SimulatorSettings.jit_optimization (sbmlsim.model.model_roadrunner.load_roadrunner), as its experiments load it, and not with roadrunner's default MCJIT, which compiles a model with large initial assignments much slower (48 s for creatinine): the loader of the tests of a model.

Parameters:

Name	Type	Description	Default
`sex`	`Sex`	the sex of the build.	`MALE`

Returns:

Type	Description
`RoadRunner`	The roadrunner instance.

Raises:

Type	Description
`ValueError`	if the model has no build of the sex.

fit_records ¶

fit_records()

Get the records of the adopted fits, see pkpdsim.uncertainty.FitRecords.

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.

load_credibility ¶

load_credibility()

Get the declaration of the contexts of use.

Raises:

Type	Description
`ValueError`	if the model has no declaration.
`TypeError`	if the reference is no `Credibility`.

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,
    uncertainty=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,
    uncertainty=None,
)

Run simulation experiments and collect their figures.

See pkpdsim.run.run_simulation_experiments.

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.

sex¶

The sex of a model build.

A model is built for one sex: the PBPK library takes the reference values of the sex when it builds a model (pkpdsim.pbpk.PBPKDefinition.sex, the ICRP 89 anatomy, the hematocrit, the partition coefficients, the GFR), so a study of women runs on a female build and a study of men on a male one. The model object holds a build per sex (pkpdsim.model.PKPDModel.model_paths, the male build the default) and an experiment chooses one (pkpdsim.experiment.PKPDSimulationExperiment.sex).

The module imports nothing else of pkpdsim, so that the model object and the library (which imports no simulator) share the enum.

Sex ¶

Bases: StrEnum

The sex of a model build, the sex of its reference individual.

model¶

SimulatorSettings dataclass ¶

FigureSettings dataclass ¶

sbmlsim_settings ¶

rc_params ¶

ExtraAction dataclass ¶

CheckSettings dataclass ¶

PKPDModel dataclass ¶

model_paths property ¶

results_dir property ¶

simulation_dir property ¶

uncertainty_dir property ¶

fit_dir property ¶

report_dir property ¶

identifiability_dir property ¶

credibility_dir property ¶

factory_dir property ¶

fits_dir property ¶

model_path_of ¶

load_roadrunner ¶

fit_records ¶

load_factory ¶

load_experiments ¶

load_fit_definitions ¶

load_credibility ¶

create_models ¶

run_experiments ¶

run_simulation_experiments ¶

check_reference ¶

resolve ¶

normalize_formats ¶

sex¶

Sex ¶

SimulatorSettings `dataclass` ¶

FigureSettings `dataclass` ¶

ExtraAction `dataclass` ¶

CheckSettings `dataclass` ¶

PKPDModel `dataclass` ¶

model_paths `property` ¶

results_dir `property` ¶

simulation_dir `property` ¶

uncertainty_dir `property` ¶

fit_dir `property` ¶

report_dir `property` ¶

identifiability_dir `property` ¶

credibility_dir `property` ¶

factory_dir `property` ¶

fits_dir `property` ¶