\name{plot_boxkm}

\alias{plot_boxkm}

\title{Visualization of Survival Distributions}

\description{
  Function for plotting the cross-validated survival distributions of a \code{PRSP} object. 
  Plot the cross-validated Kaplan-Meir estimates of survival distributions for the highest risk (inbox) versus
  lower-risk (outbox) groups of samples at each iteration of the peeling sequence (inner loop of our PRSP algorithm).
}

\usage{
  plot_boxkm(object,
             main = NULL, 
             xlab = "Time", 
             ylab = "Probability",
             precision = 1e-3, 
             mark = 3, 
             col = 2, 
             cex = 1,
             steps = 1:object$cvfit$cv.nsteps,
             nr = 3, 
             nc = 4,
             device = NULL, 
             file = "Survival Plots", 
             path=getwd(), 
             horizontal = TRUE, 
             width = 11.5, 
             height = 8.5, ...)
}

\arguments{
  \item{object}{
    Object of class \code{PRSP} as generated by the main function \code{\link[PRIMsrc]{sbh}}.
  }
  \item{main}{
    \code{Character} \code{vector}. Main Title. Defaults to \code{NULL}.
  }
  \item{xlab}{
    \code{Character} \code{vector}. X axis label. Defaults to "Time".
  }
  \item{ylab}{
    \code{Character} \code{vector}. Y axis label. Defaults to "Probability".
  }
  \item{precision}{
    Precision of cross-validated log-rank p-values of separation between two survival curves.
    Defaults to 1e-3.
  }
  \item{mark}{
    \code{Integer} scalar of mark parameter, which will be used to label the inbox and out-of-box curves. 
    Defaults to 3.
  }
  \item{col}{
    \code{Integer} scalar specifying the color of the inbox curve. 
    Defaults to 2.
  }
  \item{cex}{
    \code{Numeric} scalar specifying the size of the marks. 
    Defaults to 1.
  }
  \item{steps}{
    \code{Integer} \code{vector}. Vector of peeling steps at which to plot the survival curves. 
    Defaults to all the peeling steps of \code{PRSP} object \code{object}.
  }
  \item{nr}{
    \code{Integer} scalar of the number of rows in the plot. 
    Defaults to 3.
  }
  \item{nc}{
    \code{Integer} scalar of the number of columns in the plot. 
    Defaults to 4.
  }
  \item{device}{
    Graphic display device in \{NULL, "PS", "PDF"\}. Defaults to NULL (standard output screen).
    Currently implemented graphic display devices are "PS" (Postscript) or "PDF" (Portable Document Format).
  }
  \item{file}{
    File name for output graphic. Defaults to "Survival Plots".
  }
  \item{path}{
    Absolute path (without final (back)slash separator). Defaults to the working directory path.
  }
  \item{horizontal}{
    \code{Logical} scalar. Orientation of the printed image. Defaults to \code{TRUE}, that is potrait orientation.
  }
  \item{width}{
    \code{Numeric} scalar. Width of the graphics region in inches. Defaults to 11.5.
  }
  \item{height}{
    \code{Numeric} scalar. Height of the graphics region in inches. Defaults to 8.5.
  }
  \item{\dots}{
    Generic arguments passed to other plotting functions, including \code{plot.survfit} (R package \pkg{survival}).
  }
}

\details{
  Some of the plotting parameters are further defined in the function \code{plot.survfit} (R package \pkg{survival}).
  Step #0 always corresponds to the situation where the starting box covers the entire test-set data before peeling.
  Cross-validated LRT, LHR of inbox samples and log-rank p-values of separation are shown at the bottom of the plot
  with the corresponding peeling step. P-values are lower-bounded by the precision limit given by \eqn{1/A}, 
  where \eqn{A} is the number of permutations.
}

\value{
  Invisible. None. Displays the plot(s) on the specified \code{device}.
}

\references{
    \itemize{
        \item Dazard J-E., Choe M., LeBlanc M. and Rao J.S. (2015).
              "\emph{Cross-validation and Peeling Strategies for Survival Bump Hunting using Recursive Peeling Methods.}"
              (Submitted).
        \item Dazard J-E., Choe M., LeBlanc M. and Rao J.S. (2014).
              "\emph{Cross-Validation of Survival Bump Hunting by Recursive Peeling Methods.}"
              In JSM Proceedings, Survival Methods for Risk Estimation/Prediction Section. Boston, MA, USA.
              American Statistical Association IMS - JSM, p. 3366-3380.
        \item Dazard J-E. and J. S. Rao (2010).
              "\emph{Local Sparse Bump Hunting.}"
              J. Comp Graph. Statistics, 19(4):900-92.
    }
}

\author{
    \itemize{
        \item "Jean-Eudes Dazard, Ph.D." \email{jxd101@case.edu}
        \item "Michael Choe, M.D." \email{mjc206@case.edu}
        \item "Michael LeBlanc, Ph.D." \email{mleblanc@fhcrc.org}
        \item "Alberto Santana, MBA." \email{ahs4@case.edu}
    }
    Maintainer: "Jean-Eudes Dazard, Ph.D." \email{jxd101@case.edu}

    Acknowledgments: This project was partially funded by the National Institutes of Health
    NIH - National Cancer Institute (R01-CA160593) to J-E. Dazard and J.S. Rao.
}

\note{
  End-user plotting function.
}

\keyword{Exploratory Survival/Risk Analysis}
\keyword{Survival/Risk Estimation & Prediction}
\keyword{Non-Parametric Method}
\keyword{Cross-Validation}
\keyword{Bump Hunting}
\keyword{Rule-Induction Method}

\seealso{
    \itemize{
        \item \code{plot.survfit} (R package \pkg{survival})
    }
}

\examples{
#===================================================
# Loading the library and its dependencies
#===================================================
library("PRIMsrc")

#=================================================================================
# Simulated dataset #1 (n=250, p=3)
# Replicated Combined Cross-Validation (RCCV)
# Peeling criterion = LRT
# Optimization criterion = LRT
#=================================================================================
CVCOMBREP.synt1 <- sbh(dataset = Synthetic.1, 
                       cvtype = "combined", cvcriterion = "lrt",
                       B = 1, K = 5, 
                       vs = TRUE, cpv = FALSE, probval = 0.5, 
                       arg = "beta=0.05,
                              alpha=0.1,
                              minn=10,
                              L=NULL,
                              peelcriterion=\"lr\"",
                       parallel = FALSE, conf = NULL, seed = 123)

plot_boxkm(object = CVCOMBREP.synt1,
           main = paste("RCCV probability curves for model #1", sep=""),
           xlab = "Time", ylab = "Probability",
           device = NULL, file = "Survival Plots", path=getwd(),
               horizontal = TRUE, width = 11.5, height = 8.5)
}
