ProbBin.flowcytest {rflowcyt} | R Documentation

## 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 `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"),
       ...)

### Arguments

`controldata` | numerical vector of the control sample univariate data
`stimuldata` | numerical vector of the stimulated sample of the univariate data
`N` | The nummber of observations in each bin on the data specified in the AnalyType option
`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)
`AnalyType` | Probability Binning either "by.control" or based on the "combined" (control and stimulated) data
`title` | character string denoting the title of the plots
`MY.DEBUG` | boolean; if TRUE, debugging statements are printed; default is FALSE
`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
`plots.made` | character string denoting which histogram plot should be displayed; default is "both"
`...` | more plotting options; see `plot.ProbBin.FCS` and `hist` for details

### Details

The testing performed are summarized in `summary.ProbBin.FCS`, and the plots are produced by `plot.ProbBin.FCS`.

### Value

A list consisting of:

`PBinType` | Type of Probability Binning: "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 "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
`control.bins` | single column matrix of the counts in each bin of the control dataset
`stim.bins` | single column matrix of the counts in each bin of the stimulated dataset
`total.control` | numeric; total number in the control dataset
`total.stim` | numeric; total number in the stimulated dataset
`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.
`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
`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
`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)
`PBmetric.adj` | Baggerly's adjusted PB metric statistic which is a Chi-squared statistic
`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
`p.val.1tail.chi.adj` | Upper one-tailed chi-squared p-value corresponding to Baggerly's adjusted PB metric
`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.
`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
`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
`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
`pearson.df` | the degrees of freedom for the chi-squared statistic
`pearson.p.value` | The p-value corresponding to the chi-squared distribution
`pearson.method` | string of the indicating the type of test and options performed
`pearson.dataname` | string of the name(s) of the data
`pearson.observed` | a vector of the observed counts
`pearson.expected` | a vector of the expected counts under the null hypothesis
`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.

### WARNING

Usually the FCS object is gated and subset prior to this testing and analysis.

### Note

Other flowcytests are available such as `pkci2.flowcytest`, `ProbBin.flowcytest`, `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.

### Author(s)

A.J. Rossini and J.Y. Wan

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

### See Also

`pkci2.flowcytest`, `WLR.flowcytest`, `KS.flowcytest`, `runflowcytests`, `summary.ProbBin.FCS`, `ProbBin.FCS`, `plot.ProbBin.FCS`, `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.
    }

[Package rflowcyt version 1.0.1 Index]