\HeaderA{runflowcytests}{Tests the equivalence of two univariate sample distributions by
using four different methods}{runflowcytests}
\keyword{univar}{runflowcytests}
\keyword{dplot}{runflowcytests}
\keyword{hplot}{runflowcytests}
\begin{Description}\relax
Runs the following flowcytests:

\item[1. \code{WLR.flowcytest}] weighted log rank test (by default
when rho=0) and a the plot of survival curves for both samples
is also output
\item[2. \code{KS.flowcytest}] Kolmogorov-Smirnoff test for
the difference in distributions for the control and the
stimulated
\item[3. \code{ProbBin.flowcytest}] Statistics proposed by
Keith A. Baggerly and Mario Roederer which include Chi-squared
and Normal tests for the PB metric via probability binning (both
based on the control data only ("by.control") and based on the
combined dataset of both the stimulated and the control samples
("combined")
\item[4. \code{pkci2.flowcytest}] Tests the difference of the upper
tails of the two distributions
\end{Description}
\begin{Usage}
\begin{verbatim}
runflowcytests(controldata, stimuldata, flowcytests = c("WLR", "KS",
                 "ProbBin.by.control", "ProbBin.combined", "pkci2"),
                 N.in.bin = 100, varname = "", title = " ", output.all
                 = FALSE, graph.outlay = c(3, 2), crit.pkci2 = 0.999,
                 alpha.pkci2 = 0.05, na.action.WLR =
                 options()$na.action, rho.WLR = 0, WLR.plotted=TRUE, alternative.KS =
                 "two.sided", ..., KS.plotted=TRUE,
                           PBobj.plotted=TRUE,
                PBobj.plots.made=c("both", "stimulated", "unstimulated"))
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{controldata}] a vector of values/fluoroescent measurements; a univariate
control sample
\item[\code{stimuldata}] a vector of values/fluoroescent measurements; a univariate
stimulated sample
\item[\code{flowcytests}] vector denoting the names of the tests that are
implemented; default is a vector of all the test names
\item[\code{N.in.bin}] a number which denotes the number per bin in used in
probability binning
\item[\code{varname}] character strong of the name of the variable under
investigation (this is usually the gamma interferon variable)
\item[\code{title}] character string of the title of the plots
\item[\code{output.all}] boolean; if TRUE then all the statistics and
p-values obtained are output in list form by test; if FALSE then only the
names of the statistics, the statistics, the names of the p-values
and the p-values are output in a data.frame; default is FALSE.
\item[\code{graph.outlay}] a vector of length 2, describing the number of
graphs on each row and the number of graphs on each column,
respectively
\item[\code{crit.pkci2}] the percent of control sample to above the
meaningful percentile (usually 99.9th percentile) (for
pkci2.flowcytest)
\item[\code{alpha.pkci2}] Type I error rate for construction of the
(1-alpha)\% Confidence Interval (for pkci2.flowcytest)
\item[\code{na.action.WLR}] a missing-data filter function.  This is applied to the
\code{model.frame} after any subset argument has been used. 
Default is \code{options()\$na.action} (as quoted from the
\code{survdiff} documentation)
\item[\code{rho.WLR}] the exponent in $S(t)^\rho$, where S is the
Kaplan-Meier estimate of survival; A value of 0 specifies using the
weighted log-rank test, and a value of 1 specifies using the Peto
and 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{alternative.KS}] character string of the alternative hypothesis:
\item["two-sided"] Two sided alternative hypoothesis
\item["less"] One-sided alternative hypothesis: controldata
distribution is less than the stimuldata distribution
\item["greater"] One-sided alternative hypothesis: controldata
distribution is greater than the stimuldata distribution

\item[\code{...}] other options in \code{KS.flowcytest}
\item[\code{KS.plotted}] boolean to display the corresponding plot; default
is TRUE and the plot will be displayed
\item[\code{PBobj.plotted}] boolean; if TRUE then histograms of the
ProbBin.FCS object will be plotted; if FALSE, then these plots are
surpressed; default is TRUE
\item[\code{PBobj.plots.made}] character string denoting which histogram plot should be 
displayed; default is "both"
\end{ldescription}
\end{Arguments}
\begin{Value}
A dataframe consisting of 4 columns and 20 rows.  The labels on the
columns are "statistics.names", "statistics", "pvalues.names", and
"pvalues" or if 'output.all' is TRUE, a list of statistics and tesing
output by test name will be produced. Also 6 to 0 plots are produced.
\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
For more information about the output, please see the other
flowcytests in the "See Also" Section.
\end{Note}
\begin{Author}\relax
Zoe Moodie, A.J. Rossini, J.Y. Wan
\end{Author}
\begin{References}\relax
Keith A. Baggerly "Probability Binning and Test Agreement
between Multivariate Immunofluorescence Histograms: Extending the
Chi-Squared test" Cytometry 45: 141:150 (2001).

Harrington, D. P. and Fleming, T. R. (1982). "A class of rank test
procedures for censored survival data". Biometrika 69, 553-566.

Zoe Moodie, PhD
Statistical Center for HIV/AIDS Research and Prevention (SCHARP) 
Fred Hutchison Cancer Research Center
Seattle, WA 98109-1024

Mario Roederer, et al. "Probability Binning Comparison: A
Metric for Quantitating Univariate Distribution Differences" Cytometry
45:37-46 (2001).
\end{References}
\begin{SeeAlso}\relax
\code{pkci2.flowcytest},
\code{ProbBin.flowcytest}, \code{KS.flowcytest},
\code{\LinkA{WLR.flowcytest}{WLR.flowcytest}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}

if (require(rfcdmin)){
## obtaining the FCS objects from VRC data
if ( !(is.element("unst.1829", objects()) & is.element("st.1829",
objects()) & is.element("unst.DRT", objects()) & is.element("st.DRT",
objects())) ){
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()){

## running all the tests
output1.runall<-runflowcytests(IFN.control, IFN.stimul,
varname="Interferon Gamma",
title="HIV negative individual 1829", crit.pkci2=0.9999)
}

## HIV positive individual DRT
  IFN.control2<-unst.DRT@data[1:2000,4]
  IFN.stimul2<-st.DRT@data[1:2000,4]

if (interactive()){
## running only WLR.flowcytest and pkci2.flowcytest
output2.runall<-runflowcytests(IFN.control2, IFN.stimul2,
flowcytests=c("WLR","pkci2"), varname="Interferon Gamma",
title="HIV negative individual 1829", crit.pkci2=0.9999)
}
## 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}

