\name{ProbBin.flowcytest}
\alias{ProbBin.flowcytest}
\alias{ProbBin.by.control}
\alias{ProbBin.combined}
%- Also NEED an `\alias' for EACH other topic documented here.
\title{Test the equivalence of two univariate sample distributions by using
  Probability Binning and plots the probability-binned histograms
  of the two samples}
\description{
  This function will create a probability binning object called
  \code{ProbBin.FCS} and will perform summary statistics and a plot of
  the two resulting probability-binned histograms.  There can be
  probability binning based on the combined data of the two samples or
  just based on one sample, which is labled as the control.
}
\usage{
ProbBin.flowcytest(controldata,
   stimuldata, N = 100, varname = "",
   AnalyType = c("combined", "by.control"),
   title = "",
   MY.DEBUG = FALSE,
   PBobj.plotted=TRUE,
   plots.made=c("both", "stimulated", "unstimulated"),
   ...)
}
%- maybe also `usage' for other objects documented here.
\arguments{
  \item{controldata}{numerical vector of the control sample univariate data}

  \item{stimuldata}{numerical vector of the stimulated sample of the
    univariate data}

  \item{N}{The nummber of observations in each bin on the data specified
    in the AnalyType option}

  \item{varname}{character string of the variable being investigated
    (usually, in this analysis, the interferon gamma variable is used
    after gating and subsetting of the FCS object)}

  \item{AnalyType}{ Probability Binning either "by.control" or based on
    the "combined" (control and stimulated) data}

  \item{title}{character string denoting the title of the plots}

  \item{MY.DEBUG}{boolean; if TRUE, debugging statements are printed;
    default is FALSE}

  \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{plots.made}{character string denoting which histogram plot should be 
   displayed; default is "both"} 
  
  \item{...}{more plotting options; see \code{plot.ProbBin.FCS} and
    \code{hist} for details}
}
\details{
  The testing performed are summarized in \code{summary.ProbBin.FCS},
  and the plots are produced by \code{plot.ProbBin.FCS}. 
}
\value{
 A list consisting of:
  \item{PBinType}{Type of Probability Binning:
    \item{"by.control"}{uses the control dataset to obtain the
    breaks/cutoffs to bin the stimulated dataset given a certain
    number of observations in each bin of the control dataset}
    \item{"combined"}{uses the combined dataset (both control and stimulated
    datasets) to obtain the breaks/cutoffs for the bins given a
    certain number in each bin}
  }
  \item{control.bins}{single column matrix of the counts in each bin of
    the control dataset} 
  \item{stim.bins}{single column matrix of the counts in each bin of the
    stimulated dataset}
  \item{total.control}{numeric; total number in the control dataset}
  \item{total.stim}{numeric; total number in the stimulated dataset}
  \item{T.chi.unadj}{Roederer's unadjusted normalized PB metric statistic which
    is normalized by subtracting off the
    mean and then dividing by the standard deviation.  This statistic is
    approximately standard normal.}
  \item{p.val.2tail.z.unadj}{Two-tailed standard normal p-value corresponding to the
    Roederer's unadjusted normalized PB metric statistic which is approximated as
    a standard normal}
  \item{p.val.1tail.z.unadj}{Upper standard normal one-tailed p-value corresponding to the
    Roederer's unadjusted PB metric statistic which is approximated as
    a standard normal}
  \item{PBmetric.unadj}{Roederer's unadjusted PB metric which is
    ((n.c + n.s)/(2*nc.*n.s))*Chi-squared or an unadjusted
  chi-squared statistic, where n.c is the number of control observations
  (unbinned) and n.s is the number of stimulated observations (unbinned)}
  \item{PBmetric.adj}{Baggerly's adjusted PB metric statistic which is a
    Chi-squared statistic}
  \item{PB.df}{The degrees of freedom of the PB metric (adjusted and
    unadjusted) which is B-1, where B is the number of bins in the
    eitherthe control or the stimulated binned data}
  \item{p.val.1tail.chi.adj}{Upper one-tailed chi-squared p-value
    corresponding to Baggerly's adjusted PB metric}
  \item{T.chi.adj}{Baggerly's PB metric which is normalized
    by subtracting off the mean and dividing by the standard deviation;
    This normalized statistic is approximately standard normal.}
  \item{p.val.1tail.z.adj}{Upper one-tailed standard normal p-value corresponding to the
    Baggerly's adjusted normalized PB metric statistic which is approximated as
    a standard normal}
  \item{p.val.2tail.z.adj}{Standard normal two-tailed p-value corresponding to the
    Baggerly's adjusted PB metric statistic which is approximated as
    a standard normal}
  \item{pearson.stat}{Pearson's Chi-Squared Statistic with degrees
  of freedom 2B-1, where B is the number of bins in either the control or
  the stimulated binned data}
  \item{pearson.df}{the degrees of freedom for the chi-squared statistic}
  \item{pearson.p.value}{The p-value corresponding to the chi-squared distribution}
  \item{pearson.method}{string of the indicating the type of test and
    options performed}
  \item{pearson.dataname}{string of the name(s) of the data}
  \item{pearson.observed}{a vector of the observed counts}
  \item{pearson.expected}{a vector of the expected counts under the null
  hypothesis}
  \item{pearson.p.val.PB.df}{Fisher's Chi-squared statistic with degrees
  of freedom B-1, where B is the number of bins in either the control or
  the stimulated binned data}

  Two histograms, one of each sample, are also plotted.
}
\references{
  Keith A. Baggerly "Probability Binning and Test Agreement
  between Multivariate Immunofluorescence Histograms: Extending the
  Chi-Squared test" Cytometry 45: 141:150 (2001).

  Mario Roederer, et al. "Probability Binning Comparison: A
  Metric for Quantitating Univariate Distribution Differences" Cytometry
  45:37-46 (2001).}

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


 \seealso{ \code{pkci2.flowcytest},
  \code{WLR.flowcytest}, \code{KS.flowcytest},
  \code{\link{runflowcytests}}, \code{\link{summary.ProbBin.FCS}},
  \code{\link{ProbBin.FCS}}, \code{\link{plot.ProbBin.FCS}}, \code{\link{hist}}}


\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]


## probability binning based on the combined data of both samples
if (interactive()==TRUE){
par(mfrow=c(2,2))
test1.out<-ProbBin.flowcytest(IFN.control, IFN.stimul, varname="Interferon Gamma",
AnalyType="combined", N=200, title="HIV negative individual 1829")
}
## HIV positive individual DRT
  IFN.control2<-unst.DRT@data[1:2000,4]
  IFN.stimul2<-st.DRT@data[1:2000,4]

## probability binning based on the control data only
if (interactive()==TRUE){
test2.out<-ProbBin.flowcytest(IFN.control2, IFN.stimul2,
varname="Interferon Gamma", AnalyType="by.control",
N=100, title="HIV negative individual 1829")
}
## 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{hplot}% __ONLY ONE__ keyword per line