\HeaderA{WLR.flowcytest}{Weighted Logrank Test for testing the differences between
time-to-event, survival curves}{WLR.flowcytest}
\aliasA{WLR}{WLR.flowcytest}{WLR}
\keyword{survival}{WLR.flowcytest}
\keyword{univar}{WLR.flowcytest}
\keyword{hplot}{WLR.flowcytest}
\begin{Description}\relax
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.
\end{Description}
\begin{Usage}
\begin{verbatim}
WLR.flowcytest(controldata, stimuldata, title = "", varname = "",
               na.action.WLR = options()$na.action, rho.test = 0,
               WLR.plotted=TRUE, MY.DEBUG=TRUE)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{controldata}] numerical vector of observations of the control
data for one variable

\item[\code{stimuldata}] numerical vector of observations of the stimulated
data for the same variable as the control

\item[\code{title}] character string describing the title

\item[\code{varname}] character string describing the name of the variable

\item[\code{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[\code{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[\code{WLR.plotted}] boolean; if TRUE, then plot is made; otherwise if
FALSE, plotting is surpressed; default=TRUE
\item[\code{MY.DEBUG}] boolean; if TRUE, the test is printed out with
comments; if FALSE then these comments are surpressed
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
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.
\end{Details}
\begin{Value}
\begin{ldescription}
\item[\code{p.val.1sid.chisq.WLR}] p-value associated with a chi-squared
statistic with one degree of freedom

\item[\code{chisq.WLR}] the chi-squared statistic in the test of the
difference in survival curves

\item[\code{n.WLR}] a numeric vector of the number of subjects in the
control and the stimulated samples, respectively

\item[\code{obs.WLR}] numeric vector of the weighted observed number of
events in each sample, control and stimulated, respectively

\item[\code{exp.WLR}] numeric vector of the weighted expected number of
events in each sample, control and stimulated, respectively

\item[\code{var.WLR}] the variance matrix of the test (control, stimulated)

\end{ldescription}


A survival plot is also made with the two survival curves, labeled
"Control" and "Stimulated" and super-imposed on one plot.
\end{Value}
\begin{Section}{WARNING}
Usually the FCS object is gated and subset prior to
this testing and analysis.  Also this function requires the
library \code{survival}.
\end{Section}
\begin{Note}\relax
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.
\end{Note}
\begin{Author}\relax
A.J. Rossini and J.Y. Wan
\end{Author}
\begin{References}\relax
Harrington, D. P. and Fleming, T. R. (1982). A class of rank test
procedures for censored survival data. Biometrika 69, 553-566.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{pkci2.flowcytest}{pkci2.flowcytest}},
\code{\LinkA{ProbBin.flowcytest}{ProbBin.flowcytest}}, \code{\LinkA{KS.flowcytest}{KS.flowcytest}},
\code{\LinkA{runflowcytests}{runflowcytests}}, 
the function 'survdiff' in the \pkg{survival} package.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}

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.
}
\end{ExampleCode}
\end{Examples}

