clinicadl.io.maps.Maps¶

class clinicadl.io.maps.Maps(path: Path | str)[source]¶

Python equivalent of a MAPS directory produced by a Trainer.

A MAPS directory is the core of ClinicaDL’s experiment management. It contains all the outputs produced by a training phase (models, metrics, logs, etc.), as well as all the hyperparameters used for training. Finally, it also contains the results of test and inference on new datasets.

Given that a MAPS directory is quite large and can be tedious to handle, this class allows the user to easily access all the files stored in it.

Here are the details of the files and subdirectories that you can find in a MAPS directory, as well as their Python “equivalent” (path → python equivalent):

Examples

Let’s say we have a MAPS directory in maps_dir:

from clinicadl.io.maps import Maps

maps = Maps("maps_dir")
maps.read()

To access the checkpoint of our neural network trained on the split 0 at the end of the \(10^{th}\) epoch:

>>> maps.training.splits[0].models.checkpoints.epochs[10].model_pt
PosixPath('maps_dir/training/split-0/models/checkpoints/epoch-10/model.pt')

To get the list of all saved checkpoints:

>>> maps.training.splits[0].models.checkpoints.epochs_list
[0, 5, 10]

create(overwrite: bool = False, exist_ok: bool = False) → None[source]¶

Creates the MAPS directory.

Parameters:

overwrite (bool, default=False) – Whether to overwrite the current directory.
exists_ok (bool, default=False) – If the directory already exists and overwrite=False, the function succeeds when exist_ok=True.

static open_file(path: Path | str) → Any[source]¶

To read and load any file inside the MAPS directory.

Parameters:: path (PathType) – The path in the MAPS directory.
Returns:: Any – The content of the file.
Raises:: FileNotFoundError – If the path does not match any existing file.

Examples

from clinicadl.io.maps import Maps

maps = Maps("maps_dir")
maps.read()

>>> maps.open_file(maps.metrics_json)
{
    "metrics": {
        "mse": {
            "name_": "MSEMetric",
            "get_not_nans": False,
            "pred_key": "output",
            "label_key": "label",
            "postprocessing": [],
            "reduction": "mean",
        },
    }
}
>>> maps.open_file(maps.training.splits[0].models.checkpoints.epochs[1].model_pt)
OrderedDict([('conv0.weight',
  tensor([[[[ 7.2531e-03,  5.7384e-03,  1.4988e-02,  ..., -3.1380e-02,
             -2.2103e-02,  5.8432e-02],
...
>>> maps.open_file(maps.training.data.data_tsv)
    participant_id  session_id
0   sub-001 ses-M000
1   sub-002 ses-M000
...

See also

save_file()

static save_file(obj: Any, path: Path | str, overwrite: bool = False) → None[source]¶

To save an object in any file of the MAPS directory.

Parameters:

obj (Any) – The object to save.
path (PathType) – The path in the MAPS directory.
overwrite (bool, default=False) – To overwrite the file if it exists.

Raises:

IsADirectoryError – If the path is not a file path.
FileExistsError – If the file exists and overwrite=False.
ValueError – If the file type is not supported. Supported file types in a MAPS directory are .json, .txt, .log, .tsv, and .pt.

Examples

from clinicadl.io.maps import Maps

maps = Maps("maps_dir")
maps.read()

>>> metrics = {
        "metrics": {
            "mse": {
                "name_": "MSEMetric",
                "get_not_nans": False,
                "pred_key": "output",
                "label_key": "label",
                "postprocessing": [],
                "reduction": "mean",
            },
        }
    }
>>> maps.save_file(metrics, maps.metrics_json)