\name{WLR.flowcytest}
\alias{WLR.flowcytest}
\alias{WLR}
%- Also NEED an `\alias' for EACH other topic documented here.
\title{Weighted Logrank Test for testing the differences between
  time-to-event, survival curves
}
\description{
  Using a survival method developed by Flemming and Harrington, this
  function examines the difference in the survival curves of two samples
  in order to determine a distribution difference between the two
  samples. A plot of the two super-imposed survival curves is displayed.
  
}
\usage{
WLR.flowcytest(controldata, stimuldata, title = "", varname = "",
               na.action.WLR = options()$na.action, rho.test = 0,
               WLR.plotted=TRUE, MY.DEBUG=TRUE)
}
%- maybe also `usage' for other objects documented here.
\arguments{
  \item{controldata}{numerical vector of observations of the control
    data for one variable
  }
  \item{stimuldata}{numerical vector of observations of the stimulated
    data for the same variable as the control
  }
  \item{title}{character string describing the title
  }
  \item{varname}{character string describing the name of the variable
  }
  \item{na.action.WLR}{a missing-data filter function.  This is applied to the
    'model.frame' after any subset argument has been used. 
    Default is 'options()\$na.action' (as quoted from the
    'survdiff' documentation from the \pkg{survival} package.)
  }
  \item{rho.test}{the exponent, $\rho$ in $S(t)^\rho$, where S is the
    Kaplan-Meier estimate of survival; A $\rho$ value of 0 specifies using the
    weighted log-rank test, and a value of 1 specifies using the Peto &
    Peto modification of the Gehan-Wilcoxon test.
  }
  \item{WLR.plotted}{boolean; if TRUE, then plot is made; otherwise if
    FALSE, plotting is surpressed; default=TRUE}
  
  \item{MY.DEBUG}{boolean; if TRUE, the test is printed out with
    comments; if FALSE then these comments are surpressed}
}
\details{
  The null hypothesis is that the two survival curves are the same
  in both samples.  If there is a significant difference then a large
  chi-squared one statistic corresponding to a small
  p-value (usually $<$ 0.05, where the Type I error rate=alpha=0.05)
  will suggest this significance.
  
  This function uses 'survdiff' in the \pkg{survival} package.
  The following is a direct quote from the 'survdiff' documentation:
  "This function (survdiff) implements the G-rho family of Harrington and
  Fleming (1982), with weights on each death of $S(t)^\rho$, where S is
  the Kaplan-Meier estimate of survival.With `$\rho = 0$' this is the
  log-rank or Mantel-Haenszel test, and with `$\rho = 1$' it is
  equivalent to the Peto & Peto modification of the Gehan-Wilcoxon
  test."

  In this flowcytometry analysis, we are not dealing with the
  proportion of survival, persay, but instead in terms of the
  proportion of observations/cells beyond a certain value of the
  interferon gamma variable.
}
\value{
  \item{p.val.1sid.chisq.WLR}{p-value associated with a chi-squared
    statistic with one degree of freedom
  }
  \item{chisq.WLR}{the chi-squared statistic in the test of the
    difference in survival curves
  }
  \item{n.WLR}{a numeric vector of the number of subjects in the
    control and the stimulated samples, respectively
  }
  \item{obs.WLR}{numeric vector of the weighted observed number of
    events in each sample, control and stimulated, respectively
  }
  \item{exp.WLR}{numeric vector of the weighted expected number of
    events in each sample, control and stimulated, respectively
  }
  \item{var.WLR}{the variance matrix of the test (control, stimulated)
  }
  
  A survival plot is also made with the two survival curves, labeled
  "Control" and "Stimulated" and super-imposed on one plot.
}
\references{
  Harrington, D. P. and Fleming, T. R. (1982). A class of rank test
  procedures for censored survival data. Biometrika 69, 553-566.
}
\author{A.J. Rossini and J.Y. Wan}

\note{
  Other flowcytests are available such as \code{pkci2.flowcytest},
  \code{ProbBin.flowcytest}, \code{KS.flowcytest}, which test the
  equivalence of two sample distributions. Generally, comparing the control and
  stimulated samples of the interferon gamma variable is of interest.
}

\section{WARNING}{Usually the FCS object is gated and subset prior to
  this testing and analysis.  Also this function requires the
  library \code{survival}.
}

\seealso{ \code{\link{pkci2.flowcytest}},
  \code{\link{ProbBin.flowcytest}}, \code{\link{KS.flowcytest}},
  \code{\link{runflowcytests}}, 
  the function 'survdiff' in the \pkg{survival} package.
}

\examples{

if (require(rfcdmin)){

data.there<-is.element(c("st.1829", "unst.1829", "st.DRT", "unst.DRT"),objects())
if ( ( sum(data.there) != length(data.there) )){
## obtaining the FCS objects from VRC data
data(VRCmin)
}

## This only serves as an example.  Usually the FCS object is
## gated and then subset

## HIV negative individual 1829
  IFN.control<-unst.1829@data[1:2000,4]
  IFN.stimul<-st.1829@data[1:2000,4]



if (interactive()==TRUE){
par(mfrow=c(2,2))
WLR.flowcytest(IFN.control, IFN.stimul,
title="HIV negative individual 1829",
varname="Interferon Gamma")
}
## HIV positive individual DRT
  IFN.control2<-unst.DRT@data[1:2000,4]
  IFN.stimul2<-st.DRT@data[1:2000,4]

if (interactive()==TRUE){
WLR.flowcytest(IFN.control2, IFN.stimul2,
title="HIV positive individual DRT",
varname="Interferon Gamma")
}
## This is an artifical example, but one would expect the
## distributions of the stimulated and control samples
## to be the same in the HIV negative individual 1829
## and to be different in the HIV positive individual DRT
## The test in this example is a bit contrived but
## the bigger picture is achieved.
}
}

\keyword{survival}% at least one, from doc/KEYWORDS
\keyword{univar}
\keyword{hplot}