gplot.layout {sna} | R Documentation

## Vertex Layout Functions for gplot

### Description

Various functions which generate vertex layouts for the `gplot` visualization routine.

### Usage

    gplot.layout.adj(d, layout.par)
    gplot.layout.circle(d, layout.par)
    gplot.layout.circrand(d, layout.par)
    gplot.layout.eigen(d, layout.par)
    gplot.layout.fruchtermanreingold(d, layout.par)
    gplot.layout.geodist(d, layout.par)
    gplot.layout.hall(d, layout.par)
    gplot.layout.kamadakawai(d, layout.par)
    gplot.layout.mds(d, layout.par)
    gplot.layout.princoord(d, layout.par)
    gplot.layout.random(d, layout.par)
    gplot.layout.rmds(d, layout.par)
    gplot.layout.segeo(d, layout.par)
    gplot.layout.seham(d, layout.par)
    gplot.layout.spring(d, layout.par)
    gplot.layout.springrepulse(d, layout.par)
    gplot.layout.target(d, layout.par)

### Arguments

`d` | an adjacency matrix, as passed by `gplot`.
`layout.par` | a list of parameters.

### Details

Vertex layouts for network visualization pose a difficult problem – there is no single, ``good'' layout algorithm, and many different approaches may be valuable under different circumstances. With this in mind, `gplot` allows for the use of arbitrary vertex layout algorithms via the `gplot.layout.*` family of routines. When called, `gplot` searches for a `gplot.layout` function whose third name matches its `mode` argument (see `gplot` help for more information); this function is then used to generate the layout for the resulting plot. In addition to the routines documented here, users may add their own layout functions as needed. The requirements for a `gplot.layout` function are as follows:

1. the first argument, `d`, must be the (dichotomous) graph adjacency matrix;
2. the second argument, `layout.par`, must be a list of parameters (or `NULL`, if no parameters are specified); and
3. the return value must be a real matrix of dimension `c(2,NROW(d))`, whose rows contain the vertex coordinates.

Other than this, anything goes. (In particular, note that `layout.par` could be used to pass additional matrices, if needed.)

The `graph.layout` functions currently supplied by default are as follows:

circle
  This function places vertices uniformly in a circle; it takes no arguments.
eigen
  This function places vertices based on the eigenstructure of the adjacency matrix. It takes the following arguments:
  layout.par$var
    This argument controls the matrix to be used for the eigenanalysis. `"symupper"`, `"symlower"`, `"symstrong"`, `"symweak"` invoke `symmetrize` on `d` with the respective symmetrizing rule. `"user"` indicates a user-supplied matrix (see below), while `"raw"` indicates that `d` should be used as-is. (Defaults to `"raw"`.)
  layout.par$evsel
    If `"first"`, the first two eigenvectors are used; if `"size"`, the two eigenvectors whose eigenvalues have the largest magnitude are used instead. Note that only the real portion of the associated eigenvectors is used. (Defaults to `"first"`.)
  layout.par$mat
    If `layout.par\$var=="user"`, this matrix is used for the eigenanalysis. (No default.)
fruchtermanreingold
  This function generates a layout using a variant of Fruchterman and Reingold's force-directed placement algorithm. It takes the following arguments:
  layout.par$niter
    This argument controls the number of iterations to be employed. (Defaults to 500.)
  layout.par$max.delta
    Sets the maximum change in position for any given iteration. (Defaults to `NROW(d)`.)
  layout.par$area
    Sets the "area" parameter for the F-R algorithm. (Defaults to `NROW(d)^2`.)
  layout.par$cool.exp
    Sets the cooling exponent for the annealer. (Defaults to 3.)
  layout.par$repulse.rad
    Determines the radius at which vertex-vertex repulsion cancels out attraction of adjacent vertices. (Defaults to `area*NROW(d)`.)
  layout.par$seed.coord
    A two-column matrix of initial vertex coordinates. (Defaults to a random circular layout.)
hall
  This function places vertices based on the last two eigenvectors of the Laplacian of the input matrix (Hall's algorithm). It takes no arguments.
kamadakawai
  This function generates a vertex layout using a version of the Kamada-Kawai force-directed placement algorithm. It takes the following arguments:
  layout.par$niter
    This argument controls the number of iterations to be employed. (Defaults to 1000.)
  layout.par$sigma
    Sets the base standard deviation of position change proposals. (Defaults to `NROW(d)/4`.)
  layout.par$initemp
    Sets the initial "temperature" for the annealing algorithm. (Defaults to 10.)
  layout.par$cool.exp
    Sets the cooling exponent for the annealer. (Defaults to 0.99.)
  layout.par$kkconst
    Sets the Kamada-Kawai vertex attraction constant. (Defaults to `NROW(d)^2`.)
  layout.par$elen
    Provides the matrix of interpoint distances to be approximated. (Defaults to the geodesic distances of `d` after symmetrizing, capped at `sqrt(NROW(d))`.)
  layout.par$seed.coord
    A two-column matrix of initial vertex coordinates. (Defaults to a gaussian layout.)
mds
  This function places vertices based on a metric multidimensional scaling of a specified distance matrix. It takes the following arguments:
  layout.par$var
    This argument controls the raw variable matrix to be used for the subsequent distance calculation and scaling. `"rowcol"`, `"row"`, and `"col"` indicate that the rows and columns (concatenated), rows, or columns (respectively) of `d` should be used. `"rcsum"` and `"rcdiff"` result in the sum or difference of `d` and its transpose being employed. `"invadj"` indicates that `max{d}-d` should be used, while `"geodist"` uses `geodist` to generate a matrix of geodesic distances from `d`. Alternately, an arbitrary matrix can be provided using `"user"`. (Defaults to `"rowcol"`.)
  layout.par$dist
    The distance function to be calculated on the rows of the variable matrix. This must be one of the `method` parameters to `\list{dist}` (`"euclidean"`, `"maximum"`, `"manhattan"`, or `"canberra"`), or else `"none"`. In the latter case, no distance function is calculated, and the matrix in question must be square (with dimension `dim(d)`) for the routine to work properly. (Defaults to `"euclidean"`.)
  layout.par$exp
    The power to which distances should be raised prior to scaling. (Defaults to 2.)
  layout.par$vm
    If `layout.par\$var=="user"`, this matrix is used for the distance calculation. (No default.)

  Note: the following layout functions are based on `mds`:

  adj
    scaling of the raw adjacency matrix, treated as similarities (using `"invadj"`).
  geodist
    scaling of the matrix of geodesic distances.
  rmds
    euclidean scaling of the rows of `d`.
  segeo
    scaling of the squared euclidean distances between row-wise geodesic distances (i.e., approximate structural equivalence).
  seham
    scaling of the Hamming distance between rows/columns of `d` (i.e., another approximate structural equivalence scaling).
princoord
  This function places vertices based on the eigenstructure of a given correlation/covariance matrix. It takes the following arguments:
  layout.par$var
    The matrix of variables to be used for the correlation/covariance calculation. `"rowcol"`, `"col"`, and `"row"` indicate that the rows/cols, columns, or rows (respectively) of `d` should be employed. `"rcsum"` `"rcdiff"` result in the sum or difference of `d` and `t(d)` being used. `"user"` allows for an arbitrary variable matrix to be supplied. (Defaults to `"rowcol"`.)
  layout.par$cor
    Should the correlation matrix (rather than the covariance matrix) be used? (Defaults to `TRUE`.)
  layout.par$vm
    If `layout.par\$var=="user"`, this matrix is used for the correlation/covariance calculation. (No default.)
random
  This function places vertices randomly. It takes the following argument:
  layout.par$dist
    The distribution to be used for vertex placement. Currently, the options are `"unif"` (for uniform distribution on the square), `"uniang"` (for a ``gaussian donut'' configuration), and `"normal"` (for a straight Gaussian distribution). (Defaults to `"unif"`.)

  Note: `circrand`, which is a frontend to the `"uniang"` option, is based on this function.

spring
  This function places vertices using a spring embedder. It takes the following arguments:
  layout.par$mass
    The vertex mass (in ``quasi-kilograms''). (Defaults to `0.1`.)
  layout.par$equil
    The equilibrium spring extension (in ``quasi-meters''). (Defaults to `1`.)
  layout.par$k
    The spring coefficient (in ``quasi-Newtons per quasi-meter''). (Defaults to `0.001`.)
  layout.par$repeqdis
    The point at which repulsion (if employed) balances out the spring extension force (in ``quasi-meters''). (Defaults to `0.1`.)
  layout.par$kfr
    The base coefficient of kinetic friction (in ``quasi-Newton quasi-kilograms''). (Defaults to `0.01`.)
  layout.par$repulse
    Should repulsion be used? (Defaults to `FALSE`.)

  Note: `springrepulse` is a frontend to `spring`, with repulsion turned on.

target
  This function produces a "target diagram" or "bullseye" layout, using a Brandes et al.'s force-directed placement algorithm. (See also `gplot.target`.) It takes the following arguments:
  layout.par$niter
    This argument controls the number of iterations to be employed. (Defaults to 1000.)
  layout.par$radii
    This argument should be a vector of length `NROW(d)` containing vertex radii. Ideally, these should lie in the [0,1] interval (and odd behavior may otherwise result). (Defaults to the affine-transformed Freeman `degree` centrality scores of `d`.)
  layout.par$minlen
    Sets the minimum edge length, below which edge lengths are to be adjusted upwards. (Defaults to 0.05.)
  layout.par$area
    Sets the initial "temperature" for the annealing algorithm. (Defaults to 10.)
  layout.par$cool.exp
    Sets the cooling exponent for the annealer. (Defaults to 0.99.)
  layout.par$maxdelta
    Sets the maximum angular distance for vertex moves. (Defaults to `pi`.)
  layout.par$periph.outside
    Boolean; should "peripheral" vertices (in the Brandes et al. sense) be placed together outside the main target area? (Defaults to `FALSE`.)
  layout.par$periph.outside.offset
    Radius at which to place "peripheral" vertices if `periph.outside==TRUE`. (Defaults to 1.2.)
  layout.par$disconst
    Multiplier for the Kamada-Kawai-style distance potential. (Defaults to 1.)
  layout.par$crossconst
    Multiplier for the edge crossing potential. (Defaults to 1.)
  layout.par$repconst
    Multiplier for the vertex-edge repulsion potential. (Defaults to 1.)
  layout.par$minpdis
    Sets the "minimum distance" parameter for vertex repulsion. (Defaults to 0.05.)

### Value

A matrix whose rows contain the x,y coordinates of the vertices of `d`.

### Author(s)

Carter T. Butts buttsc@uci.edu

### References

Brandes, U.; Kenis, P.; and Wagner, D. (2003). ``Communicating Centrality in Policy Network Drawings.'' IEEE Transactions on Visualization and Computer Graphics, 9(2):241-253.

Fruchterman, T.M.J. and Reingold, E.M. (1991). ``Graph Drawing by Force-directed Placement.'' Software - Practice and Experience, 21(11):1129-1164.

Kamada, T. and Kawai, S. (1989). ``An Algorithm for Drawing General Undirected Graphs.'' Information Processing Letters, 31(1):7-15.

### See Also

`gplot`, `gplot.target`, `gplot3d.layout`, `cmdscale`, `eigen`

[Package sna version 1.1 Index]