\name{survplot}
\alias{survplot}
\title{ Draw augmented K-M survival curves  }
\description{ Plot Kaplan-Meier survival curves, automatically generate a key for each strata, and calculate and display hazard ratio if there are exactly two strata.  Optionally, indicate the number-at-risk below the main plot.}
\usage{
survplot(x, data = NULL, subset = NULL, 
         snames, stitle, 
         col, lty, lwd,
         show.nrisk = TRUE, color.nrisk = TRUE,
         hr.pos = 'topright', legend.pos = 'bottomleft', ...)
}
\arguments{
  \item{x}{ A formula, as would be appropriate for \code{\link[survival]{survfit}} and \code{\link[survival]{coxph}}. }
  \item{data, subset}{ Arguments passed to \code{\link[survival]{survfit}} and \code{\link[survival]{coxph}}. }
  \item{snames}{ Names for each stratum, to be used in the legend. If missing, these are inferred from the data. }
  \item{stitle}{ Title for the strata legend. If missing, this is inferred from \code{x}. }
  \item{col, lty, lwd}{ Colors, line type, and line width for each stratum (optional).  }
  \item{show.nrisk}{ Indicate the number-at-risk for each stratum below the plot? }
  \item{color.nrisk}{ Color the number-at-risk to match the plot? }
  \item{hr.pos}{ Where to put the hazard ratio information, or NA to omit (see \code{\link{legend}}) }
  \item{legend.pos}{ Where to put the legend, or NA to omit (see \code{\link{legend}}) }
  \item{\dots}{ Further parameters sent to \code{\link[survival]{plot.survfit}}. }
}
\details{
This function was written and documented by Aron Charles Eklund in his package
survplot version 0.0.7.

Hazard ratio (and 95\% confidence intervals) and logrank P are calculated and displayed if there are exactly two groups. 

If there is exactly one group (no stratification), the legend is omitted.
}
\value{ If there are exactly two groups, a character vector with the HR and P value is returned invisibly. }
\author{Aron Charles Eklund (survplot version 0.0.7)}
\note{ The lower figure margin is increased if the number-at-risk is displayed. }
\seealso{ \code{\link{nrisk}} }
\examples{ 
library(survival)
surv <- Surv(colon$time / 365, colon$status)

survplot(surv ~ rx,
  data = colon,
  lty = 1:3, 
  main = 'Patients stratified by treatment', 
  xlab = 'Time (Years)')

survplot(surv ~ colon$sex, 
  main = 'Patients stratified by sex', 
  xlab = 'Time (Years)',
  snames = c('F', 'M'),
  stitle = 'Gender')

survplot(surv ~ sex, 
  data = colon, 
  subset = colon$surg == 1)

## Example without stratification
survplot(surv ~ 1, data = colon)
  
}
\keyword{ survival }
\keyword{ hplot }