readDVH {DVHmetrics}

Read DVH text files

Description

Reads single or multiple DVH text files as exported from Varian Eclipse(TM), CadPlan(TM), OnCentra MasterPlan(TM), Philipps Pinnacle3 (TM), Elekta Monaco (TM), Tomo HiArt (TM), RaySearch Labs RayStation (TM), or Medcom ProSoma (TM). Supports cumulative and differential DVHs.

Usage

readDVH(x,
        type=c("Eclipse", "Cadplan", "Masterplan",
               "Pinnacle", "Monaco", "HiArt",
               "RayStation", "ProSoma", "PRIMO"),
        planInfo=FALSE, courseAsID=FALSE, add, ...)

Arguments

x

character vector giving paths to DVH text files. May contain globbing symbols understood by Sys.glob. If missing and in interactive mode, readDVH opens a file selector widget. Under Windows, this widget allows selecting multiple files simultaneously. For type="Pinnacle", x should be one of the following: A directory with information for one patient, a directory with several sub-directories (one for each patient), or a zip file of such directories. Under Windows, if x is missing and type="Pinnacle", readDVH opens a folder selector widget.

type

character. Indicates which program the DVH text files were exported from. Supported: "Cadplan" (tested with version 6.4.7), "Eclipse" (tested with Varian Eclipse version 10-15), "Masterplan" (tested with OnCentra MasterPlan version 4.3), "Pinnacle" (tested with Pinnacle3 version 9, see Details), "Monaco" (tested with Elekta Monaco version 5), "HiArt" (TomoTherapy HiArt), "RayStation" (tested with RaySearch Labs RayStation version 9A), "ProSoma" (Medcom ProSoma), "PRIMO" (tested with version 0.3.1.1558).

planInfo

Experimental: Either FALSE or character string. In the latter case, readDVH tries to extract additional information from the Plan field in the DVH file, e.g., the prescription dose for a sum plan or the boost quadrant. Undocumented, see source.

courseAsID

logical. If TRUE, the Course entry in the header section of a DVH file is appended to the regular patient ID. Currently supported only for type="Eclipse".

add

DVHLstLst object. Existing object that should be merged with the new data from the files.

...

Additional arguments passed on to file. Specify UTF-8 file encoding with encoding="UTF-8" or encoding="UTF-8-BOM" (when a byte-order-mark is used). Passing additional arguments is currently not supported when reading Pinnacle files. Additional arguments are also used for type="HiArt" where a list hiart may be supplied that specifies patient IDs, absolute structure volumes, and prescription dose. Same for type="RayStation" with a list "raystation". If Eclipse uncertainty plans are present, specify uncertainty=TRUE (see Details).

Details

Absolute dose values need to be given in Gy, cGy, or eV/g for uncalibrated dose in DVHs exported by PRIMO. Absolute volume values need to be given in in cm^3.

Differential DVHs are automatically converted to cumulative DVHs, but the differential DVH information is kept.

Sum plans are supported.

For Eclipse starting with version 13, the date format is locale dependent as it uses words for day and month. Importing those dates as class Date requires that the correct locale is set (see Sys.setlocale), and that files containing accents are read using the correct encoding (see above). Otherwise, date is stored as a character string.

For RayStation, only cumulative DVHs with absolute volume are currently supported. Volume is assumed to be measured in cm^3.

For files with absolute volume exported from Masterplan and Tomo HiArt, you can specify volume_from_dvh=TRUE if the structure volume should be guessed from the maximal volume given in the DVH for each structure.

Since files from HiArt, ProSoma and PRIMO do not contain info on patient ID, the current workaround is to generate a random ID.

To export data from Tomo HiArt, copy to clipboard and then save to file from a text editor. Support for Tomo HiArt files is currently limited to those with absolute dose. Please send an anonymized sample file if you need to read files with relative dose. You can provide a list hiart with more information about patients and structures. The list should have one component for each file you import. Each component itself has to be a named list with optional components

• date - a character string like "2022-01-16" for the date

• patName - a character string for patient name

• patID - a character string for patient ID

• doseRx - a character string like "50.4Gy" for prescription dose in the same dose unit as used in the DVHs

• structVol - a named character vector like c("PTV"=750, "LUNG"=1250) giving the absolute structure volumes with names equal to structure names

• volumeUnit - a character string, either "CC" or "cm3", for the structure volume unit)

The same approach can be used for RayStation files with a list raystation.

Pinnacle3 files have to be exported using its own scripting facility such that information from one patient is contained in one directory. A suitable export script is available on request from the package authors. The directory layout for one patient has to be as follows (experimental, likely to change in future versions):

• Files (CSV format with column headers):

  • DoseInfo.csv (variables "PrescriptionDose cGy", "NumberOfFractions", "Dosis cGy")

  • PatInfo.csv (variables "LastName", "FirstName", "MedicalRecordNumber")

  • PlanInfo.csv (variable "PlanName")

• Directory: Data:

  • Info.csv (variables "Filename", "RegionOfInterestName", "DoseMin cGy", "DoseMax cGy", "DoseMean cGy", "Volume ccm")

  • DVH1.csv, DVH2.csv, ... - the actual DVH data files with names defined in Info.csv variable "Filename". They should look like ⁠NumberOfDimensions = 2; NumberOfPoints = 431; Points[] ={ 0,0 10,0 ... 4000,100 }; ⁠

Value

Returns an object of class DVHLstLst. This is a list (one component with class DVHLst for each original file from one patient) of lists (each component is an object of class DVHs). A DVHs object is a list with the following components:

dvh

matrix - cumulative DVH values

dvhDiff

matrix - differential DVH values, only created a) if original file contained a differential DVH or b) by convertDVH

patID

character string - patient ID

date

character string - date of DVH export

type

character string - cumulative or differential DVH

plan

character string - plan name

course

character string - course - currently Eclipse only

structure

character string - structure name

structVol

numeric - structure volume

doseUnit

character string - measurement unit dose

volumeUnit

character string - measurement unit volume

doseRx

numeric - prescription dose

isoDoseRx

numeric - iso-dose percentage

doseMin

numeric - minimum dose from DVH file

doseMax

numeric - maximum dose from DVH file

doseAvg

numeric - average dose from DVH file

doseMed

numeric - median dose from DVH file

doseSD

numeric - dose standard deviation from DVH file

See Also

Sys.glob, readLines, print.DVHs, showDVH, getMetric, checkConstraint, convertDVH

Examples

## Not run: 
# pick DVH files interactively
res <- readDVH()
res

# read all txt files in subdirectory DVH
res <- readDVH("DVH/*.txt", type="Eclipse")
res

## End(Not run)