layout                package:igraph                R Documentation

_G_e_n_e_r_a_t_e _c_o_o_r_d_i_n_a_t_e_s _f_o_r _p_l_o_t_t_i_n_g _g_r_a_p_h_s

_D_e_s_c_r_i_p_t_i_o_n:

     Some simple and not so simple functions determining the placement
     of the vertices for drawing a graph.

_U_s_a_g_e:

     layout.random(graph, params, dim=2)
     layout.circle(graph, params)
     layout.sphere(graph, params)
     layout.fruchterman.reingold(graph, ..., dim=2,
           verbose=igraph.par("verbose"), params)
     layout.kamada.kawai(graph, ..., dim=2,
           verbose=igraph.par("verbose"), params)
     layout.spring(graph, ..., params)
     layout.reingold.tilford(graph, ..., params)
     layout.fruchterman.reingold.grid(graph, ...,
           verbose=igraph.par("verbose"), params)
     layout.lgl(graph, ..., params)
     layout.graphopt(graph, ..., verbose = igraph.par("verbose"), params = list())
     layout.mds(graph, d=shortest.paths(graph), ...)
     layout.svd(graph, d=shortest.paths(graph), ...)
     layout.norm(layout, xmin = NULL, xmax = NULL, ymin = NULL, ymax = NULL,
           zmin = NULL, zmax = NULL)

_A_r_g_u_m_e_n_t_s:

   graph: The graph to place.

  params: The list of function dependent parameters.

     dim: Numeric constant, either 2 or 3. Some functions are able to
          generate 2d and 3d layouts as well, supply this argument to
          change the default behavior.

     ...: Function dependent parameters, this is an alternative
          notation to the 'params' argument.

 verbose: Logial constant, whether to show a progress bar while
          calculating the layout.

       d: The matrix used for multidimansional scaling. By default it
          is the distance matrix of the graph.

  layout: A matrix with two or three columns, the layout to normalize.

xmin,xmax: The limits for the first coordinate, if one of them or both
          are 'NULL' then no normalization is performed along this
          direction.

ymin,ymax: The limits for the second coordinate, if one of them or both
          are 'NULL' then no normalization is performed along this
          direction.

zmin,zmax: The limits for the third coordinate, if one of them or both
          are 'NULL' then no normalization is performed along this
          direction.

_D_e_t_a_i_l_s:

     These functions calculate the coordinates of the vertices for a
     graph usually based on some optimality criterion.

     'layout.random' simply places the vertices randomly on a square.
     It has no parameters.

     'layout.circle' places the vertices on a unit circle
     equidistantly. It has no paramaters.

     'layout.sphere' places the vertices (approximately) uniformly on
     the surface of a sphere, this is thus a 3d layout. It is not clear
     however what "uniformly on a sphere" means.

     'layout.fruchterman.reingold' uses a force-based algorithm
     proposed by Fruchterman and Reingold, see references. Parameters
     and their default values:

   _n_i_t_e_r Numeric, the number of iterations to perform (500).

   _c_o_o_l_e_x_p Numeric, the cooling exponent for the simulated annealing
        (3).

   _m_a_x_d_e_l_t_a Maximum change ('vcount(graph)').

   _a_r_e_a Area parameter ('vcount(graph)^2').

   _r_e_p_u_l_s_e_r_a_d Cancellation radius ('area'*vcount(graph)).

   _w_e_i_g_h_t_s A vector giving edge weights or 'NULL'. If not 'NULL' then
        the attraction along the edges will be multiplied by the given
        edge weights ('NULL').

     This function was ported from the SNA package.

     'layout.kamada.kawai' is another force based algorithm. 
     Parameters and default values:

   _n_i_t_e_r Number of iterations to perform (1000).

   _s_i_g_m_a Sets the base standard deviation of position change proposals
        (vcount(graph)/4).

   _i_n_i_t_e_m_p The initial temperature (10).

   _c_o_o_l_e_x_p The cooling exponent (0.99).

   _k_k_c_o_n_s_t Sets the Kamada-Kawai vertex attraction constant
        (vcount(graph)**2).

     This function performs very well for connected graphs, but it
     gives poor results for unconnected ones. This function was ported
     from the SNA package.

     'layout.spring' is a spring embedder algorithm. Parameters and
     default values:

   _m_a_s_s The vertex mass (in 'quasi-kilograms'). (Defaults to 0.1.)

   _e_q_u_i_l The equilibrium spring extension (in 'quasi-meters').
        (Defaults to 1.)

   _k The spring coefficient (in 'quasi-Newtons per quasi-meter').
        (Defaults to 0.001.)

   _r_e_p_e_q_d_i_s The point at which repulsion (if employed) balances out the
        spring extension force (in 'quasi-meters'). (Defaults to 0.1.)

   _k_f_r The base coefficient of kinetic friction (in 'quasi-Newton
        quasi-kilograms'). (Defaults to 0.01.)

   _r_e_p_u_l_s_e Should repulsion be used? (Defaults to FALSE.)

     This function was ported from the SNA package.

     'layout.reingold.tilford' generates a tree-like layout, so it is
     mainly for trees. Parameters and default values:

   _r_o_o_t The id of the root vertex, defaults to 0.

   _c_i_r_c_u_l_a_r Logical scalar, whether to plot the tree in a circular
        fashion, defaults to 'FALSE'.

     'layout.fruchterman.reingold.grid' is similar to
     'layout.fruchterman.reingold' but repelling force is calculated
     only between vertices that are closer to each other than a limit,
     so it is faster. Patameters and default values:

   _n_i_t_e_r Numeric, the number of iterations to perform (500).

   _m_a_x_d_e_l_t_a Maximum change for one vertex in one iteration. (The number
        of vertices in the graph.)

   _a_r_e_a The area of the surface on which the vertices are placed. (The
        square of the number of vertices.)

   _c_o_o_l_e_x_p The cooling exponent of the simulated annealing (1.5).

   _r_e_p_u_l_s_e_r_a_d Cancellation radius for the repulsion (the 'area' times
        the number of vertices).

   _c_e_l_l_s_i_z_e The size of the cells for the grid. When calculating the
        repulsion forces between vertices only vertices in the same or
        neighboring grid cells are taken into account (the fourth root
        of the number of 'area'.

     'layout.lgl' is for large connected graphs, it is similar to the
     layout generator of the Large Graph Layout software (<URL:
     http://bioinformatics.icmb.utexas.edu/lgl>). Parameters and
     default values:

   _m_a_x_i_t_e_r The maximum number of iterations to perform (150).

   _m_a_x_d_e_l_t_a The maximum change for a vertex during an iteration (the
        number of vertices).

   _a_r_e_a The area of the surface on which the vertices are placed
        (square of the number of vertices). 

   _c_o_o_l_e_x_p The cooling exponent of the simulated annealing (1.5).

   _r_e_p_u_l_s_e_r_a_d Cancellation radius for the repulsion (the 'area' times
        the number of vertices).

   _c_e_l_l_s_i_z_e The size of the cells for the grid. When calculating the
        repulsion forces between vertices only vertices in the same or
        neighboring grid cells are taken into account (the fourth root
        of the number of 'area'.

   _r_o_o_t The id of the vertex to place at the middle of the layout. The
        default value is -1 which means that a random vertex is
        selected.

     'layout.graphopt' is a port of the graphopt layout algorithm by
     Michael Schmuhl. graphopt version 0.4.1 was rewritten in C and the
     support for layers was removed (might be added later) and a code
     was a bit reorganized to avoid some unneccessary steps is the node
     charge (see below) is zero.

     graphopt uses physical analogies for defining attracting and
     repelling  forces among the vertices and then the physical system
     is simulated  until it reaches an equilibrium. (There is no
     simulated annealing or  anything like that, so a stable fixed
     point is not guaranteed.)

     See also <URL: http://www.schmuhl.org/graphopt/> for the original
     graphopt.

     Parameters and default values:

   _n_i_t_e_r Integer scalar, the number of iterations to perform. Should be
        a couple of hundred in general. If you have a large graph  then
        you might want to only do a few iterations and then check the 
        result. If it is not good enough you can feed it in again in 
        the 'start' argument. The default value is 500.

   _c_h_a_r_g_e The charge of the vertices, used to calculate electric
        repulsion. The default is 0.001.

   _m_a_s_s The mass of the vertices, used for the spring forces. The
        default is 30.

   _s_p_r_i_n_g._l_e_n_g_t_h The length of the springs, an integer number. The
        default value is zero.

   _s_p_r_i_n_g._c_o_n_s_t_a_n_t The spring constant, the default value is one.

   _m_a_x._s_a._m_o_v_e_m_e_n_t Real constant, it gives the maximum amount of
        movement allowed in a single step along a single axis. The
        default value is 5.

   _s_t_a_r_t If given, then it should be a matrix with two columns and one
        line for each vertex. This matrix will be used as starting
        positions for the algorithm. If not given, then a random
        starting matrix is used.

     'layout.mds' uses metric multidimensional scaling for generating
     the coordinates. This function does not have the usual 'params'
     argument. It can just take a single argument, the distance matrix
     used for multidimensional scaling. This function generates the
     layout separately for each graph component and then merges them
     via 'layout.merge'. 'layout.mds' is an _experimental_ function
     currently.

     'layout.svd' is a currently _experimental_ layout function based
     on singular value decomposition. It does not have the usual
     'params' argument, but take a single argument, the distance matrix
     of the graph. This function generates the layout separately for
     each graph component and then merges them via 'layout.merge'.

     'layout.norm' normalizes a layout, it linearly transforms each
     coordinate separately to fit into the given limits.

     'layout.drl' is another force-driven layout generator, it is
     suitable for quite large graphs. See 'layout.drl' for details.

_V_a_l_u_e:

     All these functions return a numeric matrix with at least two
     columns and the same number of lines as the number of vertices.

_A_u_t_h_o_r(_s):

     Gabor Csardi csardi@rmki.kfki.hu

_R_e_f_e_r_e_n_c_e_s:

     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. 

     Reingold, E and Tilford, J (1981). Tidier drawing of trees. _IEEE
     Trans. on Softw. Eng._, SE-7(2):223-228.

_S_e_e _A_l_s_o:

     'layout.drl', 'plot.igraph', 'tkplot'

_E_x_a_m_p_l_e_s:

     g <- graph.ring(10)
     layout.random(g)
     layout.kamada.kawai(g)

