% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/layout.R
\name{layout_}
\alias{layout_}
\alias{layout}
\alias{print.igraph_layout_spec}
\alias{print.igraph_layout_modifier}
\title{Graph layouts}
\usage{
layout_(graph, layout, ...)

\method{print}{igraph_layout_spec}(x, ...)

\method{print}{igraph_layout_modifier}(x, ...)
}
\arguments{
\item{graph}{The input graph.}

\item{layout}{The layout specification. It must be a call
to a layout specification function.}

\item{...}{Further modifiers, see a complete list below.
For the \code{\link[=print]{print()}} methods, it is ignored.}

\item{x}{The layout specification}
}
\value{
The return value of the layout function, usually a
two column matrix. For 3D layouts a three column matrix.
}
\description{
This is a generic function to apply a layout function to
a graph.
}
\details{
There are two ways to calculate graph layouts in igraph.
The first way is to call a layout function (they all have
prefix \code{layout_()} on a graph, to get the vertex coordinates.

The second way (new in igraph 0.8.0), has two steps, and it
is more flexible. First you call a layout specification
function (the one without the \code{layout_()} prefix, and
then \code{layout_()} (or \code{\link[=add_layout_]{add_layout_()}}) to
perform the layouting.

The second way is preferred, as it is more flexible. It allows
operations before and after the layouting. E.g. using the
\code{component_wise()} argument, the layout can be calculated
separately for each component, and then merged to get the
final results.
}
\section{Modifiers}{

Modifiers modify how a layout calculation is performed.
Modifiers are applied in the order they are specified as arguments to
\code{layout_()}.

There are two types of modifiers:
\itemize{
\item \strong{Pre-layout modifiers} affect how the layout is calculated.
Only one pre-layout modifier can be used at a time.
\item \strong{Post-layout modifiers} transform the resulting coordinates.
Multiple post-layout modifiers can be chained together.
}

Currently implemented modifiers:
\itemize{
\item \code{component_wise()} (pre-layout) calculates the layout separately
for each component of the graph, and then merges them.
\item \code{normalize()} (post-layout) scales the layout to a square.
}

Custom modifiers can be created using the \code{layout_modifier()} function.
A custom modifier must specify:
\itemize{
\item \code{id}: A unique identifier string for the modifier
\item \code{type}: Either \code{"pre"} for pre-layout or \code{"post"} for post-layout
\item \code{args}: A list of arguments to pass to the apply function
\item \code{apply}: A function with signature
\verb{function(graph, layout, modifier_args)} that performs the modification.
For pre-layout modifiers, \code{layout} is the layout specification.
For post-layout modifiers, \code{layout} is the coordinate matrix to transform.
}
}

\examples{
g <- make_ring(10) + make_full_graph(5)
coords <- layout_(g, as_star())
plot(g, layout = coords)

# Using modifiers
g <- make_ring(10) + make_ring(5)
coords <- layout_(g, in_circle(), component_wise(), normalize())
plot(g, layout = coords)

# Creating a custom post-layout modifier
scale_by <- function(factor) {
  layout_modifier(
    id = "scale_by",
    type = "post",
    args = list(factor = factor),
    apply = function(graph, layout, modifier_args) {
      layout * modifier_args$factor
    }
  )
}
coords <- layout_(make_ring(10), in_circle(), scale_by(3))
plot(make_ring(10), layout = coords)
}
\seealso{
\code{\link[=add_layout_]{add_layout_()}} to add the layout to the
graph as an attribute.

Other graph layouts: 
\code{\link{add_layout_}()},
\code{\link{component_wise}()},
\code{\link{layout_as_bipartite}()},
\code{\link{layout_as_star}()},
\code{\link{layout_as_tree}()},
\code{\link{layout_in_circle}()},
\code{\link{layout_nicely}()},
\code{\link{layout_on_grid}()},
\code{\link{layout_on_sphere}()},
\code{\link{layout_randomly}()},
\code{\link{layout_with_dh}()},
\code{\link{layout_with_fr}()},
\code{\link{layout_with_gem}()},
\code{\link{layout_with_graphopt}()},
\code{\link{layout_with_kk}()},
\code{\link{layout_with_lgl}()},
\code{\link{layout_with_mds}()},
\code{\link{layout_with_sugiyama}()},
\code{\link{merge_coords}()},
\code{\link{norm_coords}()},
\code{\link{normalize}()}
}
\concept{graph layouts}
