% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ggnetview.R
\name{ggNetView}
\alias{ggNetView}
\title{Visualize a network with custom layouts}
\usage{
ggNetView(
  graph_obj,
  layout = NULL,
  node_add = 7,
  ring_n = NULL,
  r = 1,
  center = TRUE,
  idx = NULL,
  shrink = 1,
  inner_shrink = 1,
  k_nn = 12,
  push_others_delta = 0,
  layout.module = c("random", "adjacent", "order"),
  shape = 21,
  pointalpha = 1,
  pointsize = c(1, 10),
  pointstroke = 0.3,
  pointlabel = NULL,
  pointlabelsize = 5,
  group.by = "Modularity",
  fill.by = "Modularity",
  color.by = NULL,
  fill = NULL,
  color = NULL,
  jitter = FALSE,
  jitter_sd = 0.1,
  plot_line = TRUE,
  mapping_line = FALSE,
  curve = F,
  curvature = 0.25,
  linealpha = 0.25,
  linecolor = "grey70",
  label = FALSE,
  labelsize = 10,
  labelsegmentsize = 1,
  labelsegmentalpha = 1,
  label_layout = c("two_column", "two_column_follow", "label_circle"),
  label_wrap_width = NULL,
  label_outer_pad = 0.25,
  add_group_outer = FALSE,
  add_group_outer_expand = 2,
  add_group_outer_color = "grey50",
  add_group_outer_fill = NULL,
  add_group_outer_fill_alpha = 0.2,
  add_group_outer_linetype = 1,
  add_group_outer_linewidth = 0.5,
  add_outer = FALSE,
  q_outer = 0.88,
  expand_outer = 1.02,
  bandwidth_scale = 2,
  outerwidth = 1,
  outerlinetype = 1,
  outeralpha = 0.5,
  nodelabsize = 5,
  remove = FALSE,
  dropOthers = FALSE,
  orientation = "up",
  angle = 0,
  scale = T,
  anchor_dist = 6,
  nrow = NULL,
  ncol = NULL,
  seed = 1115,
  scale_radius = NULL,
  return_layout = FALSE
)
}
\arguments{
\item{graph_obj}{An graph object from build_graph_from_mat or build_graph_from_df.
The network object to be visualized.}

\item{layout}{Character string.
Custom layouts; one of "gephi", "square", "square2", "petal",
"petal2", "heart_centered","diamond", "star", "star_concentric","rectangle,
"rightiso_layers" etc.}

\item{node_add}{Integer (default = 7).
Number of nodes to add in each layer of the layout.}

\item{ring_n}{Numeric (default = 7)
Numbers of ring in rings layout.}

\item{r}{Numeric (default = 1).
Radius increment for concentric or layered layouts.}

\item{center}{Logical (default = TRUE).
Whether to place a node at the center of the layout.}

\item{idx}{Optional.
Index of nodes to be emphasized or centered in the layout}

\item{shrink}{Numeric (default = 1).
Shrinkage factor applied to the center points.}

\item{inner_shrink}{Numeric (default = 1).
Intra-module compactness factor for \code{layout = "WGCNA"} only.
Controls how tightly nodes fill each module's allocated disc during
the WGCNA bubble-pack layout: at \code{1} (default) nodes spread to
fill 95\% of the disc (original behaviour); smaller values
(e.g. \code{0.65}) contract the FR/uniform fill toward each module
centre, exposing hub/periphery structure and producing visible
inter-module whitespace.  Module disc centres and radii are
invariant under \code{inner_shrink}; this parameter only affects
the point cloud inside each module.  Ignored by all other layouts.}

\item{k_nn}{Numeric (default = 8).
Number of nearest neighbors used to build the local adjacency graph.}

\item{push_others_delta}{Numeric (default = 0).
Radial offset applied to the "Others" module to slightly}

\item{layout.module}{Character  (default = "random")
- random : modules are distributed more randomly and independently.
- adjacent : modules are positioned close to each other, minimizing inter-module gaps.
- order : modules are distributed by order, applicable to `Bipartite, Tripartite, Quadripartite, Multipartite, Pentapartite Layout`}

\item{shape}{Integer  (default = 21).
The point shape likely in ggplot2. If a character string is provided,
it must be a variable name in graph_object for point shape mapping.}

\item{pointalpha}{Integer  (default = 1).
The point alpha}

\item{pointsize}{Vector (default =  c(1,10))
The point size rang.}

\item{pointstroke}{Integer  (default = 0.3).}

\item{pointlabel}{Character (default = NULL).
Optional node label mode for top Degree nodes within each module.
Supported values: \code{"topN"} (e.g. \code{"top1"}, \code{"top7"}, \code{"top20"})
and \code{"ALL"}.}

\item{pointlabelsize}{Integer (default = 5).
Change point label size.}

\item{group.by}{Character (default = "Modularity").
Change group for nodes}

\item{fill.by}{Character (default = "Modularity").
Change fill for nodes}

\item{color.by}{Character (default = NULL).
Change color for nodes. If provided, must be a variable name in
graph_object. Numeric uses \code{scale_color_gradient},
otherwise uses \code{scale_color_manual} or \code{scale_color_ggnetview}.}

\item{fill}{Named vector of colors for node fill (e.g. \code{c("M1" = "red", "M2" = "blue")}).
If \code{NULL} (default), uses \code{scale_fill_ggnetview}; if provided, uses \code{scale_fill_manual(values = fill)}.}

\item{color}{Named vector of colors for node/edge/label color.
If \code{NULL} (default), uses \code{scale_color_ggnetview}; if provided, uses \code{scale_color_manual(values = color)}.}

\item{jitter}{Logical (default = FALSE).
Whether to apply jitter to points.}

\item{jitter_sd}{Integer  (default = 0.1).
The standard deviation of the jitter applied when `jitter = TRUE`.}

\item{plot_line}{Logical (default = TRUE).
Whether to plot line in net plot.}

\item{mapping_line}{Logical (default = FALSE).
Whether to mapping line in ggNetView. If a character string is provided,
it must be a variable name in graph_object for line color mapping.}

\item{curve}{Logical (default = FALSE).
Whether to plot curve line in net plot.}

\item{curvature}{Integer (default = 0.25)
The curve level of curve line when curve is TRUE}

\item{linealpha}{Integer  (default = 0.25).
Change  line alpha.}

\item{linecolor}{Character  (default = "grey70").
Change  line color.}

\item{label}{Logical or Character (default = \code{FALSE}).
Controls module label text and module legend prefix.
If \code{FALSE}, module text labels are not drawn and legend prefix uses
\code{"Modularity"}.
If \code{TRUE}, module text labels are drawn and legend prefix uses
\code{"Modularity"}.
If a character string, module text labels are drawn and that string is used
as prefix for module text and module legend labels.}

\item{labelsize}{Integer  (default = 10).
Change Module label size.}

\item{labelsegmentsize}{Integer  (default = 1).
Change  label segment size.}

\item{labelsegmentalpha}{Integer  (default = 1).
Change  label segment alpha.}

\item{label_layout}{Character (default = \code{"two_column"}).
Strategy used to place module text labels when \code{label} is not
\code{FALSE}. One of:
\itemize{
  \item \code{"two_column"} (default; backward compatible): modules whose
    centroid \code{x} is left of the network median go to a fixed left
    column at \code{x = xr[1] - dx}, the rest to a fixed right column at
    \code{x = xr[2] + dx}, with labels evenly distributed along \code{y}.
    Best for very crowded networks or layouts that read left-to-right
    (bipartite, grid).
  \item \code{"two_column_follow"}: 360-degree ring layout with
    two-segment "L-shape" leaders. Modules are sorted by their
    actual angle from the network centroid and assigned angularly
    equispaced target angles around the full \code{2*pi}, so
    labels are evenly distributed around the network while
    preserving the angular neighbour order. Each label is
    projected onto an outer ellipse whose semi-axes are
    \code{(1 + label_outer_pad)} times the network's half-width /
    half-height. The leader has two segments: the first leg is
    drawn manually via \code{geom_segment} from the module
    centroid to an elbow on the network boundary at the module's
    actual angle; the second leg is drawn by \code{ggrepel} from
    the label (which it may push tangentially with \code{force = 1}
    to avoid overlaps) back to that elbow. Use this when you need
    the L bend to be clearly visible and labels to never overlap.
  \item \code{"label_circle"}: 360-degree ring layout drawn
    entirely by \code{ggrepel}. Same equispacing as
    \code{"two_column_follow"} (so labels track module angular
    order around the outer ellipse), but no manual first leg --
    \code{ggrepel} handles both placement and the connecting
    segment, with \code{segment.square = TRUE} and
    \code{segment.squareShape = 0} so the leader is an L-shape
    between label and module centroid. Code is much simpler than
    \code{"two_column_follow"} and works well when modules are
    roughly evenly distributed around the network; the trade-off
    is that the L bend can visually collapse when a label happens
    to sit on its module's radial line (rare with full
    equispacing). Requires \code{ggrepel >= 0.9.4}.
}}

\item{label_wrap_width}{Integer or NULL (default = \code{NULL}).
If a positive integer, module text labels are wrapped to roughly that
many characters per line via \code{stringr::str_wrap()} before
rendering. Useful for long pathway / taxonomy names. Applies to every
\code{label_layout}.}

\item{label_outer_pad}{Numeric (default = \code{0.25}).
Fractional outward push of the label anchors, expressed as a multiple
of the network's \code{x}-range (for \code{"two_column"}) or as the
fractional enlargement of the outer label-anchor ellipse (for
\code{"two_column_follow"}). Larger values move labels further
away from the network and make the slanted second leg of the
\code{"two_column_follow"} L-shape leader more pronounced. Try
\code{0.20} for a tight layout that almost hugs the network,
\code{0.40} for the default breathing room, \code{0.55+} when
modules sit inside a thick \code{add_group_outer} ring or labels
are long.}

\item{add_group_outer}{Logical (default = FALSE).
Whether to add a circle boundary around the entire network (mimics \code{ggforce::geom_mark_circle}).}

\item{add_group_outer_expand}{Numeric (default = 2).
Expansion in mm for the group circle to account for point size; passed to \code{geom_mark_circle(expand = ...)}.}

\item{add_group_outer_color}{Character (default = "grey50").
Color of the group outer circle border.}

\item{add_group_outer_fill}{Character or NULL (default = NULL).
Fill color of the group outer circle. \code{NULL} = no fill (transparent).}

\item{add_group_outer_fill_alpha}{Numeric (default = 0.2).
Alpha (transparency) of the group outer circle fill; 0 = fully transparent, 1 = opaque.}

\item{add_group_outer_linetype}{Integer or character (default = 1).
Linetype of the group outer circle (e.g. 1 = solid, 2 = dashed).}

\item{add_group_outer_linewidth}{Numeric (default = 0.5).
Line width of the group outer circle.}

\item{add_outer}{Logical (default = FALSE).
Whether to draw a smooth outer boundary around each module. The boundary is
computed by 2D kernel density estimation followed by a Highest-Density-Region
(HDR) contour: it encloses the densest portion of each module rather than
all of its points. As a side effect, a single module whose points fall into
two well-separated clouds may produce two disconnected polygons (this is by
design and matches the behaviour of e.g. `mascarade`).}

\item{q_outer}{Numeric (default = 0.88).
HDR coverage of the outer boundary: the contour is drawn at the density
level whose iso-density region contains a fraction `q_outer` of the module's
empirical probability mass. Higher values make the boundary more inclusive
(closer to the convex hull of the module); lower values make it tighter
around the densest core. Sparse outliers/satellites typically fall outside
the contour and remain visible as bare nodes.
Note: modules with fewer than 10 nodes bypass the KDE path entirely and are
enclosed by a convex hull, so `q_outer` (and `bandwidth_scale`) have no
effect on them.}

\item{expand_outer}{Numeric (default = 1.02).
Multiplicative scaling applied to each polygon from its own centroid after
the HDR contour is drawn. Values > 1 slightly expand the boundary, values
< 1 slightly shrink it. Useful for adding a small visual breathing room
between the boundary and the nodes.}

\item{bandwidth_scale}{Numeric (default = 2.0).
Multiplier on the robust normal-reference 2D KDE bandwidth used to build the
outer boundary. Values > 1 produce smoother, wider contours (and may merge
nearby sub-clusters of a module into a single component); values < 1
produce tighter, more wiggly contours that follow local point density more
closely. Has no effect when \code{add_outer = FALSE} or when a module falls
back to the convex-hull path (very small clusters).}

\item{outerwidth}{Integer  (default = 1.25).
Change  outer linewidth.}

\item{outerlinetype}{Integer  (default = 2).
Change  outer linetype.}

\item{outeralpha}{Integer  (default = 0.5).
Change  outer alpha.}

\item{nodelabsize}{Integer  (default = 5).
Change  node label size.}

\item{remove}{Logical (default = FALSE).
Remove \code{"Others"} only at the visualization stage (post-layout),
so the layout of remaining modules is kept unchanged.}

\item{dropOthers}{Logical (default = FALSE).
If TRUE, remove nodes in the \code{"Others"} module from \code{graph_obj}
before layout and visualization, then recompute layout/plot from the
updated graph.}

\item{orientation}{Character string.
Custom orientation; one of "up","down","left","right".}

\item{angle}{Integer  (default = 0).
Change  orientation angle.}

\item{scale}{Logical  (default = T).
modules applicable to `Bipartite, Tripartite, Quadripartite, Multipartite, Pentapartite Layout` to scale the radius}

\item{anchor_dist}{Integer (default = 6)
the distance of each modules, applicable to `Bipartite, Tripartite, Quadripartite, Multipartite, Pentapartite Layout`}

\item{nrow}{Integer (default = NULL).
the nrow of network with layout is "consensus_module_equal_gephi" or "consensus_module_gephi"}

\item{ncol}{Integer (default = NULL).
the ncol of network with layout is "consensus_module_equal_gephi" or "consensus_module_gephi"}

\item{seed}{Integer (default = 1115).
Random seed for reproducibility.}

\item{scale_radius}{Numeric or NULL (default = NULL).
When non-NULL, scale the layout so the network fits within this radius.
Used by \code{ggnetview_modularity_heatmaps} for coordinate alignment.}

\item{return_layout}{Logical (default = FALSE).
When TRUE, return a list with \code{$plot} (ggplot) and \code{$layout_data}
(graph_ly_final, graph_obj, ggplot_data, module_centroids) for downstream
use (e.g. adding heatmaps and links).}
}
\value{
A ggplot object, or when \code{return_layout = TRUE}, a list with
\code{$plot} and \code{$layout_data}.
}
\description{
Visualize a network with custom layouts
}
\examples{
data(ppi_example)
obj <- build_graph_from_df(
  df              = ppi_example$ppi,
  node_annotation = ppi_example$annotation,
  module.method   = "Fast_greedy",
  top_modules     = 5
)

ggNetView(
  graph_obj     = obj,
  layout        = "fr",
  layout.module = "adjacent",
  pointsize     = c(3, 8),
  seed          = 1115
)
\donttest{
ggNetView(
  graph_obj       = obj,
  layout          = "gephi",
  layout.module   = "adjacent",
  pointsize       = c(3, 8),
  label           = TRUE,
  add_group_outer = TRUE,
  seed            = 1115
)
}
}
