cli¶

The commands of the models.

pkpdsim installs five console scripts which take the dotted name of a model package first and the options of the command for that model after it (main, resolve_model):

run_simulation pkdb_models.models.hctz --action factory
run_simulation pkdb_models.models.hctz --action list_experiments
run_simulation pkdb_models.models.hctz --action simulate --experiments "misc,Anderson1961" --open
run_simulation pkdb_models.models.hctz --action all --results-dir /path/to/results
run_simulation pkdb_models.models.hctz --action simulate --experiments all --uncertainty --draws 100
run_fit pkdb_models.models.hctz --subset PK --identifiability
run_fit pkdb_models.models.hctz --adopt PK_<fit id>
run_report pkdb_models.models.hctz --subset PK results/fit/PK_<fit id>/parameters.json
run_report pkdb_models.models.hctz --adopted
run_identifiability pkdb_models.models.hctz --subset PK results/fit/PK_<fit id>/parameters.json
run_credibility pkdb_models.models.hctz
run_credibility pkdb_models.models.hctz --from-json results/credibility/credibility.json -o /tmp/credibility

The package is imported and its model object MODEL gives everything which differs between two models; a model package registers no commands of its own.

run_simulation (run_command) creates the models with the factory and runs the simulation experiments and the extra actions of the model. A single group is written into the directory of the group, any other selection into custom_selection, both in the simulation folder of the results. The output ends with the links to the report and to the figures. --uncertainty runs the experiments over draws of the fitted parameters of the model and draws the curves of the simulations as bands of the quantiles of the draws, into the simulation_uncertainty folder of the results (see pkpdsim.uncertainty).

run_fit (fit_command) fits the parameters of a fit problem and, with --identifiability (the default of a model with fit_identifiability), analyses the identifiability of the fitted parameters: the profile likelihood of every fitted parameter and the Fisher information around the best parameter set, which end up in the identifiability section of the report of the fit. run_fit <package> --adopt <fit id> copies the record of a finished fit into the adopted fits of the model, whose values and uncertainty the factory takes (pkpdsim.uncertainty.adopt_fit). run_report and run_identifiability (report_command, identifiability_command) work on the parameters.json of an earlier fit (sbmlsim.fit.cli.report_cli, identifiability_cli); run_report <package> --adopted writes the report of every adopted fit of the model from its record (pkpdsim.reports.adopted_reports). run_credibility (credibility_command) assesses the contexts of use of the model against its adopted fits (pkpdsim.credibility.assess) and writes the record, the tables and the report (pkpdsim.credibility.report); with --from-json it writes them again from a written record. All write into the results of the model unless --output_dir is given.

--profile anywhere after the model package runs a command under the sampling profiler of python 3.15 and writes its flame graph and statistics into profiling/ of the results of the model, see pkpdsim.profiling; the commands also run as python -m pkpdsim.cli <command> <package> ....

DOTTED_PACKAGE `module-attribute` ¶

DOTTED_PACKAGE = re.compile(
    "^[A-Za-z_]\\w*(\\.[A-Za-z_]\\w*)*$"
)

The form of a dotted package, e.g. pkdb_models.models.hctz.

COMMANDS `module-attribute` ¶

COMMANDS = {
    command.name: command
    for command in (
        Command(
            name="run_simulation",
            description="Run the model factory, the simulation experiments and the extra actions of a model.",
            function=run_command,
            fits=False,
        ),
        Command(
            name="run_fit",
            description="Fit the parameters of a model and analyse their identifiability, or adopt a finished fit.",
            function=fit_command,
            fits=True,
        ),
        Command(
            name="run_report",
            description="Report stored parameters of a model.",
            function=report_command,
            fits=True,
        ),
        Command(
            name="run_identifiability",
            description="Analyse the identifiability of stored parameters of a model.",
            function=identifiability_command,
            fits=True,
        ),
        Command(
            name="run_credibility",
            description="Assess the contexts of use of a model against its adopted fits.",
            function=credibility_command,
            fits=True,
        ),
    )
}

The commands by the names of their console scripts.

Action ¶

Bases: StrEnum

The actions of the run command, pkpdsim.model.RUN_ACTIONS.

ModelNotFoundError ¶

Bases: LookupError

A package which is not found or is no model package.

Command `dataclass` ¶

Command(name, description, function, fits)

A command of the models, a console script of pkpdsim.

Attributes:

Name	Type	Description
`name`	`str`	the name of the console script.
`description`	`str`	what the command does, the description of its help.
`function`	`Callable[[PKPDModel, Sequence[str]], object]`	the command as a function of the model and the arguments after the model package.
`fits`	`bool`	the command needs the fit definitions of the model.

parse_formats ¶

parse_formats(text)

Get the figure formats of a comma separated list.

Parameters:

Name	Type	Description	Default
`text`	`str`	the formats, e.g. `"svg, PNG"`.	required

Returns:

Type	Description
`list[str]`	The formats in lower case, without blanks and empty entries.

parse_workers ¶

parse_workers(text, model)

Get the processes of a run from the option --workers.

Parameters:

Name	Type	Description	Default
`text`	`str`	`model` for the setting of the model, `auto` for the choice of sbmlsim (`None`: a pool of every CPU for a scan of 256 points or more), or a positive number.	required
`model`	`PKPDModel`	the model.	required

Returns:

Type	Description
`int \| None`	The number of processes, `None` for the choice of sbmlsim.

Raises:

Type	Description
`ValueError`	for any other text.

resolve_experiments ¶

resolve_experiments(registry, names)

Resolve the names of groups and experiments to the experiment classes.

Parameters:

Name	Type	Description	Default
`registry`	`Mapping[str, Sequence[type[SimulationExperiment]]]`	the groups of experiments of a model.	required
`names`	`Sequence[str]`	names of groups or of experiment classes.	required

Returns:

Type	Description
`list[type[SimulationExperiment]]`	The experiment classes, every class once in the order of the names, and
`list[str]`	the names which are neither a group nor an experiment.

run_parser ¶

run_parser(model)

Get the parser of the run command of a model.

run_command ¶

run_command(model, args=None)

Run the action of the command line of run_simulation.

Parameters:

Name	Type	Description	Default
`model`	`PKPDModel`	the model.	required
`args`	`Sequence[str] \| None`	the command line arguments, `sys.argv[1:]` by default.	`None`

A failure of the simulations does not stop the command: the remaining actions run, then the failures are printed and the command exits with 1. An extra action gets the settings of the simulator of the run as options.simulator: those of the model with the processes of --workers, and the settings of --uncertainty as options.uncertainty (None without).

with_output_dir ¶

with_output_dir(args, output_dir)

Add the output directory of the model to command line arguments.

The commands of sbmlsim.fit.cli write into the working directory by default, a model writes into its results instead.

Parameters:

Name	Type	Description	Default
`args`	`Sequence[str]`	command line arguments without the program name.	required
`output_dir`	`Path`	output directory used if the arguments do not name one.	required

Returns:

Type	Description
`list[str]`	The arguments with the output directory in front of them. argparse keeps
`list[str]`	the last value of an option, so an output directory in the arguments,
`list[str]`	also an abbreviation like `--out`, wins.

fit_parser ¶

fit_parser(model, definitions)

Get the parser of the fit command of a model.

The fit arguments are those of sbmlsim.fit.cli.fit_cli, the identifiability arguments are the settings of the profile likelihood which follows the fit.

analyse_identifiability ¶

analyse_identifiability(run, options)

Analyse the identifiability of the parameters of a finished fit.

The profile likelihood is the exact answer and the Fisher information the cheap local one next to it; both are computed around the best parameter set of the fit and end up in the identifiability section of its report.

Parameters:

Name	Type	Description	Default
`run`	`FitRun`	finished fit whose best parameter set is analysed.	required
`options`	`Namespace`	command line arguments of `fit_parser`.	required

Returns:

Type	Description
`tuple[IdentifiabilityResult \| None, FisherInformation \| None]`	The profiles and the Fisher information, `None` for what was skipped.

fit_command ¶

fit_command(model, args=None)

Run a fit of a model and analyse the identifiability of its parameters.

Parameters:

Name	Type	Description	Default
`model`	`PKPDModel`	the model.	required
`args`	`Sequence[str] \| None`	command line arguments, `sys.argv[1:]` by default.	`None`

Returns:

Type	Description
`dict[str, FitRun]`	The finished fits by optimization id, none for `--adopt`.

report_command ¶

report_command(model, args=None)

Report stored parameter sets of a model (sbmlsim.fit.cli.report_cli).

The report has the context of the model, with the fixed adopted fits which the record of the fit next to the parameters names (pkpdsim.fit.records_context). With --adopted the report of every adopted fit of the model is written from its record, see pkpdsim.reports.adopted_reports.

Parameters:

Name	Type	Description	Default
`model`	`PKPDModel`	the model.	required
`args`	`Sequence[str] \| None`	command line arguments, `sys.argv[1:]` by default.	`None`

Returns:

Type	Description
`Path`	The directory of the report, with `--adopted` the directory of the
`Path`	reports.

identifiability_command ¶

identifiability_command(model, args=None)

Analyse the identifiability of stored parameters of a model.

See sbmlsim.fit.cli.identifiability_cli.

Parameters:

Name	Type	Description	Default
`model`	`PKPDModel`	the model.	required
`args`	`Sequence[str] \| None`	command line arguments, `sys.argv[1:]` by default.	`None`

Returns:

Type	Description
`Path`	The directory of the report.

credibility_command ¶

credibility_command(model, args=None)

Assess the contexts of use of a model against its adopted fits.

The adopted fits are evaluated on the current model and data (pkpdsim.credibility.assess), --from-json instead reads a written record without evaluating a fit. The decisive predictions are verified (pkpdsim.credibility.verification) unless --no-verification is given. --source-commit records the commit of the source repository in the provenance, which a release passes, since it assesses the model in its release repository. The outputs replace an earlier assessment in the directory, see pkpdsim.credibility.report.write_outputs; an error of the declaration, the evidence, the records or the directory is printed and exits with 1.

Parameters:

Name	Type	Description	Default
`model`	`PKPDModel`	the model.	required
`args`	`Sequence[str] \| None`	command line arguments, `sys.argv[1:]` by default.	`None`

Returns:

Type	Description
`Path`	The directory of the outputs.

resolve_model ¶

resolve_model(package)

Get the model object MODEL of a model package.

Parameters:

Name	Type	Description	Default
`package`	`str`	the dotted name of the model package, e.g. `pkdb_models.models.hctz`.	required

Returns:

Type	Description
`PKPDModel`	The model object of the package.

Raises:

Type	Description
`ModelNotFoundError`	if the name is no dotted package, the package is not found, it has no `MODEL`, its `MODEL` is no `PKPDModel` or belongs to another package. Any other error of the import of the package, e.g. a missing module which the package imports, is raised as it is, with its traceback.

command_parser ¶

command_parser(command)

Get the parser of a command before its model is known.

The options of a command depend on the model, so this parser only prints the general usage and the errors of the model package.

main ¶

main(name, argv=None)

Run a command with the model package as the first argument.

The model is resolved first, since the options of the command depend on it; the arguments after the package are the arguments of the command.

Parameters:

Name	Type	Description	Default
`name`	`str`	the name of the command, a key of `COMMANDS`.	required
`argv`	`Sequence[str] \| None`	the command line arguments, `sys.argv[1:]` by default.	`None`

run_simulation_main ¶

run_simulation_main(argv=None)

The console script run_simulation, see run_command.

run_fit_main ¶

run_fit_main(argv=None)

The console script run_fit, see 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.

run_report_main ¶

run_report_main(argv=None)

The console script run_report, see report_command.

run_identifiability_main ¶

run_identifiability_main(argv=None)

The console script run_identifiability, see identifiability_command.

run_credibility_main ¶

run_credibility_main(argv=None)

The console script run_credibility, see credibility_command.

cli¶

DOTTED_PACKAGE module-attribute ¶

COMMANDS module-attribute ¶

Action ¶

ModelNotFoundError ¶

Command dataclass ¶

parse_formats ¶

parse_workers ¶

resolve_experiments ¶

run_parser ¶

run_command ¶

with_output_dir ¶

fit_parser ¶

analyse_identifiability ¶

fit_command ¶

report_command ¶

identifiability_command ¶

credibility_command ¶

resolve_model ¶

command_parser ¶

main ¶

run_simulation_main ¶

run_fit_main ¶

run_report_main ¶

run_identifiability_main ¶

run_credibility_main ¶

DOTTED_PACKAGE `module-attribute` ¶

COMMANDS `module-attribute` ¶

Command `dataclass` ¶