sdmat                  package:sna                  R Documentation

_E_s_t_i_m_a_t_e _t_h_e _S_t_r_u_c_t_u_r_a_l _D_i_s_t_a_n_c_e _M_a_t_r_i_x _f_o_r _a _G_r_a_p_h _S_e_t

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

     Estimates the structural distances among all elements of `dat'
     using the method specified in `method'.

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

     sdmat(dat, normalize=FALSE, diag=FALSE, mode="digraph", 
         output="matrix", method="mc", exchange.list=rep(0, 
         dim(dat)[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.  This data need not be dichotomous, and
          missing values are allowed. 

normalize: Divide by the number of available dyads? 

    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. 

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

  output: "matrix" for matrix output, "dist" for a `dist' object
          (requires `mva'). 

  method: Method to be used to search the space of accessible
          permutations; must be one of ``none'', ``exhaustive'',
          ``anneal'', ``hillclimb'', or ``mc''. 

exchange.list: Information on which vertices are exchangeable (see
          below); this must be a single number, a vector of length n,
          or a nx2 matrix. 

     ...: Additional arguments to `lab.optimize'

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

     The structural distance between two graphs G and H is defined as

           d_S(G,H | L_G,L_H) = min_[L_G,L_H] d(l(G),l(H))

     where L_G is the set of accessible permutations/labelings of G,
     and l(G) is a permuation/relabeling of the vertices of G (l(G) in
     L_G).  The set of accessible permutations on a given graph is
     determined by the theoretical exchangeability of its vertices; in
     a  nutshell, two vertices are considered to be theoretically
     exchangeable for a given problem if all predictions under the
     conditioning theory are invariant to a relabeling of the vertices
     in question (see Butts and Carley (2001) for a more formal
     exposition).  Where no vertices are exchangeable, the structural
     distance becomes the its labeled counterpart (here, the Hamming
     distance).  Where all vertices are exchangeable, the structural
     distance reflects the distance between unlabeled graphs; other
     cases correspond to distance under partial labeling.  

     The accessible permutation set is determined by the
     `exchange.list' argument, which is dealt with in the following
     manner. First, `exchange.list' is expanded to fill an nx2 matrix. 
     If `exchange.list' is a single number, this is trivially
     accomplished by replication; if `exchange.list' is a vector of
     length n, the matrix is formed by cbinding two copies together. 
     If `exchange.list' is already an nx2 matrix, it is left as-is. 
     Once the nx2 exchangeabiliy matrix has been formed, it is
     interpreted as follows: columns refer to graphs 1 and 2,
     respectively; rows refer to their corresponding vertices in the
     original adjacency matrices; and vertices are taken to be
     theoretically exchangeable iff their corresponding exchangeability
     matrix values are identical.  To obtain an unlabeled distance (the
     default), then, one could simply let `exchange.list' equal any
     single number.  To obtain the Hamming distance, one would use the
     vector `1:n'.

     Because the set of accessible permutations is, in general, very
     large (o(n!)), searching the set for the minimum distance is a
     non-trivial affair.  Currently supported methods for estimating
     the structural distance are hill climbing, simulated annealing,
     blind monte carlo search, or exhaustive search (it is also
     possible to turn off searching entirely).  Exhaustive search is
     not recommended for graphs larger than size 8 or so, and even this
     may take days; still, this is a valid alternative for small
     graphs.  Blind monte carlo search and hill climbing tend to be
     suboptimal for this problem and are not, in general recommended,
     but they are available if desired.  The preferred (and default)
     option for permutation search is simulated annealing, which seems
     to work well on this problem (though some tinkering with the
     annealing parameters may be needed in order to get optimal
     performance).  See the help for `lab.optimize' for more
     information regarding these options.

     Structural distance matrices may be used in the same manner as any
     other distance matrices (e.g., with multidimensional scaling,
     cluster analysis, etc.)  Classical null hypothesis tests should
     not be employed with structural distances, and QAP tests are
     almost never appropriate (save in the uniquely labeled case).  See
     `cugtest' for a more reasonable alternative.

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

     A matrix of distances (or an object of class `dist')

_W_a_r_n_i_n_g:

     The search process can be very slow, particularly for large
     graphs.  In particular, the exhaustive method is order factorial,
     and will take approximately forever for unlabeled graphs of size
     greater than about 7-9.

_N_o_t_e:

     For most applications, `sdmat' is dominated by `structdist'; the
     former is retained largely for reasons of compatibility.

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

     Carter T. Butts ctb@andrew.cmu.edu

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

     Butts, C.T., and Carley, K.M.  (2001).  ``Multivariate Methods for
     Interstructural Analysis.''  CASOS Working Paper, Carnegie Mellon
     University.

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

     `hdist', `structdist'

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

     #Generate two random graphs
     g<-array(dim=c(3,5,5))
     g[1,,]<-rgraph(5)
     g[2,,]<-rgraph(5)

     #Copy one of the graphs and permute it
     g[3,,]<-rmperm(g[2,,])

     #What are the structural distances between the labeled graphs?
     sdmat(g,exchange.list=1:5)

     #What are the structural distances between the underlying unlabeled 
     #graphs?
     sdmat(g,method="anneal", prob.init=0.9, prob.decay=0.85, 
         freeze.time=50, full.neighborhood=TRUE)

