planAnalysis

Functions for evaluating and analyzing treatment plans, including DVH calculation and quality indicators.

matRad_indicatorWrapper(cst, pln, resultGUI, refGy, refVol)

matRad indictor wrapper

call

[dvh,qi] = matRad_indicatorWrapper(cst,pln,resultGUI) [dvh,qi] = matRad_indicatorWrapper(cst,pln,resultGUI,refGy,refVol)

Input:

cst – matRad cst struct
pln – matRad pln struct
resultGUI – matRad resultGUI struct
refGy – (optional) array of dose values used for V_XGy calculation default is [40 50 60]
refVol – (optional) array of volumes (0-100) used for D_X calculation default is [2 5 95 98] NOTE: Call either both or none!

Output:

dvh – matRad dvh result struct
qi – matRad quality indicator result struct
graphical display of all results

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_convertFromEvaluationMode(value, pln, evaluationMode)

matRad_convertFromEvaluationMode Convert evaluation values to per-fraction.

call

baseValue = matRad_convertFromEvaluationMode(value,pln,evaluationMode) [baseValue,evaluationMode,evaluationScale] = matRad_convertFromEvaluationMode(value,pln,evaluationMode)

input

value: numeric value, array, or empty value expressed in: evaluationMode

pln: matRad pln struct evaluationMode: ‘perFraction’ or ‘total’

output

baseValue: value converted to the per-fraction evaluation base evaluationMode: normalized evaluation mode string evaluationScale: scalar conversion factor from base to evaluationMode

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_resolveDoseAnalysisQuantity(resultGUI, pln, requestedQuantity)

matRad_resolveDoseAnalysisQuantity resolves the resultGUI dose field.

call

quantity = matRad_resolveDoseAnalysisQuantity(resultGUI,pln) quantity = matRad_resolveDoseAnalysisQuantity(resultGUI,pln,requestedQuantity)

input

resultGUI: matRad resultGUI struct pln: matRad pln struct requestedQuantity: optional explicit resultGUI dose field

output

quantity: selected resultGUI dose field

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_gammaIndex(cube1, cube2, resolution, criteria, slice, n, localglobal, cst)

gamma index calculation according to http://www.ncbi.nlm.nih.gov/pubmed/9608475

call

[gammaCube,gammaPassRateCell] = matRad_gammaIndex(cube1,cube2,resolution,criteria,cst) [gammaCube,gammaPassRateCell] = matRad_gammaIndex(cube1,cube2,resolution,criteria,slice,cst) [gammaCube,gammaPassRateCell] = matRad_gammaIndex(cube1,cube2,resolution,criteria,n,cst) [gammaCube,gammaPassRateCell] = matRad_gammaIndex(cube1,cube2,resolution,criteria,localglobal,cst) [gammaCube,gammaPassRateCell] = matRad_gammaIndex(cube1,cube2,resolution,criteria,slice,n,cst) … [gammaCube,gammaPassRateCell] = matRad_gammaIndex(cube1,cube2,resolution,criteria,slice,n,localglobal,cst)

Input:

cube1 – dose cube as an M x N x O array
cube2 – dose cube as an M x N x O array
resolution – resolution of the cubes [mm/voxel]
criteria – [1x2] vector specifying the distance to agreement criterion; first element is percentage difference, second element is distance [mm]
slice – (optional) slice in cube1/2 that will be visualized
n – (optional) number of interpolations. there will be 2^n-1 interpolation points. The maximum suggested value is 3.
localglobal – (optional) parameter to choose between ‘global’ and ‘local’ normalization
cst – list of interessing volumes inside the patient

output

gammaCube: result of gamma index calculation gammaPassRateCell: rate of voxels passing the specified gamma criterion, evaluated for every structure listed in ‘cst’. Note that only voxels exceeding the dose threshold are considered.

References: [1] http://www.ncbi.nlm.nih.gov/pubmed/9608475

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_calcQualityIndicators(cst, pln, doseCube, refGy, refVol)

matRad_calcQualityIndicators calculates DVH quality indicators.

call: qi = matRad_calcQualityIndicators(cst,pln,doseCube) qi = matRad_calcQualityIndicators(cst,pln,doseCube,refGy,refVol)
input: cst: matRad cst cell array pln: matRad pln struct doseCube: per-fraction dose cube refGy: (optional) per-fraction dose values for V_XGy calculation refVol:(optional) volume percentages for D_X calculation
output: qi: quality indicators in per-fraction dose units
References: van’t Riet et. al., IJROBP, 1997 Feb 1;37(3):731-6. Kataria et. al., J Med Phys. 2012 Oct-Dec; 37(4)

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_showDVH(dvh, cst, varargin)

matRad dvh visualizaion

call

matRad_showDVH(dvh,cst) matRad_showDVH(dvh,cst,pln) matRad_showDVH(dvh,cst,Name,Value) matRad_showDVH(dvh,cst,pln,Name,Value)

Input:

dvh – result struct from fluence optimization/sequencing
cst – matRad cst struct
pln – (now optional) matRad pln struct, standard uses Dose [Gy]
lineStyleIndicator – (optional) integer (1,2,3,4) to indicate the current linestyle (hint: use different lineStyles to overlay different dvhs)

Output:

graphical display of DVH

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_sampling(ct, stf, cst, pln, w, structSel, multScen)

matRad_randomSampling enables sampling multiple treatment scenarios

call

[cst,pln] = matRad_setPlanUncertainties(ct,cst,pln)

Input:

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

Output:

caSampRes – cell array of sampling results depicting plan parameter
mSampDose – matrix holding the sampled doses, each row corresponds to one dose sample
pln – matRad pln struct containing sampling information
resultGUInomScen – resultGUI struct of the nominal scenario

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_compareDose(cube1, cube2, ct, cst, enable, contours, pln, criteria, n, localglobal)

Comparison of two dose cubes in terms of gamma index, absolute and visual difference

call

[gammaCube,gammaPassRate,hfig] = matRad_compareDose(cube1, cube2, ct, cst) [gammaCube,gammaPassRate,hfig] = matRad_compareDose(cube1, cube2, ct, cst,enable , contours, pln, criteria, n,localglobal)

Input:

cube1 – dose cube 1 as an M x N x O array
cube2 – dose cube 2 as an M x N x O array
ct – ct struct with ct cube
cst – list of interesting volumes inside the patient as matRad struct (optional, does not calculate gamma and DVH)
enable (optional) – boolean 3x1 array [1 0 0]: evaluate only basic plots [0 1 0]: evaluate only line profiles [0 0 1]: evaluate only DVH
contours (optional) – ‘on’ or ‘off’
pln (optional)
criteria – (optional)[1x2] vector specifying the distance to agreement criterion; first element is percentage difference, second element is distance [mm], default [3 3]
n – (optional) number of interpolations. there will be 2^n-1 interpolation points. The maximum suggested value is 3. default n=0
localglobal – (optional) parameter to choose between ‘global’ and ‘local’ normalization

Output:

gammaCube – result of gamma index calculation
gammaPassRate – rate of voxels passing the specified gamma criterion evaluated for every structure listed in ‘cst’. note that only voxels exceeding the dose threshold are considered.
hfig – Figure handle struct for all 3 figures and subplots, indexed by plane names

References gamma analysis:: [1] http://www.ncbi.nlm.nih.gov/pubmed/9608475

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_showQualityIndicators(figHandle, qi)

matRad display of quality indicators as table

call

matRad_showQualityIndicators(qi)

Input:

figHandle – handle to figure to display the Quality Indicators in
qi – result struct from matRad_calcQualityIndicators

Output:

graphical display of quality indicators in table form

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_EQD2accumulation(pln1, ct1, cst1, dose1, prescribedDose1, pln2, ct2, cst2, dose2, prescribedDose2)

matRad function to accumulate and compare dose and EQD2 for two treatment plans

call

result = matRad_EQD2accumulation(pln1,ct1,cst1,dose1,prescribedDose1, …: pln2,ct2,cst2,dose2,prescribedDose2)

Input:

pln1/2 – matRad pln struct
ct1/2 – matRad ct struct
cst1/2 – matRad cst struct
dose1/2 – 3D (RBE-weighted) dose cubes
prescribedDose1/2 – prescribed doses of the respective dose cubes

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_convertToEvaluationMode(rawValue, pln, evaluationMode)

matRad_convertToEvaluationMode Convert per-fraction values for evaluation.

call

convertedValue = matRad_convertToEvaluationMode(rawValue,pln,evaluationMode) [convertedValue,evaluationMode,evaluationScale] = matRad_convertToEvaluationMode(rawValue,pln,evaluationMode)

input

rawValue: numeric value, array, or empty per-fraction value pln: matRad pln struct evaluationMode: ‘perFraction’ or ‘total’

output

convertedValue: rawValue converted for the requested evaluation mode evaluationMode: normalized evaluation mode string evaluationScale: scalar conversion factor applied to rawValue

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_getTargetReferenceDoses(cst, pln)

matRad_getTargetReferenceDoses resolves per-fraction target doses.

call

targetDoseInfo = matRad_getTargetReferenceDoses(cst,pln)

input

cst: matRad cst cell array pln: matRad pln struct

output

targetDoseInfo: struct array with one entry per TARGET VOI. Each: entry contains cstIndex, name, and refDose in dose per fraction.

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_calcDVH(cst, doseCube, dvhType, doseGrid)

matRad dvh calculation

call

dvh = matRad_calcDVH(cst,doseCube) dvh = matRad_calcDVH(cst,doseCube,dvhType) dvh = matRad_calcDVH(cst,doseCube,doseGrid) dvh = matRad_calcDVH(cst,doseCube,dvhType,doseGrid)

Input:

cst – matRad cst struct
doseCube – arbitrary doseCube (e.g. physicalDose)
dvhType – (optional) string, ‘cum’ for cumulative, ‘diff’ for differential dvh
doseGrid – (optional) use predefined evaluation points. Useful when comparing multiple realizations

Output:

dose volume histogram

References: van’t Riet et. al., IJROBP, 1997 Feb 1;37(3):731-6. Kataria et. al., J Med Phys. 2012 Oct-Dec; 37(4): 207�213.

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.

Sampling Analysis 

Sampling-based plan analysis for robustness evaluation.

matRad_samplingAnalysis(ct, cst, pln, caSampRes, mSampDose, resultGUInomScen, varargin)

matRad uncertainty sampling analysis function

call

[structureStat, doseStat] = samplingAnalysis(ct,cst,subIx,mSampDose,w)

Input:

ct – ct cube
cst – matRad cst struct
pln – matRad’s pln struct
caSampRes – cell array of sampling results depicting plan parameter
mSampDose – matrix holding the sampled doses, each row corresponds to one dose sample
resultGUInomScen – resultGUI struct of the nominal plan
varargin – optional Name/Value pairs for additional custom settings - ‘GammaCriterion’: 1x2 vector [% mm] - ‘Percentiles’: vector with desired percentiles between (0,1)

Output:

cstStat structure-wise statistics (mean, max, percentiles, …)
doseStat dose-wise statistics (mean, max, percentiles, …)
meta contains additional information about sampling analysis

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_latexReport(outputPath, ct, cst, pln, nominalScenario, structureStat, doseStat, sampDose, listOfQI, varargin)

matRad uncertainty analysis report generaator function

call

latexReport(ct, cst, pln, nominalScenario, structureStat)

Input:

outputPath – where to generate the report
ct – ct cube
cst – matRad cst struct
pln – matRad plan meta information struct
nominalScenario – struct containing dose, qi and dvh of the nominal scenario
structureStat – structures which were examined (can be empty, when all structures were examined)
doseStat – structure containing dose statistics as returned from matRad_samplingAnalysis
sampDose – matrix containing all sampled Doses as returned from matRad_samplingAnalysis
listOfQI – cellstring containing list of quality indicators to be reported
Optional Name-Value Pairs
ComputationTime – state computation time to state in the report
OperatorName – Name of the Operator generating the report
SufficientStatistics – true/false (to warn for bad statistics)
PrescribedDose – Set a prescription value. If not set, will use the largest value found in target objectives

matRad_calcStudy(multScen, varargin)

matRad uncertainty study wrapper

call

matRad_calcStudy(structSel,multScen,matPatientPath,param)

Input:

structSel – structures which should be examined (can be empty, to examine all structures) cube
multScen – parameterset of uncertainty analysis
matPatientPath – (optional) absolut path to patient mat file. If empty mat file in current folder will be used
param – structure defining additional parameter outputPath

Output:

(binary) all results are saved; a pdf report will be generated – and saved

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_setupStudyTemplate: configuration script for uncertainty sampling

Copyright 2017-2026 the matRad development team.

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_createAnimationForLatexReport(confidenceValue, ct, cst, slice, meanCube, mRealizations, scenProb, subIx, outpath, legendColorbar, varargin)

matRad function to create figures for a GIF animation

call

matRad_createAnimationForLatexReport(confidenceValue, ct, cst, slice, …: meanCube, mRealizations, scenProb, subIx, outpath, legendColorbar)

Input:

confidenceValue confidence used for visualization
ct matRad ct struct
cst matRad cst struct
slice slice of the ct used for visualization
meanCube cube holding the mean dose
mRealzations samples
scenProb linear vector of all probabilities for the individual – scenarios
subIx voxel indices that are considered during analysis
outpath output path for files
legendColorbar colorbar used for the legend
Additional Name Value Pairs
PrescribedDose prescription (per fraction)
FramesPerSecond frames per second for the animation (default 24)
Period total period [s] for the animation (default 5)
FilePrefix default ‘anim’

output:

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_getGaussianOrbitSamples(mu, SIGMA, nFrames, varargin)

matRad orbit sampling

call

samples = matRad_getGaussianOrbitSamples(mu,SIGMA,nFrames) samples = matRad_getGaussianOrbitSamples(mu,SIGMA,nFrames,xr) samples = matRad_getGaussianOrbitSamples(___,Name,Value)

Input:

mu mean vector
SIGMA covariance matrix
nFrames number of sample frames
xr (optional)
Optional Name-Value-Pairs
Method – can be either ‘chol’ (default, fast) or ‘eig’ (more stable but slow)
MaximumTriesChol – number of maxim tries to make matrix PSD for cholesky decomposition. Default is 10

output:

References: [1] http://mlss.tuebingen.mpg.de/2013/Hennig_2013_Animating_Samples_from_Gaussian_Distributions.pdf [2] http://www.sciencedirect.com/science/article/pii/0024379588902236

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.

planAnalysis

Sampling Analysis

configuration script for uncertainty sampling

Sampling Analysis 