network.layout: Vertex Layout Functions for plot.network

Description

Various functions which generate vertex layouts for the plot.network visualization routine.

Usage

network.layout.circle(nw, layout.par)
network.layout.fruchtermanreingold(nw, layout.par)
network.layout.kamadakawai(nw, layout.par)

Arguments

a network object, as passed by plot.network.

layout.par

a list of parameters.

Value

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

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, plot.network allows for the use of arbitrary vertex layout algorithms via the network.layout.* family of routines. When called, plot.network searches for a network.layout function whose fourth name matches its mode argument (see plot.network 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 network.layout function are as follows:

the first argument, nw, must be a network object;
the second argument, layout.par, must be a list of parameters (or NULL, if no parameters are specified); and
the return value must be a real matrix of dimension c(2,network.size(nw)), whose rows contain the vertex coordinates.

Other than this, anything goes. (In particular, note that layout.par could be used to pass additional matrices or other information, if needed. Alternately, it is possible to make layout methods that respond to covariates on the network object, which are maintained intact by plot.network.) The network.layout functions currently supplied by default are as follows (with n==network.size(nw)):

circle: This function places vertices uniformly in a circle; it takes no arguments.

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. Larger values take longer, but will provide a more refined layout. (Defaults to 500.)

layout.par\$max.delta

Sets the maximum change in position for any given iteration. (Defaults to n.)

layout.par\$area

Sets the "area" parameter for the F-R algorithm. (Defaults to n^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*log(n).)

layout.par\$ncell

To speed calculations on large graphs, the plot region is divided at each iteration into ncell by ncell “cells”, which are used to define neighborhoods for force calculation. Moderate numbers of cells result in fastest performance; too few cells (down to 1, which produces “pure” F-R results) can yield odd layouts, while too many will result in long layout times. (Defaults to n^0.4.)

layout.par\$cell.jitter

Jitter factor (in units of cell width) used in assigning vertices to cells. Small values may generate “grid-like” anomalies for graphs with many isolates. (Defaults to 0.5.)

layout.par\$cell.pointpointrad

Squared “radius” (in units of cells) such that exact point interaction calculations are used for all vertices belonging to any two cells less than or equal to this distance apart. Higher values approximate the true F-R solution, but increase computational cost. (Defaults to 0.)

layout.par\$cell.pointcellrad

Squared “radius” (in units of cells) such that approximate point/cell interaction calculations are used for all vertices belonging to any two cells less than or equal to this distance apart (and not within the point/point radius). Higher values provide somewhat better approximations to the true F-R solution at slightly increased computational cost. (Defaults to 18.)

layout.par\$cell.cellcellrad

Squared “radius” (in units of cells) such that approximate cell/cell interaction calculations are used for all vertices belonging to any two cells less than or equal to this distance apart (and not within the point/point or point/cell radii). Higher values provide somewhat better approximations to the true F-R solution at slightly increased computational cost. Note that cells beyond this radius (if any) do not interact, save through edge attraction. (Defaults to ncell^2.)

layout.par\$seed.coord

A two-column matrix of initial vertex coordinates. (Defaults to a random circular layout.)

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 n/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 n)^2.)

layout.par\$elen

Provides the matrix of interpoint distances to be approximated. (Defaults to the geodesic distances of nw after symmetrizing, capped at sqrt(n).)

layout.par\$seed.coord

A two-column matrix of initial vertex coordinates. (Defaults to a gaussian layout.)

References

Butts, C. T. (2008). “network: a Package for Managing Relational Data in R.” Journal of Statistical Software, 24(2). http://www.jstatsoft.org/v24/i02/

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