% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/network.R
\name{NetworkAtomic}
\alias{NetworkAtomic}
\title{NetworkAtomic}
\usage{
NetworkAtomic(
  links,
  nodes = NULL,
  from = NULL,
  from_sep = "_",
  to = NULL,
  to_sep = "_",
  node_by = NULL,
  node_by_sep = "_",
  link_weight_by = 2,
  link_weight_name = NULL,
  link_type_by = "solid",
  link_type_name = NULL,
  node_size_by = 15,
  node_size_name = NULL,
  node_color_by = "black",
  node_color_name = NULL,
  node_shape_by = 21,
  node_shape_name = NULL,
  node_fill_by = "grey20",
  node_fill_name = NULL,
  link_alpha = 1,
  node_alpha = 0.95,
  node_stroke = 1.5,
  cluster_scale = c("fill", "color", "shape"),
  node_size_range = c(5, 20),
  link_weight_range = c(0.5, 5),
  link_arrow_offset = 20,
  link_curvature = 0,
  link_color_by = "from",
  link_color_name = NULL,
  palette = "Paired",
  palcolor = NULL,
  palreverse = FALSE,
  link_palette = ifelse(link_color_by \%in\% c("from", "to"), palette, "Set1"),
  link_palcolor = if (link_color_by \%in\% c("from", "to")) palcolor else NULL,
  directed = TRUE,
  layout = "circle",
  cluster = "none",
  add_mark = FALSE,
  mark_expand = ggplot2::unit(10, "mm"),
  mark_type = c("hull", "ellipse", "rect", "circle"),
  mark_alpha = 0.1,
  mark_linetype = 1,
  add_label = TRUE,
  label_size = 3,
  label_fg = "white",
  label_bg = "black",
  label_bg_r = 0.1,
  arrow = ggplot2::arrow(type = "closed", length = ggplot2::unit(0.1, "inches")),
  title = NULL,
  subtitle = NULL,
  xlab = NULL,
  ylab = NULL,
  aspect.ratio = 1,
  theme = "theme_this",
  theme_args = list(),
  legend.position = "right",
  legend.direction = "vertical",
  ...
)
}
\arguments{
\item{links}{A data frame containing the edge list. Must contain the
\code{from} and \code{to} columns specifying source and target node
identifiers. Additional columns can be referenced by other parameters
(e.g., \code{link_weight_by}, \code{link_type_by},
\code{link_color_by}).}

\item{nodes}{An optional data frame of node metadata. When provided,
columns such as \code{node_size_by}, \code{node_color_by},
\code{node_shape_by}, and \code{node_fill_by} can reference its
columns. When \code{NULL}, the node set is inferred from the unique
values in the \code{from} and \code{to} columns. If a single character
string starting with \code{"@"}, the nodes data frame is extracted
from the corresponding attribute of \code{links} (e.g.
\code{"@nodes"} extracts \code{attr(links, "nodes")}).}

\item{from}{A character string specifying the column name in
\code{links} for the source node identifiers. Defaults to
\code{"from"}, or the first column of \code{links} if that column
name does not exist. Multiple columns can be provided; they are
concatenated with \code{from_sep}.}

\item{from_sep}{A character string to join multiple \code{from}
columns. Default \code{"_"}. Ignored when \code{from} is a single
column.}

\item{to}{A character string specifying the column name in
\code{links} for the target node identifiers. Defaults to
\code{"to"}, or the second column of \code{links} if that column
name does not exist. Multiple columns can be provided; they are
concatenated with \code{to_sep}.}

\item{to_sep}{A character string to join multiple \code{to} columns.
Default \code{"_"}. Ignored when \code{to} is a single column.}

\item{node_by}{A character string specifying the column name in
\code{nodes} for the node identifiers. These must match the values
in the \code{from} / \code{to} columns of \code{links}. Defaults to
\code{"name"}, or the first column of \code{nodes} if that column
name does not exist. Multiple columns can be provided; they are
concatenated with \code{node_by_sep}.}

\item{node_by_sep}{A character string to join multiple
\code{node_by} columns. Default \code{"_"}. Ignored when
\code{node_by} is a single column.}

\item{link_weight_by}{A numeric value or a character string. If
numeric, all edges receive that constant line width. If a column
name, the edge line width is mapped to that column. Default
\code{2}.}

\item{link_weight_name}{A character string for the link weight legend
title. When \code{NULL} (default), the column name from
\code{link_weight_by} is used. Only relevant when
\code{link_weight_by} is a column name.}

\item{link_type_by}{A character string or a column name specifying
the edge linetype. Can be \code{"solid"}, \code{"dashed"},
\code{"dotted"}, etc. If a column name from \code{links} is
supplied, the linetype is mapped to that column (with a version
check for ggplot2 4.0.0, where mapping is unsupported and a
warning is issued). Default \code{"solid"}.}

\item{link_type_name}{A character string for the link linetype legend
title. When \code{NULL} (default), the column name from
\code{link_type_by} is used. Only relevant when
\code{link_type_by} is a column name.}

\item{node_size_by}{A numeric value or a character string. If
numeric, all nodes receive that constant point size. If a column
name, the size is mapped to that column. Default \code{15}.}

\item{node_size_name}{A character string for the node size legend
title. When \code{NULL} (default), the column name from
\code{node_size_by} is used. Only relevant when
\code{node_size_by} is a column name.}

\item{node_color_by}{A character string specifying the node colour.
If a colour name or hex code (e.g. \code{"black"}), all nodes
receive that constant colour. If a column name from \code{nodes} is
supplied, the colour is mapped to that column. Default
\code{"black"}.}

\item{node_color_name}{A character string for the node colour legend
title. When \code{NULL} (default), the column name from
\code{node_color_by} is used. Only relevant when
\code{node_color_by} is a column name.}

\item{node_shape_by}{A numeric value or a character string. If
numeric, all nodes receive that constant shape (see
\code{\link[ggplot2]{shape}}). If a column name, the shape is
mapped to that column (cast to factor). Default \code{21} (filled
circle with border).}

\item{node_shape_name}{A character string for the node shape legend
title. When \code{NULL} (default), the column name from
\code{node_shape_by} is used. Only relevant when
\code{node_shape_by} is a column name.}

\item{node_fill_by}{A character string specifying the node fill
colour. If a colour name or hex code (e.g. \code{"grey20"}), all
nodes receive that constant fill. If a column name from
\code{nodes} is supplied, the fill is mapped to that column.
Default \code{"grey20"}.}

\item{node_fill_name}{A character string for the node fill legend
title. When \code{NULL} (default), the column name from
\code{node_fill_by} is used. Only relevant when
\code{node_fill_by} is a column name.}

\item{link_alpha}{A numeric value specifying the transparency
(alpha) of the edge lines. Between \code{0} (invisible) and
\code{1} (opaque). Default \code{1}.}

\item{node_alpha}{A numeric value specifying the fill transparency
of the nodes. Only applies when \code{node_shape_by} is one of the
filled shapes (21--25). Default \code{0.95}.}

\item{node_stroke}{A numeric value specifying the border stroke
width of the node points. Default \code{1.5}.}

\item{cluster_scale}{A character string specifying which node
aesthetic is overridden by cluster membership. One of
\code{"fill"}, \code{"color"}, or \code{"shape"}. The value is
matched via \code{\link{match.arg}}; default is \code{"fill"}.}

\item{node_size_range}{A numeric vector of length 2 giving the
minimum and maximum node size (in ggplot2 point units) when
\code{node_size_by} is a column name. Default \code{c(5, 20)}.}

\item{link_weight_range}{A numeric vector of length 2 giving the
minimum and maximum edge line width (in mm) when
\code{link_weight_by} is a column name. Default
\code{c(0.5, 5)}.}

\item{link_arrow_offset}{A numeric value (in points) specifying the
offset distance for the arrow end cap from the target node.
Prevents arrow heads from overlapping the node points. Only
relevant when \code{directed = TRUE}. Default \code{20}.}

\item{link_curvature}{A numeric value controlling the curvature of
the edges. \code{0} (default) produces straight edges; positive
values curve them away from the direct path.}

\item{link_color_by}{A character string controlling how edge colour
is determined. Options:
\itemize{
\item \code{"from"} (default) -- colour follows the source node's
fill or colour aesthetic.
\item \code{"to"} -- colour follows the target node's fill or
colour.
\item A column name from \code{links} -- colour is mapped
directly to that column.
}}

\item{link_color_name}{A character string for the edge colour legend
title. Only used when \code{link_color_by} is a column name (not
\code{"from"} or \code{"to"}). When \code{NULL} (default), the
column name is used.}

\item{palette}{A character string specifying the palette to use.
A named list or vector can be used to specify the palettes for different \code{split_by} values.}

\item{palcolor}{A character string specifying the color to use in the palette.
A named list can be used to specify the colors for different \code{split_by} values.
If some values are missing, the values from the palette will be used (palcolor will be NULL for those values).}

\item{palreverse}{A logical value indicating whether to reverse the palette. Default is FALSE.}

\item{link_palette}{A character string specifying the palette for
edge colours when they are mapped. When \code{link_color_by} is
\code{"from"} or \code{"to"}, defaults to the node
\code{palette}. Otherwise defaults to \code{"Set1"}.}

\item{link_palcolor}{A character vector specifying custom colours
for the edge palette. When \code{link_color_by} is \code{"from"}
or \code{"to"}, defaults to the node \code{palcolor}. Otherwise
defaults to \code{NULL}.}

\item{directed}{A logical value. When \code{TRUE}, edges are drawn
with arrow heads and an end-cap offset. Default \code{TRUE}.}

\item{layout}{A character string or an \code{igraph_layout_spec}
object specifying the node placement algorithm. Built-in shortcuts:
\code{"circle"} (circular layout), \code{"tree"} (hierarchical
tree), \code{"grid"} (grid layout). Any other string is prefixed
with \code{"layout_with_"} and called as an igraph function (e.g.
\code{"fr"} for Fruchterman--Reingold, \code{"kk"} for
Kamada--Kawai). Default \code{"circle"}.}

\item{cluster}{A character string specifying the community detection
algorithm. One of \code{"none"}, \code{"fast_greedy"},
\code{"walktrap"}, \code{"edge_betweenness"}, \code{"infomap"}, or
a custom clustering function from igraph. When not \code{"none"},
cluster membership overrides the aesthetic selected by
\code{cluster_scale}. Default \code{"none"}.}

\item{add_mark}{A logical value. When \code{TRUE} (and
\code{cluster != "none"}), an enclosure mark is drawn around each
cluster's nodes. Default \code{FALSE}.}

\item{mark_expand}{A \code{\link[grid]{unit}} object specifying the
extra space around points within a cluster mark. Default
\code{unit(10, "mm")}.}

\item{mark_type}{A character string specifying the mark geometry.
One of \code{"hull"}, \code{"ellipse"}, \code{"rect"}, or
\code{"circle"}, corresponding to ggforce's \code{geom_mark_hull},
\code{geom_mark_ellipse}, \code{geom_mark_rect}, and
\code{geom_mark_circle}. The value is matched via
\code{\link{match.arg}}; default is \code{"hull"}.}

\item{mark_alpha}{A numeric value for the fill transparency of
cluster marks. Default \code{0.1}.}

\item{mark_linetype}{A numeric or character value specifying the
border line type of the cluster marks. Default \code{1} (solid).}

\item{add_label}{A logical value. When \code{TRUE} (default), node
identifiers are drawn as repulsive text labels via
\code{\link[ggrepel]{geom_text_repel}}.}

\item{label_size}{A numeric value for the font size of node labels.
Scaled by the theme base size. Default \code{3}.}

\item{label_fg}{A character string specifying the text colour of
node labels. Default \code{"white"}.}

\item{label_bg}{A character string specifying the background colour
of node labels. Default \code{"black"}.}

\item{label_bg_r}{A numeric value specifying the background box
radius (as a fraction of label height). Passed to
\code{\link[ggrepel]{geom_text_repel}}'s \code{bg.r} argument.
Default \code{0.1}.}

\item{arrow}{A \code{\link[ggplot2]{arrow}} object for the link
arrow heads. Only used when \code{directed = TRUE}. Default is
\code{arrow(type = "closed", length = unit(0.1, "inches"))}.}

\item{title}{A character string specifying the title of the plot.
A function can be used to generate the title based on the default title.
This is useful when split_by is used and the title needs to be dynamic.}

\item{subtitle}{A character string specifying the subtitle of the plot.}

\item{xlab}{A character string specifying the x-axis label.}

\item{ylab}{A character string specifying the y-axis label.}

\item{aspect.ratio}{A numeric value specifying the aspect ratio of the plot.}

\item{theme}{A character string or a theme class (i.e. ggplot2::theme_classic) specifying the theme to use.
Default is "theme_this".}

\item{theme_args}{A list of arguments to pass to the theme function.}

\item{legend.position}{A character string specifying the position of the legend.
if \code{waiver()}, for single groups, the legend will be "none", otherwise "right".}

\item{legend.direction}{A character string specifying the direction of the legend.}

\item{...}{Not used.}
}
\value{
A \code{ggplot} object with \code{height} and \code{width}
attributes (in inches).
}
\description{
Core implementation for rendering a single network graph from a links
(edge list) data frame and an optional nodes (vertex metadata) data frame.
This is the workhorse behind the exported \code{\link{Network}} function --
it takes a \strong{single} pair of links/nodes data frames (no
\code{split_by} support) and returns a \code{ggplot} object.

The graph is constructed via \code{\link[igraph]{graph_from_data_frame}},
laid out using igraph layout algorithms (\code{"circle"}, \code{"tree"},
\code{"grid"}, or any named igraph layout such as \code{"fr"} or
\code{"kk"}), and rendered with \code{\link[ggraph]{ggraph}} using
\code{\link[ggraph]{geom_edge_arc}} for links and
\code{\link[ggplot2]{geom_point}} for nodes.

Key features include:
\itemize{
\item \strong{Directed / undirected graphs} with optional arrow heads.
\item \strong{Link styling}: variable width (weight), linetype, and
colour, each constant or mapped from a column. Edge colours
can follow source nodes, target nodes, or a dedicated column.
\item \strong{Node styling}: variable size, shape, colour, and fill,
each constant or column-mapped.
\item \strong{Community detection} via igraph clustering algorithms
with convex hull, ellipse, rectangle, or circle marks from
\code{\link[ggforce]{ggforce}}.
\item \strong{Automatic labels} via
\code{\link[ggrepel]{geom_text_repel}}.
\item \strong{Self-loop edges} drawn as direction-sensitive arcs.
}
}
\section{Architecture}{

\enumerate{
\item \strong{Column resolution} -- Default column names for
\code{from}, \code{to}, and \code{node_by} are assigned when
\code{NULL}, using the first or second column of the respective
data frame. Each is validated via \code{\link{check_columns}};
multi-column inputs are concatenated with their respective
separator (\code{from_sep}, \code{to_sep}, \code{node_by_sep})
and force-converted to factors. Resolved columns are renamed to
the canonical names \code{"from"}, \code{"to"}, and \code{"name"}.
\item \strong{Graph construction} -- An \code{\link[igraph]{igraph}}
object is built via \code{\link[igraph]{graph_from_data_frame}}
using the links data frame and (optionally) the nodes data frame.
If \code{nodes} is a string starting with \code{"@"}, it is
extracted from the corresponding attribute on the links object.
\item \strong{Layout computation} -- The layout is resolved:
\code{"circle"} -> \code{\link[igraph]{layout_in_circle}},
\code{"tree"} -> \code{\link[igraph]{layout_as_tree}},
\code{"grid"} -> \code{\link[igraph]{layout_on_grid}}.
Any other character string is prefixed with \code{"layout_with_"}
and looked up in the igraph namespace (e.g. \code{"fr"} ->
\code{layout_with_fr}). If \code{layout} is already an
\code{igraph_layout_spec} object it is applied directly via
\code{\link[igraph]{layout_}}.
\item \strong{Data extraction} -- Vertex and edge data frames are
extracted from the igraph object via
\code{\link[igraph]{as_data_frame}}. Layout coordinates are
added as \code{x} and \code{y} columns to the vertex data.
\item \strong{Node aesthetic assembly} -- Each of \code{size},
\code{color}, \code{shape}, and \code{fill} is resolved as
either a constant value (numeric or character) or a mapping to
a column of the node data. A per-aesthetic \code{"guide"} /
\code{"none"} flag is tracked for legend construction.
\item \strong{Link aesthetic assembly} -- \code{linewidth} (weight),
\code{linetype}, and \code{color} are resolved similarly.
\itemize{
\item When \code{link_color_by = "from"}, edge colours are
derived from the source node's fill (if node shape is
filled, 21--25) or colour; when \code{"to"}, from the
target node.
\item When \code{link_color_by} names a column in the links
data frame (other than \code{"from"}/\code{"to"}), it
is mapped directly.
}
If \code{directed = TRUE}, a \code{\link[ggplot2]{arrow}} is
added and \code{end_cap} is set via \code{\link[ggraph]{circle}}
to prevent arrow overlap with nodes. Self-loop edges receive a
\code{direction} aesthetic.
\item \strong{Plot initialisation} -- A \code{\link[ggraph]{ggraph}}
plot is created with \code{layout = "manual"} and vertex
coordinates from the layout.
\item \strong{Clustering and marks} -- When \code{cluster != "none"},
the specified igraph community-detection algorithm is run
(\code{cluster_fast_greedy}, \code{cluster_walktrap},
\code{cluster_edge_betweenness}, \code{cluster_infomap}, or a
custom function). Membership overrides the aesthetic specified
by \code{cluster_scale} (\code{"fill"}, \code{"color"}, or
\code{"shape"}) with a warning that the previous setting is
discarded. If \code{add_mark = TRUE}, a mark enclosure
(hull / ellipse / rect / circle) is drawn per cluster via the
corresponding \code{\link[ggforce]{ggforce}} geom.
\item \strong{Link rendering} -- \code{\link[ggraph]{geom_edge_arc}}
draws the edges (with configurable \code{link_curvature}) and
\code{\link[ggraph]{geom_edge_loop}} handles self-loop edges.
\item \strong{Link scales} -- Conditional on their guide status,
\code{scale_edge_width_continuous},
\code{scale_edge_linetype_discrete}, and
\code{scale_edge_color_manual} /
\code{scale_edge_color_gradientn} are added for weight,
linetype, and colour legends respectively.
\item \strong{Node rendering} -- \code{\link[ggplot2]{geom_point}}
draws the nodes with the assembled aesthetics.
\item \strong{Node scales} -- Conditional scale additions:
\code{scale_size_continuous} (range from
\code{node_size_range}), \code{scale_color_manual},
\code{scale_shape_manual}, and \code{scale_fill_manual}, each
with their legend title and guide overrides.
\item \strong{Labels} -- When \code{add_label = TRUE}, node
identifiers are rendered via
\code{\link[ggrepel]{geom_text_repel}} using
\code{label_fg}, \code{label_bg}, and \code{label_bg_r}.
\item \strong{Final theme and dimensions} -- Coordinate expansion,
axis labels, theme application, and legend positioning are
applied. Plot height and width are computed via
\code{\link{calculate_plot_dimensions}} and stored as
attributes.
}
}

\keyword{internal}
