runflowcytests           package:rflowcyt           R Documentation

_T_e_s_t_s _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 _f_o_u_r _d_i_f_f_e_r_e_n_t _m_e_t_h_o_d_s

_D_e_s_c_r_i_p_t_i_o_n:

     Runs the following flowcytests:

     _1. '_W_L_R._f_l_o_w_c_y_t_e_s_t' weighted log rank test (by default when rho=0)
          and a the plot of survival curves for both samples is also
          output

     _2. '_K_S._f_l_o_w_c_y_t_e_s_t' Kolmogorov-Smirnoff test for the difference in
          distributions for the control and the stimulated

     _3. '_P_r_o_b_B_i_n._f_l_o_w_c_y_t_e_s_t' Statistics proposed by Keith A. Baggerly
          and Mario Roederer which include Chi-squared and Normal tests
          for the PB metric via probability binning (both based on the
          control data only ("by.control") and based on the combined
          dataset of both the stimulated and the control samples
          ("combined")

     _4. '_p_k_c_i_2._f_l_o_w_c_y_t_e_s_t' Tests the difference of the upper tails of
          the two distributions

_U_s_a_g_e:

     runflowcytests(controldata, stimuldata, flowcytests = c("WLR", "KS",
                      "ProbBin.by.control", "ProbBin.combined", "pkci2"),
                      N.in.bin = 100, varname = "", title = " ", output.all
                      = FALSE, graph.outlay = c(3, 2), crit.pkci2 = 0.999,
                      alpha.pkci2 = 0.05, na.action.WLR =
                      options()$na.action, rho.WLR = 0, WLR.plotted=TRUE, alternative.KS =
                      "two.sided", ..., KS.plotted=TRUE,
                                PBobj.plotted=TRUE,
                     PBobj.plots.made=c("both", "stimulated", "unstimulated"))

_A_r_g_u_m_e_n_t_s:

controldata: a vector of values/fluoroescent measurements; a univariate
          control sample

stimuldata: a vector of values/fluoroescent measurements; a univariate
          stimulated sample

flowcytests: vector denoting the names of the tests that are
          implemented; default is a vector of all the test names

N.in.bin: a number which denotes the number per bin in used in
          probability binning

 varname: character strong of the name of the variable under
          investigation (this is usually the gamma interferon variable)

   title: character string of the title of the plots

output.all: boolean; if TRUE then all the statistics and p-values
          obtained are output in list form by test; if FALSE then only
          the names of the statistics, the statistics, the names of the
          p-values and the p-values are output in a data.frame; default
          is FALSE.

graph.outlay: a vector of length 2, describing the number of graphs on
          each row and the number of graphs on each column,
          respectively

crit.pkci2: the percent of control sample to above the meaningful
          percentile (usually 99.9th percentile) (for pkci2.flowcytest)

alpha.pkci2: Type I error rate for construction of the (1-alpha)%
          Confidence Interval (for pkci2.flowcytest)

na.action.WLR: a missing-data filter function.  This is applied to the
          'model.frame' after any subset argument has been used. 
          Default is 'options()\$na.action' (as quoted from the
          'survdiff' documentation)

 rho.WLR: the exponent in S(t)^rho, where S is the Kaplan-Meier
          estimate of survival; A value of 0 specifies using the
          weighted log-rank test, and a value of 1 specifies using the
          Peto and Peto modification of the Gehan-Wilcoxon test.

WLR.plotted: boolean; if TRUE, then plot is made; otherwise if FALSE,
          plotting is surpressed; default=TRUE

alternative.KS: character string of the alternative hypothesis:

          "_t_w_o-_s_i_d_e_d" Two sided alternative hypoothesis

          "_l_e_s_s" One-sided alternative hypothesis: controldata
               distribution is less than the stimuldata distribution

          "_g_r_e_a_t_e_r" One-sided alternative hypothesis: controldata
               distribution is greater than the stimuldata distribution

     ...: other options in 'KS.flowcytest'

KS.plotted: boolean to display the corresponding plot; default is TRUE
          and the plot will be displayed

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

PBobj.plots.made: character string denoting which histogram plot should
          be  displayed; default is "both"

_V_a_l_u_e:

     A dataframe consisting of 4 columns and 20 rows.  The labels on
     the columns are "statistics.names", "statistics", "pvalues.names",
     and "pvalues" or if 'output.all' is TRUE, a list of statistics and
     tesing output by test name will be produced. Also 6 to 0 plots are
     produced.

_W_A_R_N_I_N_G:

     Usually the FCS object is gated and subset prior to this testing
     and analysis.  Also this function requires the library 'survival'.

_N_o_t_e:

     For more information about the output, please see the other
     flowcytests in the "See Also" Section.

_A_u_t_h_o_r(_s):

     Zoe Moodie, A.J. Rossini, 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).

     Harrington, D. P. and Fleming, T. R. (1982). "A class of rank test
     procedures for censored survival data". Biometrika 69, 553-566.

     Zoe Moodie, PhD Statistical Center for HIV/AIDS Research and
     Prevention (SCHARP)  Fred Hutchison Cancer Research Center
     Seattle, WA 98109-1024

     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', 'ProbBin.flowcytest', 'KS.flowcytest',
     'WLR.flowcytest'

_E_x_a_m_p_l_e_s:

     if (require(rfcdmin)){
     ## obtaining the FCS objects from VRC data
     if ( !(is.element("unst.1829", objects()) & is.element("st.1829",
     objects()) & is.element("unst.DRT", objects()) & is.element("st.DRT",
     objects())) ){
     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]

     if (interactive()){

     ## running all the tests
     output1.runall<-runflowcytests(IFN.control, IFN.stimul,
     varname="Interferon Gamma",
     title="HIV negative individual 1829", crit.pkci2=0.9999)
     }

     ## HIV positive individual DRT
       IFN.control2<-unst.DRT@data[1:2000,4]
       IFN.stimul2<-st.DRT@data[1:2000,4]

     if (interactive()){
     ## running only WLR.flowcytest and pkci2.flowcytest
     output2.runall<-runflowcytests(IFN.control2, IFN.stimul2,
     flowcytests=c("WLR","pkci2"), varname="Interferon Gamma",
     title="HIV negative individual 1829", crit.pkci2=0.9999)
     }
     ## 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.
     }

