Common features#

Note

The AMD tool is a collection of tools, meaning that some aspects of this section may not be applicable.

Tool context#

When running a tool, a tool context will be created. In it, all estimated models and their corresponding files are stored, as well as various result files and metadata. Using the Modelsearch tool with NONMEM for estimation, a tool context might look like this:

modelsearch1
├── annotations
├── log.csv
├── metadata.json
├── models
│   ├── final
│   │   ├── model.ctl
│   │   ├── model.ext
│   │   ├── ...
│   │   ├── mytab_mox1
│   │   ├── .pharmpy
│   │   │   ├── metadata.json
│   │   │   └── results.json
│   │   ├── stderr
│   │   └── stdout
│   ├── input
│   │   └── model.ctl
│   ├── modelsearch_run1
│   │   ├── model.ctl
│   │   ├── model.ext
│   │   └── ...
│   ├── modelsearch_run2
│   │   ├── model.ctl
│   │   ├── model.ext
│   │   └── ...
│   └── modelsearch_run3
│   │   ├── model.ctl
│   │   ├── model.ext
│   │   └── ...
│   └── ...
├── results.csv
├── results.html
├── results.json
└── subcontexts
    └── modelrank1
        └── ...

The top level modelsearch1 will contain files relevant for the whole tool, such as metadata and results. The subdirectory models will contain subfolders for each model candidate. Each candidate directory will contain the resulting NONMEM files, as well as NONMEM output in stderr and stdout. The subcontext directory contains tool directories for other tools that have been called (most commonly the ModelRank) tool, which in turn has the same structure with result files, model directory etc.

Running directory#

All tools are run in a temporary directory. This means that when Pharmpy starts a tool, the model candidates and their datasets will be written/copied to the temporary directory, and all estimations will be started there. When model has been estimated, it will be copied to the tool database.

Model database#

In the tool context, there will be two directories of interest: models and .modeldb. The models-directory is meant for interaction, and will contain all models that have been generated by the tool as well as the input model. The .modeldb-directory is a hidden directory on macOS and Linux and visible on Windows, but is not meant for interaction. In this directory the actual model files are stored, while the model directories in models use symlinks to .modeldb. The reason for this is that in a tool (especially in more complex tools like AMD), a model may appear multiple times, for example the input model for one of AMDs subtools is the final model of another. In order to avoid duplicating files, the .modeldb-directory will be used for all subtools, and then mapped with symlinks. In .modeldb the names of the directories are the hash of the model.

Datasets#

Pharmpy will create a directory .datasets in the .modeldb-directory where any unique datasets the tool creates (and the original dataset if used) will be stored. An example of this is when running Modelsearch and having zero order absorption in the search space, a RATE column will be created. If any of the stepwise algorithms are used, the subsequent models will have the “same” dataset, and thus only one copy of that dataset will be located in .datasets.

Results#

In general, the result objects will consist of a collection of summary tables. These can be accessed directly in your script:

res = run_modelsearch(model=start_model,
                      results=start_model_results,
                      search_space='ABSORPTION([FO,ZO]);PERIPHERALS([0,1])',
                      algorithm='reduced_stepwise',
                      rank_type='bic')
res.summary_models

For a more detailed description of which results are available, please check the documentation for each tool.

Additionally, Pharmpy will create at least two files: results.csv and results.json. The .csv is intended as a way to quickly look over your results, while the .json is a way to recreate the results object and can be read in with pharmpy.tools.read_results(). This allows for access to the different summary tables as data frames, and is intended to use to programmatically interact with the results. For most tools, a results.html will also be created, this is an interactive report of the tool.

res = read_results('path/to/results.json')
res.summary_models

It is also possible to read in models from the Tool context via the pharmpy.tools.retrieve_models() function.

Metadata#

For each tool run, a metadata file metadata.json will be created. This contains information about start- and end time, which options were used, which Pharmpy version etc. Example of metadata-file:

{
    "pharmpy_version": "2.1.1",
    "tool_name": "modelsearch",
    "stats": {
        "start_time": "2026-06-26T13:50:01.600421+02:00",
        "end_time": "2026-06-26T13:50:15.893176+02:00"
    },
    "tool_options": {
        "model": {
            "__class__": "Model",
            "key": "cxxVL_JcUw-PTxlLud-tpxfO9JWKQo-qClwsCgUQZxw"
        },
        "results": {
            "__class__": "ModelfitResults",
            "key": "cxxVL_JcUw-PTxlLud-tpxfO9JWKQo-qClwsCgUQZxw"
        },
        "search_space": "ABSORPTION([FO,ZO]);PERIPHERALS([0,1])",
        "algorithm": "exhaustive",
        "iiv_strategy": "absorption_delay",
        "rank_type": "mbic",
        "cutoff": null,
        "strictness": "minimization_successful and rse <= 0.7",
        "E": 0.5,
        "parameter_uncertainty_method": "SANDWICH"
    },
    "common_options": {
        "esttool": "nonmem",
        "validate_dataset": false,
        "always_create_new_dataset_file": false
    },
    "dispatching_options": {
        "context": {
            "__class__": "LocalDirectoryContext",
            "name": "modelsearch1",
            "ref": "/home/user/project"
        },
        "name": null,
        "ref": null,
        "broadcaster": "terminal",
        "dispatcher": "local_dask",
        "ncores": 8
    },
    "seed": 98368940603171891901847115121093584652
}