% -*- mode: noweb; noweb-default-code-mode: R-mode; -*-
%\VignetteIndexEntry{Documentation}
%\VignetteKeywords{Preprocessing}
%\VignetteDepends{RadOnc}
%\VignettePackage{RadOnc}
%documentclass[12pt, a4paper]{article}
\documentclass[12pt]{article}

\usepackage{amsmath,amscd}
\usepackage{graphicx, verbatim}
\usepackage{hyperref}
\usepackage[authoryear,round]{natbib}
\usepackage{chapterbib}
\setcitestyle{numbers}
\usepackage{float}
\usepackage{lscape}

\textwidth=6.5in
\textheight=9in
\oddsidemargin=0in
\evensidemargin=0in
\headheight=-.3in

\newcommand{\scscst}{\scriptscriptstyle}
\newcommand{\scst}{\scriptstyle}
\newcommand{\Rfunction}[1]{{\texttt{#1}}}
\newcommand{\Robject}[1]{{\texttt{#1}}}
\newcommand{\Rpackage}[1]{{\textit{#1}}}

\begin{document}

\title{Radiation Oncology (RadOnc) Tools}
\author{Reid F. Thompson}

\maketitle
\tableofcontents
%%\newpage
%%\listoffigures
\newpage
\section{Introduction}
\label{intro}
The \Rpackage{RadOnc} package provides a number of tools for the import and analysis of dose-volume histogram (DVH) data used routinely in Radiation Oncology clinical practice and research.  Supported formats for data import currently include:
\begin{itemize}
\item Varian's Aria/Eclipse platform (v.10 and v.11)
\item CadPlan (for historical/archival data)
\item TomoTherapy
\item RayStation
\item Elekta's Monaco platform
\item DICOM-RT files
\end{itemize}

The functionality contained herein also enables visualization of dosimetric and volumetric data, and statistical comparison among multiple DVHs and three-dimensional structures. In order to use these tools, you must first load the \Rpackage{RadOnc} package:
<<echo=TRUE,keep.source=FALSE,results=hide>>=
library(RadOnc)
@
<<echo=FALSE,results=hide>>=
data.path <- system.file("extdata", package="RadOnc")
initial.path <- getwd()
options(width=75)
@

It is assumed that the reader is already familiar with DVH analysis. If this is not the case, consult the relevant literature for a thorough treatment of the subject \citep{dvh}.

Throughout this vignette, we will be exploring actual data for 2 patients, each possessing a set of 10 structures (including organs at risk and treatment planning volumes). We will also demonstrate rudimentary three-dimensional structural processing and a number of other features.

For additional reference and details, please consult our published report on the \Rpackage{RadOnc} package\citep{radonc}.

\newpage
\section{Changes for \Rpackage{RadOnc} in current release}
\label{current.version.changes}
\begin{itemize}
      \item Added ability to display gridlines when plotting DVH graphs.
      \item Added ability to extract median dose as a dosimetric parameter.
      \item Added ability to check for arbitrary dose constraints (e.g. \Rfunction{V20Gy < 15(\%)}).
      \item New function \Rfunction{subset()} to extract a desired subset of a \Rfunction{DVH.list} object based upon patient identifiers, structure name, and/or dosimetric constraints.
      \item Extended \Rfunction{read.DVH()} function to import Elekta Monaco files.
\end{itemize}
Please refer to NEWS.Rd file for a more extensive revision history.
<<echo=TRUE,results=hide>>=
news(package="RadOnc")
@

\newpage
\section{DVH Analysis}
\label{DVHs}
\subsection{DVH file import}
\label{DVH.import}
The \Rfunction{read.DVH()} function is designed to take an input text file and output a list of DVH data objects containing all relevant data. Supported file types currently include Varian's Aria/Eclipse platform (v.10 and v.11), CadPlan (for archival/historical data), TomoTherapy, RayStation, and Elekta's Monaco platform. Other treatment planning systems are not currently supported however will be included in future releases.

For Varian-specific file types, data must be exported directly from the treatment planning system and should include all DVH structures of interest. In Eclipse, this is accomplished via the ``Export DVH in Tabular Format..." option, accessed by right-clicking over DVHs in Plan Evaluation mode. Exported files will adhere to the following form (an example file, 50 lines of which are shown here, is contained within this release of the \Rpackage{RadOnc} package):

<<echo=FALSE,results=verbatim>>=
temp <- c(readLines(paste(data.path, 'Jane_Doe.dvh', sep='/'),n=50), "...", "...")
for (i in 1:52) {
cat(temp[i], "\n")
}
@

<<echo=FALSE,results=hide>>=
johndoe <- read.DVH(file=system.file("extdata/John_Doe.dvh", package="RadOnc"), type="aria10", verbose=TRUE)
@
This DVH data may be imported using the \Rfunction{read.DVH()} function, with an example shown here:
<<echo=TRUE,eval=FALSE,results=hide>>=
read.DVH(file="Jane_Doe.dvh", type="aria10", verbose=TRUE)
@
<<echo=FALSE,results=verbatim>>=
janedoe <- read.DVH(file=system.file("extdata/Jane_Doe.dvh", package="RadOnc"), type="aria10", verbose=TRUE)
@
\newpage
Multiple files can be imported simultaneously, generating a list of \Rfunction{DVH.list} objects:
<<echo=TRUE,eval=FALSE,results=hide>>=
DVHs <- read.DVH(file=c("Jane_Doe.dvh", "John_Doe.dvh"), type="aria10")
@
<<echo=FALSE,results=verbatim>>=
DVHs <- read.DVH(file=system.file(paste("extdata", c("Jane_Doe.dvh", "John_Doe.dvh"), sep="/"), package="RadOnc"), type="aria10")
DVHs
@

\newpage
\subsection{DVH calculation from dose grid}
\label{DVH.calculate}
Alternatively, \Rfunction{read.DVH(..., type="dicom")} can be employed to extract DVH data from a DICOM-RT dataset including a dose grid (calculated from the treatment planning system) and one or more structure set(s). The DVH import implicitly calls the \Rfunction{calculate.DVH()} function without the user having to manually specify dose calculation, however the \Rfunction{calculate.DVH()} function can also be called explicitly to calculate or recalculate DVHs using specific input parameters (generally the user will not need to call this function explicitly). In any of the above cases, DVH calculation from dose grid data utilizes the method previously described by Straube et al. with trilinear interpolation of dosimetric information \citep{straube}. Please note that this is a computationally intensive process and has not yet been optimized in the current release (future releases will include speed-ups of this dose calculation).

\begin{figure}[H]
\begin{center}
<<label=fig1,fig=TRUE,echo=FALSE>>=
plot(as(janedoe.RTdata$structures,"DVH.list"),lwd=2.5)
plot(janedoe[c(3,6:7)],new=FALSE,col="red",lwd=1.25)
@
\end{center}
\caption{Comparison of DVH data for patient Jane Doe, calculated from dose grid data using the \Rpackage{RadOnc} package (black) or otherwise imported as pre-calculated DVH from the treatment planning system (red).}
\label{fig:one}
\end{figure}


\newpage
\subsection{DVH list manipulation}
\label{DVH.manipulation}
The \Rfunction{read.DVH()} function returns a DVH list that can be manipulated in multiple ways. Subsets of DVH lists can be obtained using the \Rfunction{subset()} function or \Rfunction{[]} modifier, and any number of DVH lists can be combined using the \Rfunction{c()} function. Additionally, single DVH objects can be directly accessed using the \Rfunction{[[]]} modifier, and individual elements of a DVH list may be directly replaced with other DVH objects using the \Rfunction{[[<-} function.
<<echo=TRUE,results=verbatim>>=
janedoe[1:4]
c(janedoe["PTV"], johndoe[c("CTV", "DUODENUM")])
@
<<echo=FALSE,results=hide>>=
temp <- janedoe
@
<<echo=TRUE,results=verbatim>>=
johndoe[["CTV"]]
janedoe[[1]] <- johndoe[["CTV"]]
janedoe[1:4]
@
<<echo=FALSE,results=hide>>=
janedoe <- temp
@

Note that pattern matching (using regular expressions) may also be employed to select a subset of DVH elements from a DVH list:
<<echo=TRUE,results=verbatim>>=
janedoe["KIDNEY$"]
janedoe[c(2,"IGHT.*")]
janedoe["(?i)liver"] ## (case insensitive matching) ##
@

Additionally, the \Rfunction{subset()} function has been extended to support DVH lists. In particular, a user may specify which patient(s) to include (pattern matching is applied to patient names), which structures (pattern matching for structures as described above), and/or which DVHs according to specific dose constraints (e.g. select all structures satisfying a specific parameter):
<<echo=TRUE,results=verbatim>>=
subset(janedoe, structure=c("liver", "kidney"), ignore.case=TRUE)
subset(janedoe, constraint="volume > 200(cc)")
subset(janedoe, constraint="Dmean <= 500(cGy)")
subset(janedoe, constraint="D2cc < 20(Gy)")
@

Other list processing functions may be applied to DVH lists, enabling further data manipulation. The \Rfunction{rev()} function may be used to reverse the order of a DVH list, while the \Rfunction{names()} function may be used to extract (or set) the structure names for each DVH contained within the list. The \Rfunction{length()} function may be used to find the number of DVH objects contained within a DVH list, and the \Rfunction{lapply()} function can be used to perform a customizable set of operations on a DVH list and return a customizable set of values. Here are some examples employing each of these functions:

<<echo=TRUE,results=verbatim>>=
names(janedoe)[1:4] <- c("A1", "B2", "C3", "D4")
names(rev(janedoe[1:4]))
length(johndoe)
lapply(johndoe, function(DVH) { DVH[c("DMIN", "D50%", "DMAX", "V20%")] })
@
<<echo=FALSE,results=hide>>=
janedoe <- temp
@

Patient name(s) and identifier(s) may be extracted from each DVH within the DVH list using the \Rfunction{\$} modifier:
<<echo=TRUE,results=verbatim>>=
janedoe[1:2]$patients
janedoe[3:4]$ID
@

Note: for nested DVH list data generated using \Rfunction{read.DVH(..., collapse=FALSE)} on multiple input files, the \Rfunction{as(.., Class="DVH.list")} command can convert this list to a single DVH.list object.  Subsequent structure processing may then proceed, as above.

\newpage
\subsection{DVH data}
\label{DVH.data}
Each DVH structure contains a variety of data related to the structure itself as well as the distribution of radiation dose within the structure volume. Detailed slot list and parameters are described in the \Rfunction{DVH-class} documentation accompanying the \Rpackage{RadOnc} package. Specific parameters can be extracted using the \Rfunction{[]} modifier, which can take as its argument a character string representation of the desired dose/volume parameter. For instance, the volume of duodenum receiving 20Gy or the dose to the top 2.5\% (2.3286cc) of the volume can be extracted from DVH data as follows:
<<echo=TRUE,results=verbatim>>=
johndoe[["DUODENUM"]]["V20Gy"]
johndoe[["DUODENUM"]]["D2.5%"]
johndoe[["DUODENUM"]]["volume"] * 0.025
johndoe[["DUODENUM"]]["D2.3286cc"]
@
These parameters are entirely flexible and may even specify a summarized range of dosimetric values, for instance \texttt{"V10-20Gy"} specifies the volume of a structure receiving between 10 and 20Gy.  In addition, multiple parameters can be requested for a given DVH object at the same time.  This functionality can also be applied to a DVH list using the \Rfunction{\$} modifier.
<<echo=TRUE,results=verbatim>>=
johndoe[["DUODENUM"]][c("V5%", "V20Gy", "D2.5%", "D2.3286cc", "Dmax")]
johndoe[1:4]$"V10-20Gy,V20Gy,Dmax"
@
Note that specific parameter keywords include: \texttt{"Dmax"} (maximum dose), \texttt{"Dmin"} (minimum dose), \texttt{"Dmean"} (mean dose), \texttt{"Dintegral"} (estimated integral dose), \texttt{"DRx"} (prescription dose), and \texttt{"volume"} (total structure volume). If an improper parameter is specified however, \texttt{NA} results will be returned for the affected parameter(s):
<<echo=TRUE,results=verbatim>>=
johndoe[["DUODENUM"]][c("V5", "VGy", "volume", 2.5, "", "Dmax%")]
@
Parameters may be further modified by \texttt{"()"} tags, which can alter the output format of data in the case of standard dosimetric parameters, for instance:
<<echo=TRUE,results=verbatim>>=
johndoe[["LIVER"]][c("V10Gy(%)","D25%","D25%(Gy)")]
@
Integral dose presents a special case, where additional tags can specify the range over which the integral dose is calculated (default is over the entire dose range).
<<echo=TRUE,results=verbatim>>=
johndoe[["LIVER"]][c("Dintegral","Dintegral(>0cGy)")]
johndoe[["LIVER"]][c("Dintegral(<20Gy)","Dintegral(10-20Gy)")]
@	

\newpage
\subsection{Generalized equivalent uniform dose (gEUD) calculation}
\label{gEUD.calculation}
Generalized equivalent uniform doses (gEUD) can be calculated from one or more \texttt{DVH} or \texttt{DVH.list} objects using the \Rfunction{gEUD()} function.  This calculation summarizes the entire DVH as a single dose which, when distributed evenly thorughout the structure volume, is biologically iso-effective with the heterogeneously distributed dose represented by the DVH \citep{gEUD}. The calculation depends upon a user-specified tissue-specific parameter (\texttt{a}), which can account for behavior of both tumors and normal tissues. This parameter should be negative for target structures (e.g. tumor) and positive for organs at risk. For \texttt{a = 1}, the gEUD is equivalent to mean dose, while for \texttt{a = Inf} and \texttt{a = -Inf}, the gEUD is equivalent to maximum and minimum doses, respectively.

<<echo=TRUE,results=verbatim>>=
gEUD(janedoe[1:3], 6:8)
gEUD(janedoe[1:3], 1) == unlist(janedoe[1:3]$"Dmean")
gEUD(janedoe[1:3], Inf) == unlist(janedoe[1:3]$"Dmax")
gEUD(janedoe[1:3], -Inf) == unlist(janedoe[1:3]$"Dmin")
@

\newpage
\subsection{Linear quadratic extrapolated (LQE) dose conversion}
\label{LQE.conversion}
Linear quadratic extrapolation (LQE) has been used to model iso-effective doses \citep{LQE} and is implemented herein for conversion of and comparison among one or more \Rfunction{DVH} or \Rfunction{DVH.list} objects to account for varying dose fractionation. Two identical DVH curves may in fact represent two widely divergent treatments if, for instance, one patient is treated to 6000cGy in four 1500cGy fractions whereas another is treated to 6000cGy in thirty 200cGy fractions.  In the case below, the \Rfunction{LQE()} function is used to determine the isoeffective doses for 4500, 5500, and 6000cGy when delivered in 200cGy instead of 300cGy daily fractions (20x 300cGy is iso-effective with 36x 200cGy, assuming an alpha/Beta ratio of 3 [\Rfunction{aB = 3}]):
<<echo=TRUE,results=verbatim>>=
LQE(c(4500, 5500, 6000), aB=3, fractions=c(300, 200))
LQE(c(4500, 5500, 6000), aB=3, N=c(20, 36))
@
Note that the \Rfunction{LQE()} function may also be applied to \Rfunction{DVH} or \Rfunction{DVH.list} objects, wherein doses are converted according to specified fractionation and accounting for user-specified alpha/Beta ratio.

\newpage
\subsection{DVH plotting}
\label{dvh.plot}
Individual DVH plots can be generated by the \Rfunction{plot()} function, and may be altered to show dose and/or volume as relative or absolute values with DVH shown as cumulative or differential data.
\begin{figure}[H]
\begin{center}
<<label=fig2,fig=TRUE,echo=TRUE>>=
plot(janedoe[[3]], volume="relative", dose="absolute", type="cumulative")
@
\end{center}
\caption{Standard dose-volume histogram for a single structure (``STOMACH") from patient Jane Doe. Data is shown as cumulative dose versus volume. }
\label{fig:two}
\end{figure}

\newpage
\begin{figure}[H]
\begin{center}
<<label=fig3,fig=TRUE,echo=TRUE>>=
plot(janedoe[1:3], plot.type="i", col=c("red", "green", "blue"), 
legend="topright", legend.labels=names(janedoe[1:3]))
@
\end{center}
\caption{Standard dose-volume histogram for three structures from a single patient, Jane Doe. Data is shown as cumulative dose versus volume. Legend is displayed in the top right corner of the plot. }
\label{fig:three}
\end{figure}

\newpage
\begin{figure}[H]
\begin{center}
<<label=fig4,fig=TRUE,echo=TRUE>>=
plot(c(johndoe["STOMACH"],janedoe["STOMACH"]), #group 1
c(janedoe["LIVER"],johndoe["LIVER"]), #group 2
c(johndoe["DUODENUM"],janedoe["DUODENUM"]), #group 3
plot.type="g", dose="relative", col=c("blue", "red", "green"), 
lwd=2, lty="dashed", fill.lty="solid", fill.transparency=0.3)
@
\end{center}
\caption{Mean dose-volume histograms are shown for three groups of DVHs, in this case corresponding to stomach, liver, and duodenum from two different patients (John Doe and Jane Doe). Data is shown as cumulative dose (relative) versus volume (relative). Shading represents the range of the data for each group (note that the width of the shading can be specified to represent other parameters instead of range -- e.g. variance, standard deviation, interquartile range, median absolute deviation). }
\label{fig:four}
\end{figure}

\newpage
\begin{figure}[H]
\begin{center}
<<label=fig5,fig=TRUE,echo=TRUE>>=
group1 <- c("CTV", "PTV")
group2 <- c("LIVER", "STOMACH", "SMALL_BOWEL")
plot(c(johndoe[group1],janedoe[group1]), 
c(janedoe[group2],johndoe[group2]),
plot.type="t", main="Target v. OAR t-Test", alpha=0.001, 
col=c("red", "blue"), lty="dashed", fill.lty="solid")
@
\end{center}
\caption{Mean dose-volume histograms are shown for two groups of DVHs, in this case corresponding to CTV/PTV and liver/stomach/small bowel from two different patients (John Doe and Jane Doe). Data is shown as cumulative dose (absolute) versus volume (relative). Shading represents the 99.9\% confidence interval for each group (specified here by \Rfunction{alpha=0.001}). The corresponding p-values are shown in the upper panel, with corresponding significance threshold p<0.001. }
\label{fig:five}
\end{figure}

\newpage
\begin{figure}[H]
\begin{center}
<<label=fig6,fig=TRUE,echo=TRUE>>=
plot(janedoe[2:9], plot.type="b", volume="abs", dose="rel")
@
\end{center}
\caption{Bar representation of dose distributions for eight structures from a single patient (Jane Doe). }
\label{fig:six}
\end{figure}

\newpage
\subsection{DVH statistics}
\label{DVH.stats}
Mean or median DVHs can be calculated using the \Rfunction{mean()} and \Rfunction{median()} functions, respectively. These functions take a DVH list as input and return a single object of class \Rfunction{DVH} representing the mean or median dose-volume histogram data calculated from the entire group.
\begin{figure}[H]
\begin{center}
<<label=fig8,fig=TRUE,echo=TRUE>>=
plot(janedoe)
plot(median(janedoe), new=FALSE, col="red", lwd=2)
plot(mean(janedoe), new=FALSE, col="blue", lwd=2, lty="dashed")
@
\end{center}
\caption{Mean and median DVHs are shown in blue dash and red, respectively. }
\label{fig:eight}
\end{figure}

\newpage
Similarly, DVH list summation can be performed for two or more *non-overlapping* structures (e.g. bilateral lungs or kidneys) using the \Rfunction{sum()} function.
<<echo=FALSE,eval=TRUE,results=hide>>=
L.kidney <- janedoe[["LEFT_KIDNEY"]]
R.kidney <- janedoe[["RIGHT_KIDNEY"]]
total.kidney <- sum(janedoe[c("LEFT_KIDNEY", "RIGHT_KIDNEY")])
@
<<echo=TRUE,eval=FALSE>>=
L.kidney <- janedoe[["LEFT_KIDNEY"]]
R.kidney <- janedoe[["RIGHT_KIDNEY"]]
total.kidney <- sum(janedoe[c("LEFT_KIDNEY", "RIGHT_KIDNEY")])
plot(total.kidney, type="diff", volume="abs")
plot(L.kidney, new=FALSE, type="diff", volume="abs", col="red")
plot(R.kidney, new=FALSE, type="diff", volume="abs", col="blue")
@
\begin{figure}[H]
\begin{center}
<<label=fig9,fig=TRUE,echo=FALSE>>=
plot(total.kidney, type="diff", volume="abs")
plot(L.kidney, new=FALSE, type="diff", volume="abs", col="red")
plot(R.kidney, new=FALSE, type="diff", volume="abs", col="blue")
@
\end{center}
\caption{Plot of total kidney dose, calculated using \Rfunction{sum()} function. Left and right kidney doses are shown in red and blue, respectively. }
\label{fig:nine}
\end{figure}

\newpage
In routine clinical practice and research, DVH comparisons are often performed at an individual parameter level (e.g. V20Gy from Group A compared to Group B). The \Rpackage{RadOnc} package enables automated comparison throughout the entire DVH. Functions such as \Rfunction{t.test()} and \Rfunction{wilcox.test()} are both enabled for DVH lists.
<<echo=TRUE,results=verbatim>>=
groupA <- janedoe[c("LIVER","LEFT_KIDNEY","RIGHT_KIDNEY","CORD")]
groupB <- janedoe[c("CTV", "PTV")]
t.test(unlist(groupA$"V20Gy"), unlist(groupB$"V20Gy"))
@
\newpage
\begin{figure}[H]
\begin{center}
<<echo=TRUE,eval=FALSE>>=
AvB <- t.test(groupA, groupB)
plot(AvB$dose, AvB$p, type="l", log="y", xlab="Dose (cGy)", ylab="p-value")
@
<<label=fig10,fig=TRUE,echo=FALSE>>=
AvB <- t.test(groupA, groupB)
plot(AvB$dose, AvB$p, type="l", log="y", xlab="Dose (cGy)", ylab="p-value")
abline(v=2000,col="gray", lty="dashed")
points(2000,approx(AvB$dose, AvB$p, 2000)$y, col="red")
text(2000,approx(AvB$dose, AvB$p, 2000)$y, col="red", labels="V20Gy (p=5.347e-05)",pos=4)
@
\end{center}
\caption{p-values from \Rfunction{t.test()} comparison as a function of dose. V20Gy is highlighted and its p-value corresponds closely to values generated from t-test of V20Gy directly. }
\label{fig:ten}
\end{figure}


\newpage
\section{Three-Dimensional Structure Analysis}
\label{3Dstructs}
\subsection{DICOM-RT import}
\label{DICOMRT.import}
The \Rfunction{read.DICOM.RT()} function is designed to take input DICOM-RT file(s) and output a list of \Rfunction{structure3D} data objects containing all relevant data, in particular the axially-defined contours delineating each structure. Note that DICOM-RT file import was evaluated using Varian's Aria/Eclipse platform (v.10 and v.11). Other treatment planning systems may encode 3D structural information in a different format and this has not been evaluated in the current release of software.

For DICOM-RT data, the associated CT scan must be exported directly from the treatment planning system and should include all contoured structures of interest. In Eclipse, this can be accomplished via the ``Export Wizard..." option in the ``File" menu, accessed in either Countouring or Plan Evaluation modes. Note that the ``Include structure set" option should be selected, and that Institution-specific filters will be required for proper data export. DICOM-RT data will consist of multiple files representing both the CT image as well as the relevant structure set(s).

DICOM-RT data may be imported using the \Rfunction{read.DICOM.RT()} function, with a mockup example shown here (note that ``DICOM directory" should be replaced by the path to a specific directory containing the desired DICOM data):
<<echo=TRUE,eval=FALSE,results=hide>>=
data <- read.DICOM.RT(path="<<DICOM directory>>", verbose=TRUE)
@

The DICOM-RT import process may take some time.  We have included pre-loaded data for a single patient (included structures: spinal cord, mandible, teeth) which will be explored in this vignette.
<<echo=FALSE,eval=TRUE>>=
data("RadOnc")
@

\newpage
\subsection{3D structure manipulation}
\label{3D.manip}
The \Rfunction{read.DICOM.RT()} function returns a \Rfunction{structure.list} object that can be manipulated in multiple ways. Subsets of structure lists can be obtained using the \Rfunction{[]} modifier, and any number of structure lists can be combined using the \Rfunction{c()} function. Additionally, single \Rfunction{structure3D} objects can be directly accessed using the \Rfunction{[[]]} modifier, and individual elements of a structure list may be directly replaced with other \Rfunction{structure3D} objects using the \Rfunction{[[<-} function.
<<echo=TRUE,results=verbatim>>=
teeth[1:2]
c(cord, mandible)
@
<<echo=FALSE,results=hide>>=
temp <- teeth
@
<<echo=TRUE,results=verbatim>>=
teeth[[1]]
teeth[[1]] <- teeth[["Tooth #3"]]
teeth
@
<<echo=FALSE,results=hide>>=
teeth <- temp
@

As with \Rfunction{DVH.list} objects, \Rfunction{structure.list} objects may be subsetted by pattern matching:
<<echo=TRUE,results=verbatim>>=
teeth["Tooth.*"]
@

Other list processing functions may be applied to structure lists, enabling further data manipulation. The \Rfunction{rev()} function may be used to reverse the order of a structure list, while the \Rfunction{names()} function may be used to extract (or set) the structure names for each structure contained within the list. The \Rfunction{length()} function may be used to find the number of structures contained within a structure list, and the \Rfunction{lapply()} function can be used to perform a customizable set of operations on a structure list and return a customizable set of values. Here are some examples employing each of these functions:

<<echo=TRUE,results=verbatim>>=
names(teeth) <- c("Larry", "Curly", "Moe")
names(rev(teeth[1:3]))
length(teeth)
lapply(teeth, function(tooth) { range(tooth) })
@
<<echo=FALSE,results=hide>>=
teeth <- temp
@

\newpage
\subsection{Plotting 3D structures}
\label{3D.plot}
Three dimensional surfaces renderings can be generated by the \Rfunction{plot()} function. The \Rpackage{RadOnc} package does not currently contain the functionality to generate surface triangulations for a given structure, however future releases of the package will implement surface triangulation. Thus, data imported using \Rfunction{read.DICOM.RT()} will not currently be processed for surface triangulation and will generate an empty plot if plotting is attempted. External applications such as MeshLab \citep{MeshLab} can be used to generate triangulations which, for advanced users, can be imported into a given \Rfunction{structure3D} object.
\begin{figure}[H]
\begin{center}
<<label=fig11,fig=FALSE,echo=TRUE,eval=FALSE>>=
plot(mandible)
@
\includegraphics{mandible.png}
\end{center}
\caption{Three-dimensional surface reconstruction from triangulation of physician-contoured points for the mandible of a patient. }
\label{fig:eleven}
\end{figure}

\newpage
\begin{figure}[H]
\begin{center}
<<label=fig12,fig=FALSE,echo=TRUE,eval=FALSE>>=
plot(cord)
@
\includegraphics{cord.png}
\end{center}
\caption{Three-dimensional surface reconstruction from triangulation of physician-contoured points for the spinal cord of a patient. }
\label{fig:twelve}
\end{figure}


\newpage
\subsection{Structure comparison}
\label{compare.structures}
\setkeys{Gin}{width=0.2\textwidth}
Comparison of three-dimensional structures has numerous applications.  In the case presented here, three physicians separately delineated a tooth on axial slices of a CT for a single patient.  Variability among physician contours is demonstrated using the \Rfunction{compareStructures()} function:
\begin{figure}[H]
\begin{center}
<<echo=TRUE,eval=FALSE>>=
compareStructures(teeth, method="axial", plot=TRUE)
@
<<label=fig13,fig=TRUE,echo=FALSE,results=hide,height=10,width=2>>=
compareStructures(teeth, method="axial", plot=TRUE, pixels=40)
@
\end{center}
\caption{Axial comparison of overlap among three separate physician-defined contours for a single tooth. Red (and white) regions delineate consensus while decreasing degree of overlap is shown in decreasing shades of orange and yellow. }
\label{fig:thirteen}
\end{figure}

\newpage
Structure comparison may also be performed by Hausdorff distance \citep{hausdorff}, which computes the distance between two points clouds, in this case structure surfaces. The absolute Hausdorff distance  (\Rfunction{hausdorff.method="absolute"}) yields the maximum distance required to connect any point from one point cloud to its closest neighbor in the other. This metric is highly subject to outliers, thus an aggregate metric is implemented by selecting the average distance (\Rfunction{hausdorff.method="mean"} or  \Rfunction{hausdorff.method="median"}) required to connect all points in one point cloud to their closest neighboring points in the other. Note that the Hausdorff distance between two completely superimposable point clouds is zero.
<<echo=FALSE,results=hide>>=
teeth <- teeth[c(1,3)]
@
<<echo=TRUE,results=verbatim>>=
compareStructures(teeth, method="hausdorff", hausdorff.method="mean")
@
<<echo=FALSE,results=hide>>=
teeth <- temp
@

Pairwise Dice similarity coefficients (DSC) may also be calculated \citep{DSC}:
<<echo=TRUE,results=verbatim>>=
compareStructures(teeth, method="DSC")
@


\newpage
\addcontentsline{toc}{section}{References}
\bibliographystyle{unsrtnat}
\bibliography{RadOnc}


\newpage
\appendix
\section{Acknowledgements}
\label{acknowledgements}
Many thanks to Brandon Whitcher for his phenomenal and generous support regarding the \Rpackage{oro.dicom} pacakge, and to Daniel Wollschlaeger for his insights and contributions regarding DVH file formatting, dose unit interconversion, and inclusion of CadPlan data. Thank you to Francis Gibbons, Usman Lula, Michael Young, and Lukasz Matulewicz for their contributions regarding inclusion of Elekta, RayStation, and TomoTherapy-formatted data. Thank you to Maura Kirk, Eric Ojerholm, and Abodunde Adegunloye for their help in identifying software bugs and suggesting additional package features.

\section{Previous Release Notes}
\label{previous}
\begin{itemize}
\item Initial release (v1.0.0) on 2013-07-07
\item Subsequent release (v1.0.1) on 2013-10-23
\item Subsequent release (v1.0.2) on 2013-11-25
\item Subsequent release (v1.0.3) on 2014-01-17
\item Subsequent release (v1.0.4) on 2014-01-31
\item Subsequent release (v1.0.5) on 2014-02-19
\item Subsequent release (v1.0.6) on 2014-02-20
\item Subsequent release (v1.0.7) on 2014-02-27
\item Subsequent release (v1.0.8) on 2014-05-31
\item Subsequent release (v1.0.9) on 2014-11-22
\item Subsequent release (v1.1.0) on 2015-04-22
\item Last release (v1.1.1) on 2016-01-13
\end{itemize}
Please refer to NEWS.Rd file for more details.
<<echo=TRUE,results=hide>>=
news(package="RadOnc")
@

\end{document}