\name{ProbBin.FCS}
\alias{ProbBin.FCS}
%- Also NEED an `\alias' for EACH other topic documented here.
\title{ProbBin.FCS R-object: Probability binning of 2 samples}
\description{
  Constructs a list of histogram objects and other variables on the
  probability binning between 2 samples, usually the
  stimulated and unstimulated data (post gating).
}
\usage{

ProbBin.FCS(controldata, stimuldata, N, varname = "",
PBspec = c("by.control", "combined"), MY.DEBUG = TRUE, ...)

}
%- maybe also `usage' for other objects documented here.
\arguments{

  \item{controldata}{ a vector of the unstimulated sample data (of 1 variable)}
  \item{stimuldata}{ a vector of the stimulated sample data (of 1 variable) }
  \item{N}{the number of observations per a bin }
  \item{varname}{character string of the name of the variable (optional) }
  \item{PBspec}{The type of probability binning either:
    \item{"by.control"}{in which the breaks for the bins are based on
      the unstimulated having N observations in each bin}
    \item{"combined"}{in which the breaks for the bins are based on the
      combined dataset (stimulated and unstimulated) having
      N observations in each bin}
    }
  \item{MY.DEBUG}{If TRUE, then debugging statements will be printed;
    default is TRUE.}
  \item{\dots}{other options besides 'plot' and 'br' in \link{hist} function}
}
\details{
Based on either the control data or the combined data, breaks for the
bins are determined by having a specific number of observations fall in
each bin.  These breaks are then applied to the stimulated data or both
the control and stimulated data, respectively.  The resulting two
histograms (one of the stimulated data and the other of the control
data) are the result of this probability binning method.
}
\value{
  
  \item{unst.hist}{histogram object of the control/unstimulated data}
  \item{st.hist }{histogram object of the stimulated data}
  \item{PB}{type of Probability binning: either "by.control" or "combined"}
  \item{N.in.bin}{number in each bin}
  \item{varname}{character string of the variable name}

}
\references{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{Further graphing & testing can be implemented via the following functions in
  rflowcyt package:\code{\link{plot.ProbBin.FCS}},
  \code{\link{summary.ProbBin.FCS}}, \code{\link{ProbBin.flowcytest}}  }
\section{WARNING}{Gating and subsetting should precede the analysis and
  the use of this function.  It is a good idea to implement
  \code{\link{icreateGate}} or \code{\link{createGate}} and
  \code{\link{extractGatedData}} before this analysis on univariate data.}

\seealso{  \code{\link{hist}}, \code{\link{breakpoints.ProbBin}}, \code{\link{plot.ProbBin.FCS}},
  \code{\link{summary.ProbBin.FCS}}, \code{\link{ProbBin.flowcytest}},
  \code{\link[methods]{is}}, \code{\link[methods]{as}}
}

\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.
## Gating/subsetting should precede this analysis
IFN.gamma.1<-unst.1829@data[1:2000,4]
IFN.gamma.2<-st.1829@data[1:2000,4]

#Probability binning using the control dataset to determine the breaks
PB1<-ProbBin.FCS(IFN.gamma.1, IFN.gamma.2, 200,
varname=colnames(unst.1829@data)[4], PBspec="by.control",MY.DEBUG=FALSE)

## Probability Binning using the combined dataset (control & stimulated)
## to determing the breaks
PB2<-ProbBin.FCS(IFN.gamma.1, IFN.gamma.2, 200,
varname=colnames(unst.1829@data)[4], PBspec="combined",MY.DEBUG=FALSE)
}

}
\keyword{univar}
\keyword{classes}