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

