\name{runflowcytests}
\alias{runflowcytests}
\title{Tests the equivalence of two univariate sample distributions by
  using four different methods}
\description{
  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}
  
}
\usage{
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"))
}

\arguments{
  \item{controldata}{a vector of values/fluoroescent measurements; a univariate
    control sample}
  \item{stimuldata}{a vector of values/fluoroescent measurements; a univariate
    stimulated sample}
  \item{flowcytests}{vector denoting the names of the tests that are
    implemented; default is a vector of all the test names}
  \item{N.in.bin}{ a number which denotes the number per bin in used in
    probability binning}
  \item{varname}{character strong of the name of the variable under
    investigation (this is usually the gamma interferon variable)}
  \item{title}{character string of the title of the plots}
  \item{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{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{crit.pkci2}{the percent of control sample to above the
    meaningful percentile (usually 99.9th percentile) (for
    pkci2.flowcytest)}
  \item{alpha.pkci2}{Type I error rate for construction of the
    (1-alpha)\% Confidence Interval (for pkci2.flowcytest)}
  \item{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{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{WLR.plotted}{boolean; if TRUE, then plot is made; otherwise if
    FALSE, plotting is surpressed; default=TRUE}
  
  \item{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{\dots}{other options in \code{KS.flowcytest}}
  \item{KS.plotted}{boolean to display the corresponding plot; default
    is TRUE and the plot will be displayed}

  \item{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{PBobj.plots.made}{character string denoting which histogram plot should be 
   displayed; default is "both"} 
  
}

\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.
  
}
\references{
  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).}

\author{Zoe Moodie, A.J. Rossini, J.Y. Wan}
\note{For more information about the output, please see the other
  flowcytests in the "See Also" Section.}

\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{pkci2.flowcytest},
  \code{ProbBin.flowcytest}, \code{KS.flowcytest},
  \code{\link{WLR.flowcytest}} }

\examples{

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.
}

}
\keyword{univar}% at least one, from doc/KEYWORDS
\keyword{dplot}% __ONLY ONE__ keyword per line
\keyword{hplot}% __ONLY ONE__ keyword per line