readDVH {DVHmetrics}R Documentation

Read DVH text files


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.


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



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.


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


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.


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".


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).


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

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):


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:


matrix - cumulative DVH values


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


character string - patient ID


character string - date of DVH export


character string - cumulative or differential DVH


character string - plan name


character string - course - currently Eclipse only


character string - structure name


numeric - structure volume


character string - measurement unit dose


character string - measurement unit volume


numeric - prescription dose


numeric - iso-dose percentage


numeric - minimum dose from DVH file


numeric - maximum dose from DVH file


numeric - average dose from DVH file


numeric - median dose from DVH file


numeric - dose standard deviation from DVH file

See Also

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


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

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

## End(Not run)

[Package DVHmetrics version 0.4.2 Index]