\HeaderA{ProbBin.flowcytest}{Test the equivalence of two univariate sample distributions by using
Probability Binning and plots the probability-binned histograms
of the two samples}{ProbBin.flowcytest}
\aliasA{ProbBin.by.control}{ProbBin.flowcytest}{ProbBin.by.control}
\aliasA{ProbBin.combined}{ProbBin.flowcytest}{ProbBin.combined}
\keyword{univar}{ProbBin.flowcytest}
\keyword{hplot}{ProbBin.flowcytest}
\begin{Description}\relax
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.
\end{Description}
\begin{Usage}
\begin{verbatim}
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"),
   ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{controldata}] numerical vector of the control sample univariate data
\item[\code{stimuldata}] numerical vector of the stimulated sample of the
univariate data
\item[\code{N}] The nummber of observations in each bin on the data specified
in the AnalyType option
\item[\code{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[\code{AnalyType}] Probability Binning either "by.control" or based on
the "combined" (control and stimulated) data
\item[\code{title}] character string denoting the title of the plots
\item[\code{MY.DEBUG}] boolean; if TRUE, debugging statements are printed;
default is FALSE
\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{plots.made}] character string denoting which histogram plot should be 
displayed; default is "both"
\item[\code{...}] more plotting options; see \code{plot.ProbBin.FCS} and
\code{hist} for details
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The testing performed are summarized in \code{summary.ProbBin.FCS},
and the plots are produced by \code{plot.ProbBin.FCS}.
\end{Details}
\begin{Value}
A list consisting of:
\begin{ldescription}
\item[\code{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[\code{control.bins}] single column matrix of the counts in each bin of
the control dataset
\item[\code{stim.bins}] single column matrix of the counts in each bin of the
stimulated dataset
\item[\code{total.control}] numeric; total number in the control dataset
\item[\code{total.stim}] numeric; total number in the stimulated dataset
\item[\code{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[\code{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[\code{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[\code{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[\code{PBmetric.adj}] Baggerly's adjusted PB metric statistic which is a
Chi-squared statistic
\item[\code{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[\code{p.val.1tail.chi.adj}] Upper one-tailed chi-squared p-value
corresponding to Baggerly's adjusted PB metric
\item[\code{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[\code{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[\code{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[\code{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[\code{pearson.df}] the degrees of freedom for the chi-squared statistic
\item[\code{pearson.p.value}] The p-value corresponding to the chi-squared distribution
\item[\code{pearson.method}] string of the indicating the type of test and
options performed
\item[\code{pearson.dataname}] string of the name(s) of the data
\item[\code{pearson.observed}] a vector of the observed counts
\item[\code{pearson.expected}] a vector of the expected counts under the null
hypothesis
\item[\code{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
\end{ldescription}


Two histograms, one of each sample, are also plotted.
\end{Value}
\begin{Section}{WARNING}
Usually the FCS object is gated and subset prior to
this testing and analysis.
\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
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).
\end{References}
\begin{SeeAlso}\relax
\code{pkci2.flowcytest},
\code{WLR.flowcytest}, \code{KS.flowcytest},
\code{\LinkA{runflowcytests}{runflowcytests}}, \code{\LinkA{summary.ProbBin.FCS}{summary.ProbBin.FCS}},
\code{\LinkA{ProbBin.FCS}{ProbBin.FCS}}, \code{\LinkA{plot.ProbBin.FCS}{plot.ProbBin.FCS}}, \code{\LinkA{hist}{hist}}
\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]

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

\end{ExampleCode}
\end{Examples}

