% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/netplot.R
\name{nplot}
\alias{nplot}
\alias{netplot}
\alias{nplot.igraph}
\alias{nplot.network}
\alias{nplot.matrix}
\alias{nplot.default}
\alias{print.netplot}
\title{Plot a network}
\usage{
nplot(
  x,
  layout,
  vertex.size = 1,
  bg.col = "transparent",
  vertex.nsides = 10,
  vertex.color = grDevices::hcl.colors(1),
  vertex.size.range = c(0.01, 0.03, 4),
  vertex.frame.color = NULL,
  vertex.rot = 0,
  vertex.frame.prop = 0.2,
  vertex.label = NULL,
  vertex.label.fontsize = NULL,
  vertex.label.color = adjustcolor("black", alpha.f = 0.8),
  vertex.label.fontfamily = "sans",
  vertex.label.fontface = "plain",
  vertex.label.show = 0.3,
  vertex.label.range = c(5, 15),
  edge.width = 1,
  edge.width.range = c(1, 2),
  edge.arrow.size = NULL,
  edge.color = ~ego(alpha = 0.1, col = "gray") + alter,
  edge.curvature = pi/3,
  edge.line.lty = "solid",
  edge.line.breaks = 5,
  sample.edges = 1,
  skip.vertex = FALSE,
  skip.edges = FALSE,
  skip.arrows = skip.edges,
  add = FALSE,
  zero.margins = TRUE,
  edgelist
)

\method{nplot}{igraph}(
  x,
  layout = igraph::layout_nicely(x),
  vertex.size = igraph::degree(x, mode = "in"),
  bg.col = "transparent",
  vertex.nsides = 10,
  vertex.color = grDevices::hcl.colors(1),
  vertex.size.range = c(0.01, 0.03, 4),
  vertex.frame.color = NULL,
  vertex.rot = 0,
  vertex.frame.prop = 0.2,
  vertex.label = igraph::vertex_attr(x, "name"),
  vertex.label.fontsize = NULL,
  vertex.label.color = adjustcolor("black", alpha.f = 0.8),
  vertex.label.fontfamily = "sans",
  vertex.label.fontface = "plain",
  vertex.label.show = 0.3,
  vertex.label.range = c(5, 15),
  edge.width = igraph::edge_attr(x, "weight"),
  edge.width.range = c(1, 2),
  edge.arrow.size = NULL,
  edge.color = ~ego(alpha = 0.1, col = "gray") + alter,
  edge.curvature = pi/3,
  edge.line.lty = "solid",
  edge.line.breaks = 5,
  sample.edges = 1,
  skip.vertex = FALSE,
  skip.edges = FALSE,
  skip.arrows = !igraph::is_directed(x),
  add = FALSE,
  zero.margins = TRUE,
  edgelist
)

\method{nplot}{network}(
  x,
  layout = sna::gplot.layout.kamadakawai(x, NULL),
  vertex.size = sna::degree(x, cmode = "indegree"),
  bg.col = "transparent",
  vertex.nsides = 10,
  vertex.color = grDevices::hcl.colors(1),
  vertex.size.range = c(0.01, 0.03, 4),
  vertex.frame.color = NULL,
  vertex.rot = 0,
  vertex.frame.prop = 0.2,
  vertex.label = network::get.vertex.attribute(x, "vertex.names"),
  vertex.label.fontsize = NULL,
  vertex.label.color = adjustcolor("black", alpha.f = 0.8),
  vertex.label.fontfamily = "sans",
  vertex.label.fontface = "plain",
  vertex.label.show = 0.3,
  vertex.label.range = c(5, 15),
  edge.width = network::get.edge.attribute(x, "weight"),
  edge.width.range = c(1, 2),
  edge.arrow.size = NULL,
  edge.color = ~ego(alpha = 0.1, col = "gray") + alter,
  edge.curvature = pi/3,
  edge.line.lty = "solid",
  edge.line.breaks = 5,
  sample.edges = 1,
  skip.vertex = FALSE,
  skip.edges = FALSE,
  skip.arrows = !network::is.directed(x),
  add = FALSE,
  zero.margins = TRUE,
  edgelist
)

\method{nplot}{matrix}(
  x,
  layout,
  vertex.size = 1,
  bg.col = "transparent",
  vertex.nsides = 10,
  vertex.color = grDevices::hcl.colors(1),
  vertex.size.range = c(0.01, 0.03, 4),
  vertex.frame.color = NULL,
  vertex.rot = 0,
  vertex.frame.prop = 0.2,
  vertex.label = NULL,
  vertex.label.fontsize = NULL,
  vertex.label.color = adjustcolor("black", alpha.f = 0.8),
  vertex.label.fontfamily = "sans",
  vertex.label.fontface = "plain",
  vertex.label.show = 0.3,
  vertex.label.range = c(5, 15),
  edge.width = 1,
  edge.width.range = c(1, 2),
  edge.arrow.size = NULL,
  edge.color = ~ego(alpha = 0.1, col = "gray") + alter,
  edge.curvature = pi/3,
  edge.line.lty = "solid",
  edge.line.breaks = 5,
  sample.edges = 1,
  skip.vertex = FALSE,
  skip.edges = FALSE,
  skip.arrows = skip.edges,
  add = FALSE,
  zero.margins = TRUE,
  edgelist
)

\method{nplot}{default}(
  x,
  layout,
  vertex.size = 1,
  bg.col = "transparent",
  vertex.nsides = 10,
  vertex.color = grDevices::hcl.colors(1),
  vertex.size.range = c(0.01, 0.03, 4),
  vertex.frame.color = NULL,
  vertex.rot = 0,
  vertex.frame.prop = 0.2,
  vertex.label = NULL,
  vertex.label.fontsize = NULL,
  vertex.label.color = adjustcolor("black", alpha.f = 0.8),
  vertex.label.fontfamily = "sans",
  vertex.label.fontface = "plain",
  vertex.label.show = 0.3,
  vertex.label.range = c(5, 15),
  edge.width = 1,
  edge.width.range = c(1, 2),
  edge.arrow.size = NULL,
  edge.color = ~ego(alpha = 0.1, col = "gray") + alter,
  edge.curvature = pi/3,
  edge.line.lty = "solid",
  edge.line.breaks = 5,
  sample.edges = 1,
  skip.vertex = FALSE,
  skip.edges = FALSE,
  skip.arrows = skip.edges,
  add = FALSE,
  zero.margins = TRUE,
  ...,
  edgelist
)

\method{print}{netplot}(x, y = NULL, newpage = TRUE, legend = TRUE, ...)
}
\arguments{
\item{x}{A graph. It supports networks stored as \code{igraph}, \code{network}, and
matrices objects (see details).}

\item{layout}{Numeric two-column matrix with the graph layout in x/y positions of the vertices.}

\item{vertex.size}{Numeric vector of length \code{vcount(x)}. Absolute size of the
vertex from 0 to 1. Can also be a one-sided formula (e.g. \code{~ degree}) naming a
numeric vertex attribute to map sizes from (see "Mapping attributes with
formulas").}

\item{bg.col}{Color of the background.}

\item{vertex.nsides}{Numeric vector of length \code{vcount(x)}. Number of sides of
the vertex. E.g. three is a triangle, and 100 approximates a circle. Can also
be a one-sided formula (e.g. \code{~ group}) naming a vertex attribute; each unique
value is then mapped to a distinct shape (see "Mapping attributes with
formulas").}

\item{vertex.color}{Vector of length \code{vcount(x)}. Vertex HEX or built in
colors. Can also be a one-sided formula (e.g. \code{~ group}) naming a vertex
attribute to color vertices by (see "Mapping attributes with formulas").}

\item{vertex.size.range}{Numeric vector of length 2 or 3, or \code{NULL}. Relative size for the
minimum and maximum of the plot, and curvature of the scale. The third number
is used as \code{size^rel[3]}. If \code{NULL}, scaling is suppressed and \code{vertex.size}
is used as is.}

\item{vertex.frame.color}{Vector of length \code{vcount(x)}. Border of vertex in
HEX or built in colors.}

\item{vertex.rot}{Vector of length \code{vcount(x)} in Radians. Passed to \link{npolygon},
elevation degree from which the polygon is drawn.}

\item{vertex.frame.prop}{Vector of length \code{vcount(x)}. What proportion of the
vertex does the frame occupy (values between 0 and 1).}

\item{vertex.label}{Character vector of length \code{vcount(x)}. Labels.}

\item{vertex.label.fontsize}{Numeric vector.}

\item{vertex.label.color}{Vector of colors of length \code{vcount(x)}.}

\item{vertex.label.fontfamily}{Character vector of length \code{vcount(x)}.}

\item{vertex.label.fontface}{See \link[grid:gpar]{grid::gpar}}

\item{vertex.label.show}{Numeric scalar. Proportion of labels to show as the
top ranking according to \code{vertex.size}.}

\item{vertex.label.range}{Numeric vector of size 2 or 3. Relative scale of
\code{vertex.label.fontsize} in points (see \link[grid:gpar]{grid::gpar}).}

\item{edge.width}{Numeric vector of length \code{ecount(x)}. Relative edge widths.
Values are normalized and then mapped to the range specified by \code{edge.width.range},
unless \code{edge.width.range} is \code{NULL}.
For \code{nplot.igraph} and \code{nplot.network}, defaults to the "weight" edge
attribute if present; otherwise all edges use width 1. Can also be a one-sided
formula (e.g. \code{~ weight}) naming a numeric edge attribute (see "Mapping
attributes with formulas").}

\item{edge.width.range}{Numeric vector of length 2, or \code{NULL}. The minimum and maximum line
widths (in points) to use when mapping \code{edge.width} values. For example,
\code{c(1, 4)} maps the smallest edge weight to 1pt and the largest to 4pt.
If \code{NULL}, scaling is suppressed and \code{edge.width} is used as is.}

\item{edge.arrow.size}{Vector of length \code{ecount(x)} from 0 to 1.}

\item{edge.color}{A vector of length \code{ecount(x)}. In HEX or built in colors.
Can be \code{NULL} in which case
the color is picked as a mixture between ego and alters' \code{vertex.color} values.}

\item{edge.curvature}{Numeric vector of length \code{ecount(x)}. Curvature of edges
in terms of radians.}

\item{edge.line.lty}{Vector of length \code{ecount(x)}. Line types in R
(e.g.- 1 = Solid, 2 = Dashed, etc).}

\item{edge.line.breaks}{Vector of length \code{ecount(x)}. Number of vertices to
draw (approximate) the arc (edge).}

\item{sample.edges}{Numeric scalar between 0 and 1. Proportion of edges to
sample.}

\item{skip.vertex, skip.edges, skip.arrows}{Logical scalar. When \code{TRUE} the
object is not plotted.}

\item{add}{Logical scalar.}

\item{zero.margins}{Logical scalar.}

\item{edgelist}{An edgelist.}

\item{y, ...}{Ignored}

\item{newpage}{Logical scalar. When \code{TRUE} calls \link[grid:grid.newpage]{grid::grid.newpage}.}

\item{legend}{Logical scalar. When \code{TRUE} it adds a legend.}
}
\value{
An object of class \code{c("netplot", "gTree", "grob", "gDesc")}. The object
has an additional set of attributes:
\itemize{
\item \verb{.xlim, .ylim} vector of size two with the x-asis/y-axis limits.
\item \code{.layout} A numeric matrix of size \code{vcount(x) * 2} with the vertices positions
\item \code{.edgelist} A numeric matrix, The edgelist.
}

In the case of \code{nplot.default}, an object of class \code{netplot} and \code{grob} (see
\link[grid:grob]{grid::grob}) with the following slots:
\itemize{
\item \code{children} The main \code{grob} of the object.
\item \code{name} Character scalar. The name of the plot
\item \code{.xlim} and \code{.ylim} Two vectors indicating the limits of the plot
\item \code{.layout} A two-column matrix with the location of the vertices.
\item \code{.edgelist} A two-column matrix, an edgelist.
\item \code{.N} Integer. The number of vertices.
\item \code{.M} Integer. The number of edges.
}

The \code{children} \code{grob} contains the following two objects:
\itemize{
\item \code{background} a \code{grob} rectangule.
\item \code{graph} a \code{gTree} that contains each vertex and each edge
of the figure.
}
}
\description{
\code{nplot()} is the main function of the \strong{netplot} package. It draws a network
using the \strong{grid} graphics system (the same engine that powers \strong{ggplot2}),
emphasizing aesthetics and providing sensible defaults that yield
out-of-the-box nice visualizations. Compared with base \code{igraph}/\code{network}
plots, \code{nplot()} auto-scales vertices and edges relative to the plotting
device, draws truly curved edges, mixes edge colors from their endpoints,
and fills the device efficiently.
}
\details{
Vertex and edge aesthetics can be set directly (passing a vector) or,
conveniently, mapped from graph attributes using a \emph{formula} interface (see
the "Mapping attributes with formulas" section below). The returned object is
a \strong{grid} \code{grob}, so it can be further edited with \code{\link[=set_vertex_gpar]{set_vertex_gpar()}} /
\code{\link[=set_edge_gpar]{set_edge_gpar()}}, combined with other grid graphics (e.g. via
\code{gridExtra::grid.arrange()}), or annotated with a legend through
\code{\link[=nplot_legend]{nplot_legend()}}.

When \code{x} is of class \link{matrix}, it will be passed to \code{\link[igraph:graph_from_adjacency_matrix]{igraph::graph_from_adjacency_matrix()}}.
}
\section{Mapping attributes with formulas}{


Several aesthetics can be mapped directly from graph attributes by passing a
one-sided formula naming the attribute, instead of building the vector by
hand. The mapping depends on the aesthetic:
\itemize{
\item \code{vertex.color = ~ attr} colors vertices by the vertex attribute \code{attr}.
Character/factor attributes are mapped to a categorical palette, numeric
attributes to a continuous gradient, and logical attributes to two colors.
When used this way, \code{print()}-ing the resulting plot also draws a matching
legend: a categorical key for discrete attributes and a continuous color
bar for continuous ones.
\item \code{vertex.nsides = ~ attr} maps each unique value of \code{attr} to a distinct
vertex shape (triangle, square, pentagon, ...).
\item \code{vertex.size = ~ attr} and \code{edge.width = ~ attr} scale sizes/widths from a
numeric vertex/edge attribute.
\item \code{edge.color} uses a different, richer formula grammar based on \code{ego()} and
\code{alter()} to mix the endpoints' colors; see \link{netplot-formulae}.
}

For \code{vertex.nsides}, \code{vertex.size}, and \code{edge.width} the right-hand side of
the formula is \emph{evaluated} with the graph's attributes in scope, so besides
bare names you can use expressions, e.g. \code{edge.width = ~ log1p(weight)} or
\code{vertex.size = ~ degree ^ 2}.

For example, \code{nplot(x, vertex.color = ~ gender, vertex.size = ~ degree)}
colors vertices by the \code{gender} attribute and sizes them by \code{degree}. The
same attribute-mapping formulas also work in \code{\link[=set_vertex_gpar]{set_vertex_gpar()}}.
}

\examples{
library(igraph)
library(netplot)
set.seed(1)
x <- sample_smallworld(1, 200, 5, 0.03)

plot(x) # ala igraph
nplot(x) # ala netplot

# Mapping aesthetics from vertex attributes using formulas
V(x)$grp <- sample(letters[1:3], vcount(x), replace = TRUE)
V(x)$deg <- degree(x)
nplot(
  x,
  vertex.color  = ~ grp, # color by the categorical attribute
  vertex.nsides = ~ grp, # and give each group a distinct shape
  vertex.size   = ~ deg  # size by a numeric attribute
)
}
\seealso{
\link{nplot_base}
}
