matRad API Documentation

matRad is separted into a top-level API that consists of a few functions to run the treatment planning workflow resting on the top-level of the the matRad folder / module. The core implementation is organized in several subdirectories / submodules that are called by the API functions and can be used for more fine-grained development. Startup and configuration functions are located in the root of the repository.

Note

The root-level scripts (matRad.m, matRadGUI.m, matRad_rc.m etc.) are not auto-documented here. See the Using the matRad.m script guide for usage information.

Below, the top-level matRad functions are explained. For more specialized functions, refer to the documentation of the respective Modules / Subfolders.

Global Configuration 

matRad’s global configuration class MatRad_Config is used to set up the environment and configuration for the matRad application. It is implemented as a Singleton pattern and thus consistent throughout a matRad session.

At the core, the class handles user folders, caches the environment (Matlab/Octave), provides matRad’s version, and stores default parameters. The class also provides logging functionality enabling control over output via log levels.

class MatRad_Config

Bases: handle

MatRad_Config MatRad Configuration class This class is used globally through Matlab to handle default values and logging and is declared as global matRad_cfg.

Usage:: matRad_cfg = MatRad_Config.instance();

This file is part of the matRad project. It is subject to the license terms in the LICENSE file found in the top-level directory of this distribution and at https://github.com/e0404/matRad/LICENSE.md. No part of the matRad project, including this file, may be copied, modified, propagated, or distributed except according to the terms contained in the LICENSE file.

MatRad_Config Constructs an instance of this class. The configuration is implemented as a singleton and used globally Therefore its constructor is private For instantiation, use the static MatRad_Config.instance();

Property Summary

logLevel = 4: Logging

keepLog = false: Stores the full log in memory

writeLog = false: Writes the log to a file on-the-fly

defaults

disableGUI = false: Disable GUI

devMode = false

eduMode = false

gui

userfolders: Cell array of user folders containing machines, patients, hluts. Default contains the userdata folder in the matRad root directory

propDoseCalc: Default Properties

propOpt

propStf

messageLog = {}

logFileHandle

env: For storing the Environment & its version

envVersion

isOctave: Helper bool to check for Octave

isMatlab: Helper bool to check for Matlab

matRad_version: MatRad version string

matRadRoot: Path to matRadRoot

matRadSrcRoot: Path to matRadSrcRoot (“matRad” subfolder of matRadRoot)

primaryUserFolder: Points to the first entry in userfolders

exampleFolder: Contains examples

thirdPartyFolder: Contains third party tools/libraries used in matRad

Method Summary

delete(~): might not be desired by users rmpath(genpath(matRad_cfg.matRadRoot));

displayToConsole(type, formatSpec, varargin)

displayToConsole lowest-level logging function for matRad.: Display to console will be called from the public wrapper functions dispError, dispWarning, dispInfo, dispDebug

Input:

type – type of the log information. Needs to be one of ‘error’, ‘warning’, ‘info’ or ‘debug’.
formatSpec – string to print using format specifications similar to fprintf
varargin – variables according to formatSpec

reset(): Set all default properties for matRad’s computations

setDefaultProperties(): setDefaultProperties set matRad’s default computation properties

setDefaultPropertiesForTesting(): setDefaultPropertiesForTesting sets matRad’s default properties during testing to reduce computational load

setDefaultPropertiesForEduMode()

setDefaultGUIProperties(): Detect current theme

dispDebug(formatSpec, varargin)

dispDebug print debug messages (log level >= 4)

Input:

formatSpec – string to print using format specifications similar to fprintf
varargin – variables according to formatSpec

dispInfo(formatSpec, varargin)

dispInfo print information console output (log level >= 3)

Input:

formatSpec – string to print using format specifications similar to fprintf
varargin – variables according to formatSpec

dispError(formatSpec, varargin)

dispError print errors (forwarded to “error” that will stop the program) (log level >= 1)

Input:

formatSpec – string to print using format specifications similar to ‘error’
varargin – variables according to formatSpec

dispWarning(formatSpec, varargin)

dispError print warning (forwarded to ‘warning’) (log level >= 2)

Input:

formatSpec – string to print using format specifications similar to ‘warning’
varargin – variables according to formatSpec

dispDeprecationWarning(formatSpec, varargin): dispDeprecationWarning wrapper for deprecation warnings forwarded to displayToConsole

writeLogToFile(filename): writeLogToFile writes the log kept in MatRad_Config to file. Note that the switch keepLog must be enabled for MatRad_Config to store all logging output.

getEnvironment(): getEnvironment function to get the software environment matRad is running on

getDefaultProperties(pln, fields): Function to load all non-set parameters into pln struct

configureEnvironment()

static instance(): instance creates a singleton instance of MatRad_Config In MatRad_Config, the constructor is private to make sure only on global instance exists. Call this static functino to get or create an instance of the matRad configuration class

static loadobj(sobj): Overload the loadobj function to allow downward compatibility with workspaces which where saved as an older version of this class

Top-level API functions 

matRad_calcDoseForward(ct, cst, stf, pln, w)

matRad forward dose calculation (no dij)

call

resultGUI = matRad_calcDoseForward(ct,cst,stf,pln) %If weights stored in stf resultGUI = matRad_calcDoseForward(ct,cst,stf,pln,w)

Input:

ct – ct cube
cst – matRad cst cell array
stf – matRad steering information struct
pln – matRad plan meta information struct
w – optional (if no weights available in stf): bixel weight vector

Output:

resultGUI – matRad result struct

References

This file is part of the matRad project. It is subject to the license terms in the LICENSE file found in the top-level directory of this distribution and at https://github.com/e0404/matRad/LICENSE.md. No part of the matRad project, including this file, may be copied, modified, propagated, or distributed except according to the terms contained in the LICENSE file.

matRad_generateStf(ct, cst, pln, visMode)

matRad steering information generation

call

stf = matRad_generateStf(ct,cst,pln)

Input:

ct – ct cube
cst – matRad cst struct
pln – matRad plan meta information struct

Output:

stf – matRad steering information struct

References

This file is part of the matRad project. It is subject to the license terms in the LICENSE file found in the top-level directory of this distribution and at https://github.com/e0404/matRad/LICENSE.md. No part of the matRad project, including this file, may be copied, modified, propagated, or distributed except according to the terms contained in the LICENSE file.

matRad_version(matRadRoot)

matRad function to get the current matRad version (and git information when used from within a repository

call

[versionString,matRadVer] = matRad_version() [versionString,matRadVer] = matRad_version(matRadRoot)

Input:

matRadRoot – Optional Root Directory. This is for call in matRad initialization when MatRad_Config is not yet available

Output:

versionString – Readable string build from version information
matRadVer – struct with version information

References

This file is part of the matRad project. It is subject to the license terms in the LICENSE file found in the top-level directory of this distribution and at https://github.com/e0404/matRad/LICENSE.md. No part of the matRad project, including this file, may be copied, modified, propagated, or distributed except according to the terms contained in the LICENSE file.

matRad_calcDoseInfluence(ct, cst, stf, pln)

matRad dose calculation automaticly creating the appropriate dose engine for the given pln struct and called the associated dose calculation funtion

call

dij = matRad_calcDoseInfluence(ct,cst,stf,pln)

Input:

ct – ct cube
cst – matRad cst cell array
stf – matRad steering information struct
pln – matRad plan meta information struct

Output:

dij – matRad dij struct

References

This file is part of the matRad project. It is subject to the license terms in the LICENSE file found in the top-level directory of this distribution and at https://github.com/e0404/matRad/LICENSE.md. No part of the matRad project, including this file, may be copied, modified, propagated, or distributed except according to the terms contained in the LICENSE file.

matRad_directApertureOptimization(dij, cst, apertureInfo, optResult, pln)

matRad function to run direct aperture optimization

call

[optResult,optimizer] = matRad_directApertureOptimization(dij,cst,apertureInfo,optResult,pln)

Input:

dij – matRad dij struct
cst – matRad cst struct
apertureInfo – aperture shape info struct
optResult – resultGUI struct to which the output data will be added, if this field is empty optResult struct will be created
pln – matRad pln struct

Output:

optResult – struct containing optimized fluence vector, dose, and shape info
optimizer – used optimizer object

References: [1] http://dx.doi.org/10.1118/1.4914863

This file is part of the matRad project. It is subject to the license terms in the LICENSE file found in the top-level directory of this distribution and at https://github.com/e0404/matRad/LICENSE.md. No part of the matRad project, including this file, may be copied, modified, propagated, or distributed except according to the terms contained in the LICENSE file.

matRad_fluenceOptimization(dij, cst, pln, wInit)

matRad inverse planning wrapper function

call

[resultGUI,optimizer] = matRad_fluenceOptimization(dij,cst,pln) [resultGUI,optimizer] = matRad_fluenceOptimization(dij,cst,pln,wInit)

Input:

dij – matRad dij struct
cst – matRad cst struct
pln – matRad pln struct
wInit – (optional) custom weights to initialize problems

Output:

resultGUI – struct containing optimized fluence vector, dose, and (for biological optimization) RBE-weighted dose etc.
optimizer – Used Optimizer Object

References

This file is part of the matRad project. It is subject to the license terms in the LICENSE file found in the top-level directory of this distribution and at https://github.com/e0404/matRad/LICENSE.md. No part of the matRad project, including this file, may be copied, modified, propagated, or distributed except according to the terms contained in the LICENSE file.

matRad_sequencing(resultGUI, stf, dij, pln, visBool)

matRad inverse planning wrapper function

call

resultGUI = matRad_sequencing(resultGUI,stf,dij,pln)

Input:

dij – matRad dij struct
stf – matRad stf struct
pln – matRad pln struct
resultGUI – struct containing optimized fluence vector, dose, and (for biological optimization) RBE-weighted dose etc.

Output:

resultGUI – struct containing optimized fluence vector, dose, and (for biological optimization) RBE-weighted dose etc.

References

This file is part of the matRad project. It is subject to the license terms in the LICENSE file found in the top-level directory of this distribution and at https://github.com/e0404/matRad/LICENSE.md. No part of the matRad project, including this file, may be copied, modified, propagated, or distributed except according to the terms contained in the LICENSE file.

matRad_planAnalysis(resultGUI, ct, cst, stf, pln, varargin)

matRad plan analysis function This function performs analysis on radiation therapy plans, including DVH (Dose-Volume Histogram) and quality indicators. It optionally displays these analyses based on input parameters.

Input:

resultGUI – matRad resultGUI struct containing the analysis results
ct – matRad ct struct with computed tomography data
cst – matRad cst cell array with structure definitions
stf – matRad stf struct with beam information
pln – matRad pln struct with plan information
name / value pairs – Optional parameters for analysis customization
refGy – (optional) Dose values for V_XGy calculation (default: [40 50 60])
refVol – (optional) Volume percentages for D_X calculation (default: [2 5 95 98])

Output:

resultGUI – Updated resultGUI with analysis data

matRad API Documentation

Global Configuration

Top-level API functions

Modules / Subfolders

Global Configuration 

Top-level API functions 

Modules / Subfolders 