R: Two-Dimensional Visualization of Networks

plot.network.ergm {ergm} | R Documentation

## Two-Dimensional Visualization of Networks

### Description

`plot.network.ergm` produces a simple two-dimensional plot of the network object `x`. A variety of options are available to control vertex placement, display details, color, etc. The function is based on the plotting capabilities of the `network` package with additional pre-processing of arguments. Some of the capabilites require the `latentnet` package. See `plot.network` in the `network` package for details.

### Usage

    ## S3 method for class 'ergm'
    plot.network(x,
        attrname=NULL,
        label=network.vertex.names(x),
        coord=NULL,
        jitter=TRUE,
        thresh=0,
        usearrows=TRUE,
        mode="fruchtermanreingold",
        displayisolates=TRUE,
        interactive=FALSE,
        xlab=NULL,
        ylab=NULL,
        xlim=NULL,
        ylim=NULL,
        pad=0.2,
        label.pad=0.5,
        displaylabels=FALSE,
        boxed.labels=TRUE,
        label.pos=0,
        label.bg="white",
        vertex.sides=8,
        vertex.rot=0,
        arrowhead.cex=1,
        label.cex=1,
        loop.cex=1,
        vertex.cex=1,
        edge.col=1,
        label.col=1,
        vertex.col=2,
        label.border=1,
        vertex.border=1,
        edge.lty=1,
        label.lty=NULL,
        vertex.lty=1,
        edge.lwd=0,
        label.lwd=par("lwd"),
        edge.len=0.5,
        edge.curve=0.1,
        edge.steps=50,
        loop.steps=20,
        object.scale=0.01,
        uselen=FALSE,
        usecurve=FALSE,
        suppress.axes=TRUE,
        vertices.last=TRUE,
        new=TRUE,
        layout.par=NULL,
        cex.main=par("cex.main"),
        cex.sub=par("cex.sub"),
        seed=NULL,
        latent.control=list(maxit=500,
                            trace=0,
                            dyadsample=10000,
                            penalty.sigma=c(5,0.5),
                            nsubsample=200),
        colornames="rainbow",
        verbose=FALSE,
        latent=FALSE,
        ...)

### Arguments

`x` | an object of class `network`.
`attrname` | an optional edge attribute, to be used to set edge values.
`label` | a vector of vertex labels, if desired; defaults to the vertex labels returned by `network.vertex.names`.
`coord` | user-specified vertex coordinates, in an NCOL(dat)x2 matrix. Where this is specified, it will override the `mode` setting.
`jitter` | boolean; should the output be jittered?
`thresh` | real number indicating the lower threshold for tie values. Only ties of value >`thresh` are displayed. By default, `thresh`=0.
`usearrows` | boolean; should arrows (rather than line segments) be used to indicate edges?
`mode` | the vertex placement algorithm; this must correspond to a `network.layout` function. These include `"latent"`, `"latentPrior"`, and `"fruchtermanreingold"`.
`displayisolates` | boolean; should isolates be displayed?
`interactive` | boolean; should interactive adjustment of vertex placement be attempted?
`xlab` | x axis label.
`ylab` | y axis label.
`xlim` | the x limits (min, max) of the plot.
`ylim` | the y limits of the plot.
`pad` | amount to pad the plotting range; useful if labels are being clipped.
`label.pad` | amount to pad label boxes (if `boxed.labels==TRUE`), in character size units.
`displaylabels` | boolean; should vertex labels be displayed?
`boxed.labels` | boolean; place vertex labels within boxes?
`label.pos` | position at which labels should be placed, relative to vertices. `0` results in labels which are placed away from the center of the plotting region; `1`, `2`, `3`, and `4` result in labels being placed below, to the left of, above, and to the right of vertices (respectively); and `label.pos>=5` results in labels which are plotted with no offset (i.e., at the vertex positions).
`label.bg` | background color for label boxes (if `boxed.labels==TRUE`); may be a vector, if boxes are to be of different colors.
`vertex.sides` | number of polygon sides for vertices; may be given as a vector or a vertex attribute name, if vertices are to be of different types.
`vertex.rot` | angle of rotation for vertices (in degrees); may be given as a vector or a vertex attribute name, if vertices are to be rotated differently.
`arrowhead.cex` | expansion factor for edge arrowheads.
`label.cex` | character expansion factor for label text.
`loop.cex` | expansion factor for loops; may be given as a vector or a vertex attribute name, if loops are to be of different sizes.
`vertex.cex` | expansion factor for vertices; may be given as a vector or a vertex attribute name, if vertices are to be of different sizes.
`edge.col` | color for edges; may be given as a vector, adjacency matrix, or edge attribute name, if edges are to be of different colors.
`label.col` | color for vertex labels; may be given as a vector or a vertex attribute name, if labels are to be of different colors.
`vertex.col` | color for vertices; may be given as a vector or a vertex attribute name, if vertices are to be of different colors.
`label.border` | label border colors (if `boxed.labels==TRUE`); may be given as a vector, if label boxes are to have different colors.
`vertex.border` | border color for vertices; may be given as a vector or a vertex attribute name, if vertex borders are to be of different colors.
`edge.lty` | line type for edge borders; may be given as a vector, adjacency matrix, or edge attribute name, if edge borders are to have different line types.
`label.lty` | line type for label boxes (if `boxed.labels==TRUE`); may be given as a vector, if label boxes are to have different line types.
`vertex.lty` | line type for vertex borders; may be given as a vector or a vertex attribute name, if vertex borders are to have different line types.
`edge.lwd` | line width scale for edges; if set greater than 0, edge widths are scaled by `edge.lwd*dat`. May be given as a vector, adjacency matrix, or edge attribute name, if edges are to have different line widths.
`label.lwd` | line width for label boxes (if `boxed.labels==TRUE`); may be given as a vector, if label boxes are to have different line widths.
`edge.len` | if `uselen==TRUE`, curved edge lengths are scaled by `edge.len`.
`edge.curve` | if `usecurve==TRUE`, the extent of edge curvature is controlled by `edge.curv`. May be given as a fixed value, vector, adjacency matrix, or edge attribute name, if edges are to have different levels of curvature.
`edge.steps` | for curved edges (excluding loops), the number of line segments to use for the curve approximation.
`loop.steps` | for loops, the number of line segments to use for the curve approximation.
`object.scale` | base length for plotting objects, as a fraction of the linear scale of the plotting region. Defaults to 0.01.
`uselen` | boolean; should we use `edge.len` to rescale edge lengths?
`usecurve` | boolean; should we use `edge.curve`?
`suppress.axes` | boolean; suppress plotting of axes?
`vertices.last` | boolean; plot vertices after plotting edges?
`new` | boolean; create a new plot? If `new==FALSE`, vertices and edges will be added to the existing plot.
`layout.par` | parameters to the `network.layout` function specified in `mode`.
`cex.main` | Character expansion for the plot title.
`cex.sub` | Character expansion for the plot sub-title.
`seed` | Integer for seeding random number generator. See `set.seed`.
`latent.control` | A list of parameters to control the `latent` and `latentPrior` models, `dyadsample` determines the size above which to sample the latent dyads; see `ergm` and `optim` for details.
`colornames` | A vector of color names that can be selected by index for the plot. By default it is `colors()`.
`verbose` | logical; if this is `TRUE`, we will print out more information as we run the function.
`latent` | logical; use a two-dimensional latent space model based on the MLE fit. See documentation for `ergmm()` in `latentnet`.
`...` | additional arguments to `plot`.

### Details

`plot.network` is a version of the standard network visualization tool within the `sna` package. By means of clever selection of display parameters, a fair amount of display flexibility can be obtained. Network layout – if not specified directly using `coord` – is determined via one of the various available algorithms. These are (briefly) as follows:

1. `latentPrior`: Use a two-dimensional latent space model based on a Bayesian minimum Kullback-Leibler fit. See documentation for `latent()` in `ergm`.

2. `random`: Vertices are placed (uniformly) randomly within a square region about the origin.

3. `circle`: Vertices are placed evenly about the unit circle.

4. `circrand`: Vertices are placed in a “Gaussian donut,” with distance from the origin following a normal distribution and angle relative to the X axis chosen (uniformly) randomly.

5. `eigen`, `princoord`: Vertices are placed via (the real components of) the first two eigenvectors of:

   1. `eigen`: the matrix of correlations among (concatenated) rows/columns of the adjacency matrix

   2. `princoord`: the raw adjacency matrix.

6. `mds`, `rmds`, `geodist`, `adj`, `seham`: Vertices are placed by a metric MDS. The distance matrix used is given by:

   1. `mds`: absolute row/column differences within the adjacency matrix

   2. `rmds`: Euclidean distances between rows of the adjacency matrix

   3. `geodist`: geodesic distances between vertices within the network

   4. `adj`: (max A)-A, where A is the raw adjacency matrix

   5. `seham`: structural (dis)equivalence distances (i.e., as per `sedist` in the package `sna`) based on the Hamming metric

7. `spring`, `springrepulse`: Vertices are placed using a simple spring embedder. Parameters for the embedding model are given by `embedder.params`, in the following order: vertex mass; equilibrium extension; spring coefficient; repulsion equilibrium distance; and base coefficient of friction. Initial vertex positions are in random order around a circle, and simulation proceeds – increasing the coefficient of friction by the specified base value per unit time – until “motion” within the system ceases. If `springrepulse` is specified, then an inverse-cube repulsion force between vertices is also simulated; this force is calibrated so as to be exactly equal to the force of a unit spring extension at a distance specified by the repulsion equilibrium distance.

### Value

None.

### Requires

`mva`

### Author(s)

Carter T. Butts buttsc@uci.edu

### References

Wasserman, S., and Faust, K. (1994). “Social Network Analysis: Methods and Applications.” Cambridge: Cambridge University Press.

### See Also

`plot`

### Examples

    data(florentine)
    plot(flomarriage)  #Plot the Florentine Marriage data
    plot(network(10))  #Plot a random network
    ## Not run: plot(flomarriage,interactive="points")

[Package ergm version 3.8.0 Index]