gplot3d.layout: Vertex Layout Functions for gplot3d

Description

Various functions which generate vertex layouts for the gplot3d visualization routine.

Usage

gplot3d.layout.adj(d, layout.par)
gplot3d.layout.eigen(d, layout.par)
gplot3d.layout.fruchtermanreingold(d, layout.par)
gplot3d.layout.geodist(d, layout.par)
gplot3d.layout.hall(d, layout.par)
gplot3d.layout.kamadakawai(d, layout.par)
gplot3d.layout.mds(d, layout.par)
gplot3d.layout.princoord(d, layout.par)
gplot3d.layout.random(d, layout.par)
gplot3d.layout.rmds(d, layout.par)
gplot3d.layout.segeo(d, layout.par)
gplot3d.layout.seham(d, layout.par)

Arguments

an adjacency matrix, as passed by gplot3d.

layout.par

a list of parameters.

Value

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

Details

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

the first argument, d, must be the (dichotomous) graph adjacency matrix;
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(3,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 gplot3d.layout functions currently supplied by default are as follows:

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 three eigenvectors are used; if "size", the three 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 300.)

layout.par\$max.delta

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

layout.par\$volume

Sets the "volume" parameter for the F-R algorithm. (Defaults to NROW(d)^3.)

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 volume*NROW(d).)

layout.par\$seed.coord

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

hall

This function places vertices based on the last three 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)^3.)

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 three-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 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 unit cube), "uniang" (for a ``gaussian sphere'' configuration), and "normal" (for a straight Gaussian distribution). (Defaults to "unif".)

References

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.