Obtain or create layout for igraph object

Set the node layout for an igraph object

Usage

get_igraph_layout(
  g,
  layout = NULL,
  default_layout = igraph::layout_nicely,
  verbose = FALSE,
  ...
)

set_igraph_layout(
  g,
  layout = NULL,
  default_layout = igraph::layout_nicely,
  verbose = FALSE,
  prefer = c("graph_attr"),
  spread_labels = FALSE,
  ...
)

Arguments

g

igraph object

layout

is always applied when not NULL, even when layout exists in g. Input should be one of:

numeric matrix of layout coordinates, with nrow(layout) equal to the number of nodes igraph::vcount(g).
function that takes igraph input, and returns numeric matrix of layout coordinates.
NULL: default, uses the graph attribute 'layout' if it exists, igraph::graph_attr(g, "layout") if it exists. If it does not exist, it follows default_layout.

default_layout

is only applied when layout is NULL, and no layout is defined in graph g. Input should be function or NULL:

Default igraph::layout_nicely() is used for consistency with igraph conventions. This algorithm should be safe for very large graphs, which may be extremely inefficient with layout_with_qfr() for example.
When NULL, it will return NULL unless layout is defined in the input g graph.

verbose

logical indicating whether to print verbose output.

...

additional arguments are passed to any layout function called.

prefer

character vector with preferred method of storage:

'graph_attr': store the matrix in graph attribute 'layout'.
'vertex_attr': store coordinates in vertex attributes 'x', 'y', and optionally 'z' when defined.

spread_labels

logical default FALSE, whether to call spread_igraph_labels() to re-position node labels radially away from incoming edges.

Note that spread_igraph_labels() also by default do_reorder=TRUE which will re-order nodes by color, border, label, and name.
It is used to use TRUE when node labels were previously spread, so that the angle of offset is updated per the new layout coordinates.

Value

get_igraph_layout() returns a numeric matrix when: the input graph g contains layout as a graph attribute as either numeric matrix or function, or coordinates as x,y,z vertex attributes.

However, when there is no layout defined in g and default_layout is NULL, it returns NULL. This logic is used to avoid defining a layout if it does not already exist.
When matrix is returned, the number of rows matches the input graph g using igraph::vcount(g). All rownames() are defined to match vertex name when it exists, using igraph::V(g)$name.

set_igraph_layout() returns igraph object with layout defined per function arguments.

Details

This function is a simple helper function intended to retrieve the node layout for an igraph object.

The layout is defined with the following priority:

When layout is supplied as an argument, it is used. When it is a function it is applied to g to produce numeric matrix; otherwise it should be a numeric matrix and is used as-is.
When graph attribute 'layout' is defined, it is used as described for argument layout above, accepting either function or matrix values.
When vertex attributes 'x' and 'y' are defined, optionally 'z', their values are used to produce a numeric matrix.
When default_layout is supplied as a function it is applied to graph g to produce a numeric matrix.
Finally, when default_layout is NULL, this function returns NULL. This fallback is intended only when it is desirable not to apply a new layout function, useful for large graphs.

Additional rules

When layout is defined as a matrix with rownames, the rownames are matched to vertex attribute 'name' if it exists, using igraph::V(g)$name. This step is intended to help ensure nodes the layout can be supplied in any order without regard to the order defined in graph g.
- When the layout rownames do not match vertex names, this function will stop().
When layout is defined as a function, or when any layout function is applied as relevant, it is expected to return a numeric matrix, or data which can be coerced to a matrix with as.matrix() or as(x, "matrix").
- The matrix rownames are matched to vertex names as described above.
- Note that data.frame rownames are only retained at this step when they were already explicitly defined before coersion to matrix.

Suggested Usage

Define layout as a function in order to force the use of that function to produce layout coordinates. This step would always ignore pre-existing layout coordinates in graph g.
Define layout as NULL, and default_layout as a function, to use an existing layout stored in graph g, then to apply the default layout function only if no layout already existed in graph g.
Define layout as NULL, and default_layout as NULL, to return an existing layout stored in graph g, otherwise to return NULL without applying any layout. This option would avoid computationally expensive layout for large graphs, for example.

This function is a simple wrapper to get_igraph_layout() which also defines the resulting layout in the graph g.

Examples

g <- make_cnet_test(2, c(12, 5))
gl <- get_igraph_layout(g, verbose=TRUE)
#> ##  (21:50:31) 02Dec2025:   get_igraph_layout(): using graph_attr layout. 
jam_igraph(g)


# apply repulse=4
gl2 <- get_igraph_layout(g, layout=layout_with_qfrf(repulse=4), verbose=TRUE)
#> ##  (21:50:31) 02Dec2025:   get_igraph_layout(): creating layout using layout() 
jam_igraph(g, layout=gl2)


igraph::graph_attr(g, "layout") <- layout_with_qfrf(repulse=4)
gl3 <- get_igraph_layout(g, verbose=TRUE)
#> ##  (21:50:31) 02Dec2025:   get_igraph_layout(): using graph_attr layout. 
#> ##  (21:50:31) 02Dec2025:   get_igraph_layout(): applying graph_attr layout() 
identical(gl2, gl3)
#> [1] TRUE
#> TRUE

g2 <- set_igraph_layout(g, spread_labels=TRUE)
jam_igraph(g2)