The Userfolder Setup

matRad uses one or more userfolders to store user-provided data and generated files outside the version-controlled source tree. The folders are managed centrally by the global configuration object MatRad_Config and are available through matRad_cfg.userfolders if matRad_cfg = MatRad_Config.instance(); or matRad_rc has been called before.

The userfolder mechanism is intended for resources such as custom machine files, patients, HLUTs, scripts, and temporary working directories created by external dose engines. It complements the repository content by providing a writable location for user-specific data.

The source tree of matRad already contains a default userfolder at <matRadRoot>/userdata. This folder is included in the default search path and can be used immediately for custom data. However, users are free to configure additional folders in their home directory or via environment variable.

Default behavior

The configured userfolders are collected during startup in MatRad_Config.updateUserfolders().

When matRad is run from source, the default search order is:

  1. <matRadRoot>/userdata/

  2. <home>/matRad if this folder already exists

  3. Any additional folders listed in the MATRAD_USERDATA environment variable

When matRad is deployed, the default is:

  1. <home>/matRad

  2. Any additional folders listed in the MATRAD_USERDATA environment variable

The MATRAD_USERDATA variable is interpreted as a semicolon-separated list of existing directories.

Note

The first entry in matRad_cfg.userfolders is exposed separately as matRad_cfg.primaryUserFolder. This is the default writable location used by several matRad components.

Automatically created subfolders

If a configured userfolder does not yet exist, matRad creates it on demand. It also tries to create the following standard subfolders:

  • hluts

  • machines

  • patients

  • scripts

These subfolders are used throughout matRad for user-supplied resources. For example, machine data are searched in machines and HLUT files in hluts.

Search and path handling

Each configured userfolder is added to the MATLAB path together with its subfolders. This makes helper scripts placed in the userfolder tree directly accessible from MATLAB.

If the list of userfolders is changed at runtime, MatRad_Config updates the MATLAB path accordingly:

  • newly added folders are added to the path

  • removed folders are removed from the path

If an empty list is assigned, matRad falls back to the default userdata folder in the matRad installation.

How matRad uses the userfolders

The userfolder list is used as a search path for several kinds of data. Typical examples are:

  • custom machines in machines

  • patient files in patients

  • HLUT definitions in hluts

  • user scripts in scripts

  • engine-specific working directories below primaryUserFolder

Because primaryUserFolder always points to the first configured entry, changing the order of matRad_cfg.userfolders also changes where matRad writes default output for features that rely on this property.

MATLAB examples

Inspect the currently active configuration:

global matRad_cfg
matRad_cfg = MatRad_Config.instance();

matRad_cfg.userfolders
matRad_cfg.primaryUserFolder

Set a custom list of userfolders at runtime:

global matRad_cfg
matRad_cfg = MatRad_Config.instance();

matRad_cfg.userfolders = { ...
    fullfile(matRad_cfg.matRadRoot,'userdata'), ...
    fullfile(getenv('USERPROFILE'),'matRad'), ...
    'D:\matRadData\projectA' ...
};

Add additional userfolders via the environment before starting MATLAB:

setenv('MATRAD_USERDATA', 'D:\matRadData\projectA;D:\matRadData\shared')
global matRad_cfg
matRad_cfg = MatRad_Config.instance();

Tip

For local scripts and experimental data, the repository-local userdata folder is usually the safest starting point because it is separated from the tracked source files.