% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plot-chord.R
\name{plot_chord}
\alias{plot_chord}
\title{Chord Diagram}
\usage{
plot_chord(
  x,
  directed = NULL,
  segment_colors = NULL,
  segment_border_color = "white",
  segment_border_width = 1,
  segment_pad = 0.02,
  segment_width = 0.08,
  chord_color_by = "source",
  chord_alpha = 0.5,
  chord_border = NA,
  self_loop = TRUE,
  labels = NULL,
  label_size = 1,
  label_color = "black",
  label_offset = 0.05,
  label_threshold = 0,
  threshold = 0,
  ticks = FALSE,
  tick_interval = NULL,
  tick_labels = TRUE,
  tick_size = 0.6,
  tick_color = "grey30",
  start_angle = pi/2,
  clockwise = TRUE,
  title = NULL,
  title_size = 1.2,
  background = NULL,
  ...
)
}
\arguments{
\item{x}{A weight matrix, \code{cograph_network}, \code{CographNetwork},
\code{tna}, \code{igraph}, or list-like object with a matrix
\code{weights} component.}

\item{directed}{Logical. If \code{NULL} (default), auto-detected from
matrix symmetry.}

\item{segment_colors}{Colors for the outer ring segments. \code{NULL} uses
a built-in vibrant palette.}

\item{segment_border_color}{Border color for segments.}

\item{segment_border_width}{Border width for segments.}

\item{segment_pad}{Gap between segments in radians.}

\item{segment_width}{Radial thickness of the outer ring as a fraction of
the radius.}

\item{chord_color_by}{How to color chords: \code{"source"} (default),
\code{"target"}, or a color vector of length matching the number of
non-zero edges.}

\item{chord_alpha}{Alpha transparency for chords.}

\item{chord_border}{Border color for chords. \code{NA} for no border.}

\item{self_loop}{Logical. Currently accepted for API compatibility; the
current matrix preparation preserves self-loop chords.}

\item{labels}{Node labels. \code{NULL} uses row names, \code{FALSE}
suppresses labels.}

\item{label_size}{Text size multiplier for labels.}

\item{label_color}{Color for labels.}

\item{label_offset}{Radial offset of labels beyond the outer ring.}

\item{label_threshold}{Hide labels for nodes whose flow fraction is below
this value.}

\item{threshold}{Minimum absolute weight to show a chord.}

\item{ticks}{Logical. Draw tick marks along the outer ring to indicate
magnitude?}

\item{tick_interval}{Spacing between ticks in the same units as the weight
matrix. \code{NULL} (default) auto-selects a nice interval.}

\item{tick_labels}{Logical. Show numeric labels at major ticks?}

\item{tick_size}{Text size multiplier for tick labels.}

\item{tick_color}{Color for tick marks and labels.}

\item{start_angle}{Starting angle in radians (default \code{pi/2}, top).}

\item{clockwise}{Logical. Lay out segments clockwise?}

\item{title}{Optional plot title.}

\item{title_size}{Text size multiplier for the title.}

\item{background}{Background color for the plot. \code{NULL} (default) uses
the current device background.}

\item{...}{Additional arguments (currently ignored).}
}
\value{
Invisibly returns a list with components \code{segments} (data frame
of segment angles and flows) and \code{chords} (data frame of chord
endpoints and weights).
}
\description{
Draw a chord diagram where nodes are arcs on the outer ring and edges are
curved ribbons (chords) connecting them. Arc size is proportional to total
flow through each node and chord width is proportional to edge weight.
}
\details{
The diagram is drawn entirely with base R graphics using \code{polygon()}
for segments and chords, and \code{bezier_points()} for the curved ribbons.

For directed networks, each segment is split into an outgoing half and an
incoming half so that chords attach to the correct side. For undirected
networks each edge is drawn once and the full segment arc is shared.
}
\examples{
# Weighted directed matrix
mat <- matrix(c(
   0, 25,  5, 15,
  10,  0, 20,  8,
   3, 18,  0, 30,
  20,  5, 10,  0
), 4, 4, byrow = TRUE,
dimnames = list(c("A", "B", "C", "D"), c("A", "B", "C", "D")))

plot_chord(mat)
plot_chord(mat, chord_alpha = 0.6, ticks = TRUE)

if (requireNamespace("tna", quietly = TRUE)) {
  # TNA transition network
  model <- tna::tna(tna::group_regulation)
  plot_chord(model, ticks = TRUE, segment_width = 0.10)
}

}
