Drawing graphs            package:igraph            R Documentation

_D_r_a_w_i_n_g _g_r_a_p_h_s

_D_e_s_c_r_i_p_t_i_o_n:

     The common bits of the three plotting functions 'plot.igraph',
     'tkplot' and 'rglplot' are discussed in this manual page

_D_e_t_a_i_l_s:

     There are currently three different functions in the igraph
     package which can draw graph in various ways:

     'plot.igraph' does simple non-interactive 2D plotting to R
     devices. Actually it is an implementation of the 'plot' generic
     function,  so you can write 'plot(graph)' instead of
     'plot.igraph(graph)'. As it used the standard R devices it
     supports every output format for which R has an output device. The
     list is quite impressing: PostScript, PDF files, XFig files, SVG
     files, JPG, PNG and of course you can plot to the screen as well
     using the default devices, or the good-looking anti-aliased Cairo
     device. See 'plot.igraph' for some more information.

     'tkplot' does interactive 2D plotting using the 'tcltk' package.
     It can only handle graphs of moderate size, a thousend vertices is
     probably already too many. Some parameters of the plotted graph
     can be changed interactively after issuing the 'tkplot' command:
     the position, color and size of the vertices and the color and
     width of the edges. See 'tkplot' for details.

     'rglplot' is an experimental function to draw graphs in 3D using
     OpenGL. See 'rglplot' for some more information.

     Please also check the examples below.

_H_o_w _t_o _s_p_e_c_i_f_y _g_r_a_p_h_i_c_a_l _p_a_r_a_m_e_t_e_r_s:

     There are three ways to give values to the parameters described
     below, in section 'Parameters'. We give these three ways here in
     the order of their precedence. 

     The first method is to supply named arguments to the plotting
     commands: 'plot.igraph', 'tkplot' or 'rglplot'. Parameters for
     vertices start with prefix ''vertex.'', parameters for edges have
     prefix ''edge.'', and global parameters have now prefix. Eg. the
     color of the vertices can be given via argument 'vertex.color',
     whereas 'edge.color' sets the color of the edges. 'layout' gives
     the layout of the graphs.

     The second way is to assign vertex, edge and graph attributes to
     the graph. These attributes have now prefix, ie. the color of the
     vertices is taken from the 'color' vertex attribute and the color
     of the edges from the 'color' edge attribute. The layout of the
     graph is given by the 'layout' graph attribute. (Always assuming
     that the corresponding command argument is not present.) Setting
     vertex and edge attributes are handy if you want to assign a given
     'look' to a graph, attributes are saved with the graph is you save
     it with 'save' or in GraphML format with 'write.graph', so the
     graph will have the same look after loading it again.

     If a parameter is not given in the command line, and the
     corresponding vertex/edge/graph attribute is also missing then the
     general igraph parameters handled by 'igraph.par' are also
     checked. Vertex parameters have prefix ''vertex.'', edge
     parameters are prefixed with ''edge.'', general parameters like
     'layout' are prefixed with ''plot''. These parameters are useful
     if you want all or most of your graphs to have the same look,
     vertex size, vertex color, etc. Then you don't need to set these
     at every plotting, and you also don't need to assign vertex/edge
     attributes to every graph.

     If the value of a parameter is not specified by any of the three
     ways described here, its default valued is used, as given in the
     source code.

     Different parameters can have different type, eg. vertex colors
     can be given as a character vector with color names, or as an
     integer vector with the color numbers from the current palette.
     Different types are valid for different parameters, this is
     discussed in detail in the next section. It is however always true
     that the parameter can always be a function object in which it
     will be called with the graph as its single argument to get the
     "proper" value of the parameter. (If the function returns another
     function object that will _not_ be called again...)

_T_h_e _l_i_s_t _o_f _p_a_r_a_m_e_t_e_r_s:

     Vertex parameters first, note that the ''vertex.'' prefix needs to
     be added if they are used as an argument or when setting via
     'igraph.par'. The value of the parameter may be scalar valid for
     every vertex or a vector with a separate value for each vertex.
     (Shorter vectors are recycled.)

   _s_i_z_e The size of the vertex, a numeric scalar or vector, in the
        latter case each vertex sizes may differ. This vertex sizes are
        scaled in order have about the same size of vertices for a
        given value for all three plotting commands. It does not need
        to be an integer number.

        The default value is 15. This is big enough to place short
        labels on vertices.

   _s_i_z_e_2 The "other" size of the vertex, for some vertex shapes. For
        the various rectangle shapes this gives the height of the
        vertices, whereas 'size' gives the width. It is ignored by
        shapes for which the size can be specified with a single
        number.

        The default is 15.

   _c_o_l_o_r The fill color of the vertex. If it is numeric then the
        current palette is used, see 'palette'. If it is a character
        vector then it may either contain named colors or RGB specified
        colors with three or four bytes. All strings starting with
        ''#'' are assumed to be RGB color specifications. It is
        possible to mix named color and RGB colors. Note that 'tkplot'
        ignores the fourth byte (alpha channel) in the RGB color
        specification.

        The default value is "'SkyBlue2'".

   _f_r_a_m_e._c_o_l_o_r The color of the frame of the vertices, the same formats
        are allowed as for the fill color.

        By default it is "black".

   _s_h_a_p_e The shape of the vertex, currently "'circle'", "'square'",
        "'csquare'", "'rectangle'", "'crectangle'", "'vrectangle'" and
        "'none'" are supported, and only by the 'plot.igraph' command.
        "'none'" does not draw the vertices at all, although vertex
        label are plotted (if given). See 'igraph.vertex.shapes' for
        details about vertex shapes.

        By default vertices are drawn as circles.

   _l_a_b_e_l The vertex labels. They will be converted to character.
        Specify 'NA' to omit vertex labels.

        The default vertex labels are the vertex ids.

   _l_a_b_e_l._f_a_m_i_l_y The font family to be used for vertex labels. As
        different plotting commands can used different fonts, they
        interpret this parameter different ways. The basic notation is,
        however, understood by both 'plot.igraph' and 'tkplot'.
        'rglplot' does not support fonts at all right now, it ignores
        this parameter completely.

        For 'plot.igraph' this parameter is simply passed to 'text' as
        argument 'family'.

        For 'tkplot' some conversion is performed. If this parameter is
        the name of an exixting Tk font, then that font is used and the
        'label.font' and 'label.cex' parameters are ignored complerely.
        If it is one of the base families (serif, sans, mono) then
        Times, Helvetica or Courier fonts are used, there are
        guaranteed to exist on all systems. For the 'symbol' base
        family we used the symbol font is available, otherwise the
        first font which has 'symbol' in its name. If the parameter is
        not a name of the base families and it is also not a named Tk
        font then we pass it to 'tkfont.create' and hope the user knows
        what she is doing. The 'label.font' and 'label.cex' parameters
        are also passed to 'tkfont.create' in this case.

        The default value is 'serif'.

   _l_a_b_e_l._f_o_n_t The font within the font family to use for the vertex
        labels. It is interpreted the same way as the the 'font'
        graphical parameter: 1 is plain text, 2 is bold face, 3 is
        italic, 4 is bold and italic and 5 specifies the symbol font.

        For 'plot.igraph' this parameter is simply passed to 'text'.

        For 'tkplot', if the 'label.family' parameter is not the name
        of a Tk font then this parameter is used to set whether the
        newly created font should be italic and/or boldface. Otherwise
        it is ignored.

        For 'rglplot' it is ignored.

        The default value is 1.

   _l_a_b_e_l._c_e_x The font size for vertex labels. It is interpreted as a
        multiplication factor of some device-dependent base font size.

        For 'plot.igraph' it is simply passed to 'text' as argument
        'cex'.

        For 'tkplot' it is multiplied by 12 and then used as the 'size'
        argument for 'tkfont.create'. The base font is thus 12 for
        tkplot.

        For 'rglplot' it is ignored.

        The default value is 1.

   _l_a_b_e_l._d_i_s_t The distance of the label from the center of the vertex.
        If it is 0 then the label is centered on the vertex. If it is 1
        then the label is displayed beside the vertex.

        The default value is 0.

   _l_a_b_e_l._d_e_g_r_e_e It defines the position of the vertex labels, relative
        to the center of the vertices. It is interpreted as an angle in
        radian, zero means 'to the right', and ''pi'' means to the
        left, up is '-pi/2' and down is 'pi/2'.

        The default value is '-pi/4'.

   _l_a_b_e_l._c_o_l_o_r The color of the labels, see the 'color' vertex
        parameter discussed earlier for the possible values.

        The default value is 'black'. 

     Edge parameters require to add the ''edge.'' prefix when used as
     arguments or set by 'igraph.par'. The edge parameters:

   _c_o_l_o_r The color of the edges, see the 'color' vertex parameter for
        the possible values.

        By default this parameter is 'darkgrey'.

   _w_i_d_t_h The width of the edges.

        The default value is 1.

   _a_r_r_o_w._s_i_z_e The size of the arrows. Currently this is a constant, so
        it is the same for every edge. If a vector is submitted then
        only the first element is used, ie. if this is taken from an
        edge attribute then only the attribute of the first edge is
        used for all arrows. This will likely change in the future.

        The default value is 1.

   _a_r_r_o_w._w_i_d_t_h The width of the arrows. Currently this is a constant,
        so it is the same for every edge. If a vector is submitted then
        only the first element is used, ie. if this is taken from an
        edge attribute then only the attribute of the first edge is
        used for all arrows. This will likely change in the future.

        This argument is currently only used by 'plot.igraph'.

        The default value is 1, which gives the same width as before
        this option appeared in igraph.

   _l_t_y The line type for the edges. Almost the same format is accepted
        as for the standard graphics 'par', 0 and "blank" mean no
        edges, 1 and "solid" are for solid lines, the other possible
        values are: 2 ("dashed"), 3 ("dotted"), 4 ("dotdash"), 5
        ("longdash"), 6 ("twodash").

        'tkplot' also accepts standard Tk line type strings, it does
        not however support "blank" lines, instead of type '0' type
        '1', ie. solid lines will be drawn.

        This argument is ignored for 'rglplot'.

        The default value is type 1, a solid line.

   _l_a_b_e_l The edge labels. They will be converted to character. Specify
        'NA' to omit edge labels.

        Edge labels are omitted by default.

   _l_a_b_e_l._f_a_m_i_l_y Font family of the edge labels. See the vertex
        parameter with the same name for the details.

   _l_a_b_e_l._f_o_n_t The font for the edge labels. See the corresponding
        vertex parameter discussed earlier for details.

   _l_a_b_e_l._c_e_x The font size for the edge labels, see the corresponding
        vertex parameter for details.

   _l_a_b_e_l._c_o_l_o_r The color of the edge labels, see the 'color' vertex
        parameters on how to specify colors. 

   _c_u_r_v_e_d Specifies whether to draw curved edges, or not. This can be a
        logical or a numeric vector or scalar.

        First the vector is replicated to have the same length as the
        number of edges in the graph. Then it is interpreted for each
        edge separately. A numeric value specifies the curvature of the
        edge; zero curvature means straight edges, negative values
        means the edge bends clockwise, positive values the opposite.
        'TRUE' means curvature 0.5, 'FALSE' means curvature zero.

        This parameter is ignored for loop edges.

        The default value is 'FALSE'.

        This parameter is currently ignored by 'rglplot'.

   _a_r_r_o_w._m_o_d_e This parameter can be used to specify for which edges
        should arrows be drawn. If this parameter is given by the user
        (in either of the three ways) then it specifies which edges
        will have forward, backward arrows, or both, or no arrows at
        all. As usual, this parameter can be a vector or a scalar
        value. It can be an integer or character type. If it is integer
        then 0 means no arrows, 1 means backward arrows, 2 is for
        forward arrows and 3 for both. If it is a character vector then
        "<" and "<-" specify backward, ">" and "->" forward arrows and
        "<>" and "<->" stands for both arrows. All other values mean no
        arrows, perhaps you should use "-" or "-" to specify no arrows.

        Hint: this parameter can be used as a 'cheap' solution for
        drawing "mixed" graphs: graphs in which some edges are directed
        some are not. If you want do this, then please create a
        _directed_ graph, because as of version 0.4 the vertex pairs in
        the edge lists can be swapped in undirected graphs.

        By default, no arrows will be drawn for undirected graphs, and
        for  directed graphs, an arrow will be drawn for each edge,
        according to its direction. This is not very surprising, it is
        the expected behavior.

   _l_o_o_p._a_n_g_l_e Gives the angle in radian for plotting loop edges. See
        the 'label.dist' vertex parameter to see how this is
        interpreted.

        The default value is 0. 

   _l_o_o_p._a_n_g_l_e_2 Gives the second angle in radian for plotting loop
        edges. This is only used in 3D, 'loop.angle' is enough in 2D.

        The default value is 0.


     Other parameters:

   _l_a_y_o_u_t Either a function or a numeric matrix. It specifies how the
        vertices will be placed on the plot.

        If it is a numeric matrix, then the matrix has to have one line
        for each vertex, specifying its coordinates. The matrix should
        have at least two columns, for the 'x' and 'y' coordinates, and
        it can also have third column, this will be the 'z' coordinate
        for 3D plots and it is ignored for 2D plots.

        If a two column matrix is given for the 3D plotting function
        'rglplot' then the third column is assumed to be 1 for each
        vertex.

        If 'layout' is a function, this function will be called with
        the 'graph' as the single parameter to determine the actual
        coordinates. The function should return a matrix with two or
        three columns. For the 2D plots the third column is ignored.

        The default value is 'layout.random', ie. a function returning
        with 2D random placement.

   _m_a_r_g_i_n The amount of empty space below, over, at the left and right
        of the plot, it is a numeric vector of length four. Usually
        values between 0 and 0.5 are meaningful, but negative values
        are also possible, that will make the plot zoom in to a part of
        the graph. If it is shorter than four then it is recycled.

        'rglplot' does not support this parameter, as it can zoom in
        and out the graph in a more flexible way.

        Its default value is 0.

   _r_e_s_c_a_l_e Logical constant, whether to rescale the coordinates to the
        [-1,1]x[-1,1](x[-1,1]) interval. This parameter is not
        implemented for 'tkplot'.

        Defaults to 'TRUE', the layout will be rescaled.

   _a_s_p A numeric constant, it gives the 'asp' parameter for 'plot', the
        aspect ratio. Supply 0 here if you don't want to give an aspect
        ratio. It is ignored by 'tkplot' and 'rglplot'.

        Defaults to 1.

   _f_r_a_m_e Boolean, whether to plot a frame around the graph. It is
        ignored by 'tkplot' and 'rglplot'.

        Defaults to 'FALSE'.


_A_u_t_h_o_r(_s):

     Gabor Csardi csardi@rmki.kfki.hu

_S_e_e _A_l_s_o:

     'plot.igraph', 'tkplot', 'rglplot', 'igraph.par'

_E_x_a_m_p_l_e_s:

     ## Not run: 

     # plotting a simple ring graph, all default parameters, except the layout
     g <- graph.ring(10)
     g$layout <- layout.circle
     plot(g)
     tkplot(g)
     rglplot(g)

     # plotting a random graph, set the parameters in the command arguments
     g <- barabasi.game(100)
     plot(g, layout=layout.fruchterman.reingold, vertex.size=4,
          vertex.label.dist=0.5, vertex.color="red", edge.arrow.size=0.5)

     # plot a random graph, different color for each component
     g <- erdos.renyi.game(100, 1/100)
     comps <- clusters(g)$membership
     colbar <- rainbow(max(comps)+1)
     V(g)$color <- colbar[comps+1]
     plot(g, layout=layout.fruchterman.reingold, vertex.size=5, vertex.label=NA)

     # plot communities in a graph
     g <- graph.full(5) 
     g <- add.edges(g, c(0,5, 0,10, 5,10))
     com <- spinglass.community(g, spins=5)
     V(g)$color <- com$membership+1
     g <- set.graph.attribute(g, "layout", layout.kamada.kawai(g))
     plot(g, vertex.label.dist=1.5)

     # draw a bunch of trees, fix layout
     igraph.par("plot.layout", layout.reingold.tilford)
     plot(graph.tree(20, 2))
     plot(graph.tree(50, 3), vertex.size=3, vertex.label=NA)
     tkplot(graph.tree(50, 2), mode="undirected", vertex.size=10, vertex.color="green")
     ## End(Not run)

