gapply                  package:sna                  R Documentation

_A_p_p_l_y _F_u_n_c_t_i_o_n_s _O_v_e_r _V_e_r_t_e_x _N_e_i_g_h_b_o_r_h_o_o_d_s

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

     Returns a vector or array or list of values obtained by applying a
     function to vertex neighborhoods of a given order.

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

     gapply(X, MARGIN, STATS, FUN, ..., mode = "digraph", diag = FALSE, 
         distance = 1, thresh = 0, simplify = TRUE)

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

       X: the adjacency matrix to be used. 

  MARGIN: a vector giving the ``margin'' of 'X' to be used in
          calculating neighborhoods.  1 indicates rows (out-neighbors),
          2 indicates columns (in-neighbors), and c(1,2) indicates rows
          and columns (total neighborhood). 

   STATS: the vector or matrix of vertex statistics to be used. 

     FUN: the function to be applied.  In the case of operators, the
          function name must be quoted. 

     ...: additional arguments to 'FUN'. 

    mode: '"graph"' if 'X' is a simple graph, else '"digraph"'. 

    diag: boolean; are the diagonals of 'X' meaningful? 

distance: the maximum geodesic distance at which neighborhoods are to
          be taken.  1 signifies first-order neighborhoods, 2 signifies
          second-order neighborhoods, etc. 

  thresh: the threshold to be used in dichotomizing 'X'. 

simplify: boolean; should we attempt to coerce output to a vector if
          possible? 

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

     For each vertex in 'X', 'gapply' first identifies all members of
     the relevant neighborhood (as determined by 'MARGIN' and
     'distance') and pulls the rows of 'STATS' associated with each. 
     'FUN' is then applied to this collection of values.  This provides
     a very quick and easy way to answer questions like:

        *  How many persons are in each ego's 3rd-order neighborhood?

        *  What fraction of each ego's alters are female?

        *  What is the mean income for each ego's trading partners?

        *  etc.

     With clever use of 'FUN' and 'STATS', a wide range of
     functionality can be obtained.

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

     The result of the iterated application of 'FUN' to each vertex
     neighborhood's 'STATS'.

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

     Carter T. Butts buttsc@uci.edu

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

     'apply', 'sapply'

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

     #Generate a random graph
     g<-rgraph(6)

     #Calculate the degree of g using gapply
     all(gapply(g,1,rep(1,6),sum)==degree(g,cmode="outdegree"))
     all(gapply(g,2,rep(1,6),sum)==degree(g,cmode="degree"))
     all(gapply(g,c(1,2),rep(1,6),sum)==degree(symmetrize(g),cmode="freeman")/2)

     #Find first and second order neighborhood means on some variable
     gapply(g,c(1,2),1:6,mean)
     gapply(g,c(1,2),1:6,mean,distance=2)

