ProbBin.flowcytest         package:rflowcyt         R Documentation

_T_e_s_t _t_h_e _e_q_u_i_v_a_l_e_n_c_e _o_f _t_w_o _u_n_i_v_a_r_i_a_t_e _s_a_m_p_l_e _d_i_s_t_r_i_b_u_t_i_o_n_s _b_y _u_s_i_n_g
_P_r_o_b_a_b_i_l_i_t_y _B_i_n_n_i_n_g _a_n_d _p_l_o_t_s _t_h_e _p_r_o_b_a_b_i_l_i_t_y-_b_i_n_n_e_d _h_i_s_t_o_g_r_a_m_s
_o_f _t_h_e _t_w_o _s_a_m_p_l_e_s

_D_e_s_c_r_i_p_t_i_o_n:

     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.

_U_s_a_g_e:

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

_A_r_g_u_m_e_n_t_s:

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

_D_e_t_a_i_l_s:

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

_V_a_l_u_e:

     A list consisting of: 

PBinType: Type of Probability Binning:

     "_b_y._c_o_n_t_r_o_l" 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

     "_c_o_m_b_i_n_e_d" 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.

_W_A_R_N_I_N_G:

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

_N_o_t_e:

     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.

_A_u_t_h_o_r(_s):

     A.J. Rossini and J.Y. Wan

_R_e_f_e_r_e_n_c_e_s:

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

_S_e_e _A_l_s_o:

     'pkci2.flowcytest', 'WLR.flowcytest', 'KS.flowcytest',
     'runflowcytests', 'summary.ProbBin.FCS', 'ProbBin.FCS',
     'plot.ProbBin.FCS', 'hist'

_E_x_a_m_p_l_e_s:

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

