gapply {sna} | R Documentation

## Apply Functions Over Vertex Neighborhoods

### Description

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

### Usage

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

### Arguments

`X` | one or more input graphs.
`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?

### Details

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.

### Value

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

### Author(s)

Carter T. Butts buttsc@uci.edu

### See Also

`apply`, `sapply`

### Examples

    #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)

[Package sna version 1.1 Index]