% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plot-simplicial.R
\name{plot_simplicial}
\alias{plot_simplicial}
\title{Simplicial Complex Visualization}
\usage{
plot_simplicial(
  x = NULL,
  pathways = NULL,
  method = "hon",
  max_pathways = 10L,
  layout = "circle",
  labels = NULL,
  node_color = "#4A7FB5",
  target_color = "#E8734A",
  ring_color = "#F5A623",
  node_size = 22,
  label_size = 5,
  blob_alpha = 0.25,
  blob_colors = NULL,
  blob_linetype = NULL,
  blob_linewidth = 0.7,
  blob_line_alpha = 0.8,
  shadow = TRUE,
  title = NULL,
  dismantled = FALSE,
  ncol = NULL,
  ...
)
}
\arguments{
\item{x}{A network object: \code{tna}, \code{netobject}, matrix,
\code{igraph}, \code{cograph_network}, \code{net_hon}, or
\code{net_hypa}. When \code{x} is a \code{tna} or
\code{netobject} with sequence data and \code{pathways} is
\code{NULL}, higher-order pathways are built automatically
using the \code{method} parameter.}

\item{pathways}{Character vector of pathway strings, a list of
character vectors, or a \code{net_hon} / \code{net_hypa} object.
String separators: \code{"A B -> C"}, \code{"A, B, C"},
\code{"A - B - C"}, \code{"A B C"}. Last state is the target.
When \code{NULL} and \code{x} is a model with sequence data,
pathways are built automatically.}

\item{method}{Higher-order method when auto-building from a
\code{tna}/\code{netobject}: \code{"hon"} (default) or
\code{"hypa"}.}

\item{max_pathways}{Maximum number of pathways to display. HON
pathways are ranked by count, HYPA by anomaly ratio.
\code{NULL} shows all. Default \code{10}.}

\item{layout}{\code{"circle"} (default) or a coordinate matrix.}

\item{labels}{Display labels. \code{NULL} uses state names.}

\item{node_color}{Source node fill color.}

\item{target_color}{Target node fill color.}

\item{ring_color}{Donut ring color.}

\item{node_size}{Node point size.}

\item{label_size}{Label text size.}

\item{blob_alpha}{Blob fill transparency.}

\item{blob_colors}{Blob fill colors (recycled).}

\item{blob_linetype}{Blob border line styles (recycled).}

\item{blob_linewidth}{Blob border line width.}

\item{blob_line_alpha}{Blob border line transparency.}

\item{shadow}{Draw soft drop shadows?}

\item{title}{Plot title.}

\item{dismantled}{If \code{TRUE}, one panel per pathway arranged
in a grid layout.}

\item{ncol}{Number of columns in the grid when \code{dismantled = TRUE}.
Default \code{NULL} auto-selects based on the number of pathways.}

\item{...}{Additional arguments passed to
\code{Nestimate::build_hon()} or \code{Nestimate::build_hypa()}
when auto-building.}
}
\value{
A \code{ggplot} object (or combined grid if dismantled),
invisibly.
}
\description{
Visualize higher-order pathways as smooth blobs overlaid on a
network layout. Source nodes are blue, target nodes are red.
}
\details{
Supports direct use with \code{tna} and \code{netobject} models:
when \code{x} has sequence data, HON or HYPA pathways are built
automatically (requires the \pkg{Nestimate} package). Pathways can
also be passed as \code{net_hon} or \code{net_hypa} objects, with
labels auto-translated when \code{x} is a \code{tna}/\code{netobject}.
}
\examples{
\dontrun{
mat <- matrix(runif(16), 4, 4,
              dimnames = list(LETTERS[1:4], LETTERS[1:4]))
diag(mat) <- 0
plot_simplicial(mat, c("A B -> C", "B C -> D"))

# Direct from tna model (requires Nestimate):
# model <- tna::tna(tna::group_regulation)
# plot_simplicial(model, dismantled = TRUE)
# plot_simplicial(model, method = "hypa")

# With pre-built HON + tna for label translation:
# hon <- Nestimate::build_hon(as.data.frame(model$data))
# plot_simplicial(model, hon, dismantled = TRUE)
}

}
