% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/geom-edgespace.R
\name{geom_edgespace}
\alias{geom_edgespace}
\alias{edgespace_handler}
\title{Draw edge elements in a 2D graph layout}
\usage{
geom_edgespace(
  mapping = NULL,
  data = NULL,
  stat = StatEdgeSpace,
  position = "identity",
  ...,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = FALSE,
  arrow_size = 1,
  arrow_offset = 0.01,
  lineend = "butt",
  linejoin = "mitre",
  raster = FALSE,
  dpi = NULL,
  dev = "cairo",
  scale = 1
)

edgespace_handler()
}
\arguments{
\item{mapping}{Set of aesthetic mappings created by \code{\link[ggplot2:aes]{ggplot2::aes()}}.
These mappings override global aesthetics and are not inherited
from the top-level plot.}

\item{data}{The data to be displayed in this layer. It can be a
\link{GraphSpace} object, an \link[igraph]{igraph} object, or the
\code{edgespace_handler()} closure. When \code{NULL} (default),
a handler is created internally.}

\item{stat}{The statistical transformation to use on the data.
Defaults to \code{identity}.}

\item{position}{Position adjustment, either as a string or
the result of a call to a position adjustment function.}

\item{...}{Additional parameters passed to the underlying
drawing function in \link{GeomEdgeSpace}.}

\item{na.rm}{Logical. Should missing values be removed?
Defaults to \code{FALSE}.}

\item{show.legend}{Logical or a named logical vector indicating
whether this layer should be included in legends.}

\item{inherit.aes}{Logical. If \code{FALSE} (default), the layer will use
aesthetics defined in \code{mapping}.}

\item{arrow_size}{Numeric scaling factor controlling arrowhead
geometry (see 'drawing' section).}

\item{arrow_offset}{Numeric value controlling the base offset of arrows
at edge endpoints (see 'drawing' section).}

\item{lineend}{Line end style (round, butt, square). Supplied for
compatibility with \link[ggplot2]{geom_segment}.}

\item{linejoin}{Line join style (round, mitre, bevel). Supplied for
compatibility with \link[ggplot2]{geom_segment}.}

\item{raster}{Logical. Should node glyphs be rasterized?
Rasterization support is based on \code{\link[ggrastr]{rasterise}}.}

\item{dpi}{Numeric. Rasterization resolution.}

\item{dev}{Character. Rasterization backend. One of \code{"cairo"},
\code{"ragg"}, \code{"ragg_png"}, or \code{"cairo_png"}.}

\item{scale}{Numeric. Rasterization scaling factor
(see \code{\link[ggrastr]{rasterise}}).}
}
\value{
A ggplot2 layer that renders edge segments defined by
\link{GeomEdgeSpace}.
}
\description{
Constructor for \link{GeomEdgeSpace} ggproto objects.

A wrapper around \link[ggplot2]{geom_segment} that enables direct use of
edge attributes stored in \link{GraphSpace} objects as aesthetics.

This \code{geom} is designed to create edge-level aesthetics such as
\code{colour} and \code{linewidth}, or any custom aesthetics defined
in \link{GeomEdgeSpace}.
}
\details{
\strong{arrow_size} is a numeric scaling factor controlling arrowhead geometry.
The value is interpreted in the same numeric space as line width (\code{lwd}),
ensuring consistent scaling between edge strokes and arrowheads.

\strong{arrow_offset} is an additive term that offsets arrow endpoints
uniformly in graph space and is bounded by the edge length, in NPC units.

Arrowhead types are specified in the \link{GraphSpace} constructor.
}
\section{Aesthetics}{


\code{geom_edgespace()} understands \link[ggplot2]{geom_segment} aesthetics.

If these aesthetics are not explicitly provided in \code{aes()}, they
are automatically retrieved from the \link{GraphSpace} object.

\tabular{ll}{
\strong{\code{x}, \code{y}, \code{xend}, \code{yend}} \tab Required (automatically supplied).\cr
\code{colour} \tab Edge colour (see \link[ggplot2]{aes_colour_fill_alpha}).\cr
\code{alpha} \tab Transparency (see \link[ggplot2]{aes_colour_fill_alpha}).\cr
\code{linetype} \tab Edge line type (see \link[ggplot2]{aes_linetype_size_shape}).\cr
\code{linewidth} \tab Edge line width (see \link[ggplot2]{aes_linetype_size_shape}).
}

Required aesthetics (\code{x}, \code{y}, \code{xend}, \code{yend}, ...)
are supplied from the \link{GraphSpace} object and do not need to be
manually mapped.

Additional parameters can be passed to control fixed values for the layer.
For example: \code{colour = "grey"}, \code{linetype = 2}, \code{linewidth = 1}.

Arrows can be further adjusted by \code{arrow_size} and \code{arrow_offset}
arguments (see \emph{details}).
}

\section{Integration with ggraph}{


\code{geom_edgespace} is compatible with the \code{ggraph} methods.
When used within a \code{ggraph()} call, the default \code{edgespace_handler()}
automatically:
\itemize{
\item Identifies the current \code{layout_ggraph}.
\item Extracts the \code{x} and \code{y} coordinates calculated by \code{ggraph}.
\item Reconstructs a temporary \code{GraphSpace} object to inject spatial
metadata and user-chosen \code{ggraph} layout.
}
}

\examples{
library(RGraphSpace)
library(igraph)
library(ggplot2)

# Load a demo igraph
data('gtoy1', package = 'RGraphSpace')

# Create a GraphSpace object
gs <- GraphSpace(gtoy1)

\dontrun{

ggplot() +
  geom_edgespace(data = gs) +
  geom_nodespace(data = gs) +
  theme(aspect.ratio = 1)

}

}
\seealso{
\link{GraphSpace}, \link{geom_nodespace}, \link{geom_graphspace},
\link[ggplot2]{geom_segment}
}
