cugtest                 package:sna                 R Documentation

_P_e_r_f_o_r_m _C_o_n_d_i_t_i_o_n_a_l _U_n_i_f_o_r_m _G_r_a_p_h (_C_U_G) _H_y_p_o_t_h_e_s_i_s _T_e_s_t_s _f_o_r _G_r_a_p_h-_L_e_v_e_l _I_n_d_i_c_e_s

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

     `cugtest' tests an arbitrary GLI (computed on `dat' by `FUN')
     against a conditional uniform graph null hypothesis, via Monte
     Carlo simulation of likelihood quantiles.  Some variation in the
     nature of the conditioning is available; currently, conditioning
     only on size, conditioning jointly on size and estimated tie
     probability (via density), and conditioning jointly on size and
     (bootstrapped) edge value distributions are implemented.  Note
     that fair amount of flexibility is possible regarding CUG tests on
     functions of GLIs (Anderson et al., 1999).  See below for more
     details.

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

     cugtest(dat, FUN, reps=1000, gmode="digraph", cmode="density", 
         diag=FALSE, g1=1, g2=2, ...)

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

     dat: Data array to be analyzed.  By assumption, the first
          dimension of the array indexes the graph, with the next two
          indexing the actors.  Provided that `FUN' is well-behaved,
          this can be an n x n matrix if only one graph is involved. 

     FUN: Function to compute GLIs, or functions thereof.  `FUN' must
          accept `dat' and the specified `g' arguments, and should
          return a real number. 

    reps: Integer indicating the number of draws to use for quantile
          estimation.  Note that, as for all Monte Carlo procedures,
          convergence is slower for more extreme quantiles.  By
          default, `reps==1000'. 

   gmode: String indicating the type of graph being evaluated. 
          "digraph" indicates that edges should be interpreted as
          directed; "graph" indicates that edges are undirected. 
          `gmode' is set to "digraph" by default. 

   cmode: String indicating the type of conditioning assumed by the
          null hypothesis.  If `cmode' is set to "density", then the
          density of the graph in question is used to determine the tie
          probabilities of the Bernoulli graph draws (which are also
          conditioned on |V(G)|).  If`cmode=="ties"', then draws are
          bootstrapped from the distribution of edge values within the
          data matrices.  If `cmode="order"', then draws are uniform
          over all graphs of the same order (size) as the graphs within
          the input stack.  By default, `cmode' is set to `"density"'.

    diag: Boolean indicating whether or not the diagonal should be
          treated as valid data.  Set this true if and only if the data
          can contain loops.  `diag' is `FALSE' by default. 

      g1: Integer indicating the index of the first graph input to the
          GLI.  By default, `g1==1'. 

      g2: Integer indicating the index of the second graph input to the
          GLI.  (`FUN' can ignore this, if one wishes to test the GLI
          value of a single graph, but it should recognize the
          argument.)  By default, `g2==2'. 

     ...: Additional arguments to `FUN'. 

_D_e_t_a_i_l_s:

     The null hypothesis of the CUG test is that the observed GLI (or
     function thereof) was drawn from a distribution isomorphic to that
     of said GLI evaluated (uniformly) on the space of all graphs
     conditional on one or more features.  The most common "features"
     used for conditioning purposes are order (size) and density, both
     of which are known to have strong and nontrivial effects on other
     GLIs (Anderson et al., 1999) and which are, in many cases,
     exogenously determined.  Since theoretical results regarding
     functions of arbitrary GLIs on the space of graphs are not
     available, the standard approach to CUG testing is to approximate
     the quantiles of the likelihood associated with the null
     hypothesis using Monte Carlo methods.  This is the technique
     utilized by `cugtest', which takes appropriately conditioned draws
     from the set of graphs and computes on them the GLI specified in
     `FUN', thereby accumulating an approximation to the true
     likelihood.

     The `cugtest' procedure returns a `cugtest' object containing the
     estimated likelihood (distribution of the test GLI under the null
     hypothesis), the observed GLI value of the data, and the
     one-tailed p-values (estimated quantiles) associated with said
     observation.  As usual, the (upper tail) null hypothesis is
     rejected for significance level alpha if p>=observation is less
     than alpha (or p<=observation, for the lower tail); if the
     hypothesis is undirected, then one rejects if either
     p<=observation or p>=observation is less then alpha/2.  Standard
     caveats regarding the use of null hypothesis testing procedures
     are relevant here: in particular, bear in mind that a significant
     result does not necessarily imply that the likelihood ratio of the
     null model and the alternative hypothesis favors the latter.

     Informative and aesthetically pleasing portrayals of `cugtest'
     objects are available via the `print.cugtest' and
     `summary.cugtest' methods.  The `plot.cugtest' method displays the
     estimated distribution, with a reference line signifying the
     observed value.

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

     An object of class `cugtest', containing

 testval: The observed GLI value. 

    dist: A vector containing the Monte Carlo draws.  

   pgreq: The proportion of draws which were greater than or equal to
          the observed GLI value. 

   pleeq: The proportion of draws which were less than or equal to the
          observed GLI value. 

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

     Carter T. Butts ctb@andrew.cmu.edu

_R_e_f_e_r_e_n_c_e_s:

     Anderson, B.S.; Butts, C.T.; and Carley, K.M. (1999). ``The
     Interaction of Size and Density with Graph-Level Indices.'' Social
     Networks, 21(3), 239-267.

_S_e_e _A_l_s_o:

     `qaptest', `gliop'

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

     #Draw two random graphs, with different tie probabilities
     dat<-rgraph(20,2,tprob=c(0.2,0.8))
     #Is their correlation higher than would be expected, conditioning 
     #only on size?
     cug<-cugtest(dat,gcor,cmode="order")
     summary(cug)
     #Now, let's try conditioning on density as well.
     cug<-cugtest(dat,gcor)
     summary(cug)

