\HeaderA{ProbBin.FCS}{ProbBin.FCS R-object: Probability binning of 2 samples}{ProbBin.FCS}
\keyword{univar}{ProbBin.FCS}
\keyword{classes}{ProbBin.FCS}
\begin{Description}\relax
Constructs a list of histogram objects and other variables on the
probability binning between 2 samples, usually the
stimulated and unstimulated data (post gating).
\end{Description}
\begin{Usage}
\begin{verbatim}

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

\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{controldata}] a vector of the unstimulated sample data (of 1 variable)
\item[\code{stimuldata}] a vector of the stimulated sample data (of 1 variable) 
\item[\code{N}] the number of observations per a bin 
\item[\code{varname}] character string of the name of the variable (optional) 
\item[\code{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[\code{MY.DEBUG}] If TRUE, then debugging statements will be printed;
default is TRUE.
\item[\code{...}] other options besides 'plot' and 'br' in \LinkA{hist}{hist} function
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
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.
\end{Details}
\begin{Value}
\begin{ldescription}
\item[\code{unst.hist}] histogram object of the control/unstimulated data
\item[\code{st.hist }] histogram object of the stimulated data
\item[\code{PB}] type of Probability binning: either "by.control" or "combined"
\item[\code{N.in.bin}] number in each bin
\item[\code{varname}] character string of the variable name
\end{ldescription}
\end{Value}
\begin{Section}{WARNING}
Gating and subsetting should precede the analysis and
the use of this function.  It is a good idea to implement
\code{\LinkA{icreateGate}{icreateGate}} or \code{\LinkA{createGate}{createGate}} and
\code{\LinkA{extractGatedData}{extractGatedData}} before this analysis on univariate data.
\end{Section}
\begin{Note}\relax
Further graphing \& testing can be implemented via the following functions in
rflowcyt package:\code{\LinkA{plot.ProbBin.FCS}{plot.ProbBin.FCS}},
\code{\LinkA{summary.ProbBin.FCS}{summary.ProbBin.FCS}}, \code{\LinkA{ProbBin.flowcytest}{ProbBin.flowcytest}}
\end{Note}
\begin{Author}\relax
Zoe Moodie, A.J. Rossini, J.Y. Wan
\end{Author}
\begin{References}\relax
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{\LinkA{hist}{hist}}, \code{\LinkA{breakpoints.ProbBin}{breakpoints.ProbBin}}, \code{\LinkA{plot.ProbBin.FCS}{plot.ProbBin.FCS}},
\code{\LinkA{summary.ProbBin.FCS}{summary.ProbBin.FCS}}, \code{\LinkA{ProbBin.flowcytest}{ProbBin.flowcytest}},
\code{\LinkA{is}{is}}, \code{\LinkA{as}{as}}
\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.
## 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)
}

\end{ExampleCode}
\end{Examples}

