% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/enrich.R
\name{EnrichMapAtomic}
\alias{EnrichMapAtomic}
\title{Atomic enrichment map (internal)}
\usage{
EnrichMapAtomic(
  data,
  in_form = "clusterProfiler",
  top_term = 100,
  metric = "p.adjust",
  layout = "fr",
  minchar = 2,
  cluster = "fast_greedy",
  show_keyword = FALSE,
  nlabel = 4,
  character_width = 50,
  words_excluded = plotthis::words_excluded,
  mark = "ellipse",
  label = c("term", "feature"),
  labelsize = 5,
  expand = c(0.4, 0.4),
  theme = "theme_this",
  theme_args = list(),
  palette = "Paired",
  palcolor = NULL,
  palreverse = FALSE,
  alpha = 1,
  aspect.ratio = 1,
  legend.position = "right",
  legend.direction = "vertical",
  title = NULL,
  subtitle = NULL,
  xlab = NULL,
  ylab = NULL,
  seed = 8525,
  ...
)
}
\arguments{
\item{data}{A data frame containing enrichment results in clusterProfiler
format with at least the columns: \code{Description}, \code{GeneRatio},
\code{pvalue}, \code{p.adjust}, and \code{geneID}.
\itemize{
\item \code{ID}, \code{qvalue}, \code{BgRatio}, and \code{Count} are
optional.
\item \code{Description} is the term description, displayed as the
default keyword.
\item \code{GeneRatio} is the fraction of input genes annotated to
the term (e.g. \code{"10/500"}).
\item \code{BgRatio} is the fraction of background genes annotated
to the term (e.g. \code{"50/20000"}).
\item \code{Count}, if given, must equal the numerator of
\code{GeneRatio}.
\item \code{geneID} contains gene symbols separated by \code{"/"}.
}}

\item{in_form}{A character string specifying the input format.
When \code{"auto"} (default), the function infers the format from the
column names: clusterProfiler columns (\code{pvalue}, \code{p.adjust},
\code{qvalue}) or Enrichr columns (\code{P.value},
\code{Adjusted.P.value}).  Other options are \code{"clusterProfiler"}
and \code{"enrichr"}.}

\item{top_term}{An integer specifying the maximum number of terms to
include.  Terms are ranked by \code{metric} (ascending).  Default
\code{100}.}

\item{metric}{A character string specifying the significance metric
used for top-term selection and node scoring: \code{"p.adjust"}
(default) or \code{"pvalue"}.  The value is transformed as
\eqn{-\log_{10}(metric)}.}

\item{layout}{A character string naming the igraph layout algorithm.
Built-in shortcuts: \code{"circle"}, \code{"tree"}, \code{"grid"}.
Otherwise, the suffix passed to \code{layout_with_<layout>} in igraph
(e.g. \code{"fr"} for Fruchterman-Reingold, \code{"kk"} for
Kamada-Kawai).  Default \code{"fr"}.}

\item{minchar}{An integer specifying the minimum character length for
words to be included as keywords when \code{show_keyword = TRUE}.
Default \code{2}.}

\item{cluster}{A character string naming the igraph community detection
algorithm.  The suffix passed to \code{cluster_<cluster>} in igraph
(e.g. \code{"fast_greedy"}, \code{"walktrap"},
\code{"edge_betweenness"}, \code{"infomap"}).  Default
\code{"fast_greedy"}.}

\item{show_keyword}{A logical value.  When \code{TRUE}, the
\code{Description} text is tokenized and the most significant words
per cluster are shown as keywords.  When \code{FALSE} (default), the
original term descriptions are used as labels.}

\item{nlabel}{An integer specifying the number of keywords or term
descriptions to show per cluster in the legend labels.  Default
\code{4}.}

\item{character_width}{An integer specifying the maximum width (in
characters) at which keyword labels are wrapped via
\code{strwrap(width = character_width)}.  Default \code{50}.}

\item{words_excluded}{A character vector of words to exclude from
keyword extraction when \code{show_keyword = TRUE}.  Defaults to
\code{plotthis::words_excluded}.}

\item{mark}{A character string naming the ggforce hull function.
One of \code{"ellipse"} (default), \code{"rect"}, \code{"circle"}, or
\code{"text"} -- passed as the suffix to \code{geom_mark_<mark>}.}

\item{label}{A character string specifying what information to display
in the legend labels.  Either \code{"term"} (default; shows top term
descriptions/keywords per cluster) or \code{"feature"} (shows top
gene symbols per cluster).}

\item{labelsize}{A numeric value specifying the font size of the
cluster labels drawn by the ggforce mark layer.  Default \code{5}.}

\item{expand}{A numeric vector of length 2 (or 4) specifying the
expansion of the x and y axes, processed via
\code{\link{norm_expansion}()}.  Default \code{c(0.4, 0.4)}.}

\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{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{alpha}{A numeric value specifying the transparency of the plot.}

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

\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{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{seed}{The random seed to use. Default is 8525.}

\item{...}{Additional arguments.}
}
\value{
A \code{ggplot} object with \code{height} and \code{width}
attributes (in inches) attached.
}
\description{
Core implementation for drawing a single enrichment map -- a gene-set
similarity network where nodes represent enriched terms, node fill colour
encodes cluster membership, node size encodes the number of genes per
term, and edge thickness encodes the number of overlapping genes between
pairs of terms.  This is the workhorse behind the exported
\code{\link{EnrichMap}} function -- it takes a \strong{single} data frame (no
\code{split_by} support) and returns a \code{ggplot} object.

The function constructs an undirected graph from the term-term gene
overlap matrix, computes a force-directed layout, detects term clusters
via igraph community detection, and renders the result as a labelled
network plot with ggforce hull annotations around each cluster.
}
\section{Architecture}{

\enumerate{
\item \strong{ggplot dispatch} -- selects \code{gglogger::ggplot} or
\code{ggplot2::ggplot} based on
\code{getOption("plotthis.gglogger.enabled")}.
\item \strong{Data format conversion} -- if \code{data} inherits from
\code{"enrichResult"}, converts via \code{as.data.frame()}; if
\code{in_form == "enrichr"}, calls
\code{\link{prepare_enrichr_result}()} to rename columns and
infer GeneRatio/BgRatio.
\item \strong{Column validation} -- \code{\link{check_columns}()}
verifies that \code{Description}, \code{GeneRatio},
\code{pvalue}, \code{p.adjust}, and \code{geneID} are present.
\item \strong{Top-term selection} -- when \code{top_term} is not
\code{NULL}, selects the top N terms by the chosen \code{metric}
via \code{dplyr::slice_min()}.
\item \strong{Metric transformation} -- computes
\eqn{-\log_{10}(metric)} as the node scoring variable.  Splits
\code{geneID} on \code{"/"} to obtain per-term gene lists.
\item \strong{ID assignment} -- uses the \code{ID} column if present;
otherwise falls back to row names or generates synthetic IDs
(\code{"GS1"}, \code{"GS2"}, \dots).
\item \strong{Edge construction} -- creates all pairwise combinations
(\code{utils::combn()}) of term IDs and computes the overlap
count (intersection of geneID elements) as edge weight.  Edges
with weight 0 are dropped.
\item \strong{igraph graph construction} --
\code{igraph::graph_from_data_frame()} builds an undirected
graph from the edge list, with node attributes from the term
data.
\item \strong{Layout computation} -- dispatches to the chosen igraph
layout function (\code{layout_with_*}) or one of the built-in
shortcuts (\code{"circle"}, \code{"tree"}, \code{"grid"}).
\item \strong{Cluster detection} -- runs the chosen igraph clustering
algorithm (\code{cluster_*}) to group related terms into
modules.
\item \strong{Node coordinates} -- extracts vertex positions and
cluster assignments into a data frame with \code{dim1},
\code{dim2}, and \code{clusters} columns.
\item \strong{Keyword extraction} -- when \code{show_keyword = TRUE},
tokenizes \code{Description} text, filters words by
\code{minchar} and \code{words_excluded}, scores remaining
words by summed \code{metric} per cluster, and keeps the top
\code{nlabel} keywords.  Otherwise, the term \code{Description}
texts themselves are used as keywords.
\item \strong{Gene keyword extraction} -- always computes per-cluster
gene-level keywords (top \code{nlabel} genes by summed
\code{metric}) for the feature legend mode.
\item \strong{Mark layer} -- \code{ggforce::geom_mark_*()} (ellipse,
rect, circle, or text) draws cluster hulls with labels
containing the cluster ID and either term or feature keywords.
\item \strong{Edge rendering} -- \code{ggplot2::geom_segment()} draws
edges with line width proportional to overlap weight.
\item \strong{Node rendering} -- \code{ggplot2::geom_point(shape = 21)}
draws nodes sized by \code{Count} and filled by cluster
membership.
\item \strong{Scale configuration} -- \code{scale_size()} for node
size, \code{scale_linewidth()} for edge width,
\code{scale_fill_manual()} for cluster colours with custom
legend labels (term keywords or gene keywords depending on
\code{label}).
\item \strong{Theme and dimensions} -- applies the resolved theme,
sets aspect ratio and legend position, then calls
\code{\link{calculate_plot_dimensions}()} to attach
\code{height}/\code{width} attributes.
}
}

\keyword{internal}
