% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plot-transitions.R
\name{plot_transitions}
\alias{plot_transitions}
\title{Plot Transitions Between States}
\usage{
plot_transitions(
  x,
  from_title = "From",
  to_title = "To",
  title = NULL,
  from_colors = NULL,
  to_colors = NULL,
  flow_fill = "#888888",
  flow_alpha = 0.4,
  flow_color_by = NULL,
  flow_border = NA,
  flow_border_width = 0.5,
  node_width = 0.08,
  node_border = NA,
  node_spacing = 0.02,
  label_size = 3.5,
  label_position = c("beside", "inside", "above", "below", "outside"),
  mid_label_position = NULL,
  label_halo = TRUE,
  label_color = "black",
  label_fontface = "plain",
  label_nudge = 0.02,
  title_size = 5,
  title_color = "black",
  title_fontface = "bold",
  curve_strength = 0.6,
  show_values = FALSE,
  value_position = c("center", "origin", "destination", "outside_origin",
    "outside_destination"),
  value_size = 3,
  value_color = "black",
  value_halo = NULL,
  value_fontface = "bold",
  value_nudge = 0.03,
  value_min = 0,
  show_totals = FALSE,
  total_size = 4,
  total_color = "white",
  total_fontface = "bold",
  conserve_flow = TRUE,
  min_flow = 0,
  threshold = 0,
  value_digits = 2,
  column_gap = 1,
  track_individuals = FALSE,
  line_alpha = 0.3,
  line_width = 0.5,
  jitter_amount = 0.8,
  proportional_nodes = TRUE,
  node_label_format = NULL,
  bundle_size = NULL,
  bundle_legend = TRUE,
  bundle_legend_size = 3,
  bundle_legend_color = "grey50",
  bundle_legend_fontface = "italic",
  bundle_legend_position = c("bottom", "top")
)
}
\arguments{
\item{x}{Input data in one of several formats:
\itemize{
\item A transition matrix (rows = from, cols = to, values = counts)
\item Two vectors: pass \code{before} as x and \code{after} as second argument
(contingency table computed automatically, like chi-square)
\item A 2-column data frame (raw observations; table computed automatically)
\item A data frame with columns: from, to, count
\item A list of matrices for multi-step transitions
}}

\item{from_title}{Title for the left column. Default "From". For multi-step,
use a vector of titles (e.g., c("T1", "T2", "T3", "T4")).}

\item{to_title}{Title for the right column. Default "To". Ignored for multi-step.}

\item{title}{Optional plot title. Applied via ggplot2::labs(title = title).}

\item{from_colors}{Colors for left-side nodes. Default uses palette.}

\item{to_colors}{Colors for right-side nodes. Default uses palette.}

\item{flow_fill}{Fill color for flows. Default "#888888" (grey). Ignored if flow_color_by is set.}

\item{flow_alpha}{Alpha transparency for flows. Default 0.4.}

\item{flow_color_by}{Color flows by "source", "destination", or NULL (use flow_fill). Default NULL.}

\item{flow_border}{Border color for flows. Default NA (no border).}

\item{flow_border_width}{Line width for flow borders. Default 0.5.}

\item{node_width}{Width of node rectangles (0-1 scale). Default 0.08.}

\item{node_border}{Border color for nodes. Default NA (no border).}

\item{node_spacing}{Vertical spacing between nodes (0-1 scale). Default 0.02.}

\item{label_size}{Size of node labels. Default 3.5.}

\item{label_position}{Position of node labels: "beside" (default), "inside", "above", "below", "outside".
Applied to first and last columns. See \code{mid_label_position} for middle columns.}

\item{mid_label_position}{Position of labels for intermediate (middle) columns.
Same options as \code{label_position}. Default NULL uses \code{label_position} value.}

\item{label_halo}{Logical: add white halo around labels for readability? Default TRUE.}

\item{label_color}{Color of state name labels. Default "black".}

\item{label_fontface}{Font face of state name labels ("plain", "bold", "italic",
"bold.italic"). Default "plain".}

\item{label_nudge}{Distance between node edge and label (in plot units).
Default 0.02. Increase for more spacing.}

\item{title_size}{Size of column titles. Default 5.}

\item{title_color}{Color of column title text. Default "black".}

\item{title_fontface}{Font face of column titles. Default "bold".}

\item{curve_strength}{Controls bezier curve shape (0-1). Default 0.6.}

\item{show_values}{Logical: show transition counts on flows? Default FALSE.}

\item{value_position}{Position of flow values: "center", "origin", "destination",
"outside_origin", "outside_destination". Default "center".}

\item{value_size}{Size of value labels on flows. Default 3.}

\item{value_color}{Color of value labels. Default "black".}

\item{value_halo}{Logical: add halo around flow value labels? Default NULL
(inherits from \code{label_halo}).}

\item{value_fontface}{Font face of flow value labels. Default "bold".}

\item{value_nudge}{Distance of value labels from node edge when using
"origin" or "destination" positions. Default 0.03.}

\item{value_min}{Minimum count to show a flow value label. Default 0 (show all).
Use to hide small flows (e.g., \code{value_min = 100}).}

\item{show_totals}{Logical: show total counts on nodes? Default FALSE.}

\item{total_size}{Size of total labels. Default 4.}

\item{total_color}{Color of total labels. Default "white".}

\item{total_fontface}{Font face of total labels. Default "bold".}

\item{conserve_flow}{Logical: should left and right totals match? Default TRUE.
When FALSE, each side scales independently (allows for "lost" or "gained" items).}

\item{min_flow}{Minimum flow value to display. Default 0 (show all).}

\item{threshold}{Minimum edge weight to display. Flows below this value are
removed. Combined with \code{min_flow}: effective minimum is
\code{max(threshold, min_flow)}. Default 0.}

\item{value_digits}{Number of decimal places for flow value labels and node
totals. Default 2.}

\item{column_gap}{Horizontal spread of columns (0-1). Default 1 uses full width.
Use smaller values (e.g., 0.6) to bring columns closer together.}

\item{track_individuals}{Logical: draw individual lines instead of aggregated flows?
Default FALSE. When TRUE, each row in the data frame becomes a separate line.}

\item{line_alpha}{Alpha for individual tracking lines. Default 0.3.}

\item{line_width}{Width of individual tracking lines. Default 0.5.}

\item{jitter_amount}{Vertical jitter for individual lines (0-1). Default 0.8.}

\item{proportional_nodes}{Logical: size nodes proportionally to counts? Default TRUE.}

\item{node_label_format}{Format string for node labels with \code{{state}} and
\code{{count}} placeholders. Default NULL (plain state name).
Example: \code{"{state} (n={count})"}.}

\item{bundle_size}{Controls line bundling for large datasets. Default NULL (no bundling).
Integer >= 2: each drawn line represents that many cases.
Numeric in (0,1): reduce to this fraction of original lines
(e.g., 0.15 keeps about 15 percent of lines).}

\item{bundle_legend}{Logical or character: show annotation when bundling is
active? Default TRUE shows "Each line ~ N cases" below the plot.
Pass a string to use custom text (with \code{{n}} placeholder for count).}

\item{bundle_legend_size}{Size of the bundle legend text. Default 3.}

\item{bundle_legend_color}{Color of the bundle legend text. Default "grey50".}

\item{bundle_legend_fontface}{Font face of the bundle legend text. Default "italic".}

\item{bundle_legend_position}{Position of the bundle legend: "bottom" (default)
or "top".}
}
\value{
A ggplot2 object.
}
\description{
Creates an elegant alluvial/Sankey diagram showing how items flow from
one set of categories to another. Useful for visualizing cluster
transitions, state changes, or any categorical mapping.
}
\details{
The function creates smooth bezier curves connecting nodes from the left
column to the right column. Flow width is proportional to the transition
count. Nodes are sized proportionally to their total flow.
}
\examples{
\dontrun{
# From a transition matrix
mat <- matrix(c(50, 10, 5, 15, 40, 10, 5, 20, 30), 3, 3, byrow = TRUE)
rownames(mat) <- c("Light", "Resource", "Intense")
colnames(mat) <- c("Light", "PBL", "Resource")
plot_transitions(mat, from_title = "Time 1", to_title = "Time 2")

# From a 2-column data frame - auto-computes contingency table
before <- c("A", "A", "B", "B", "A", "C", "B", "C")
after <- c("X", "Y", "X", "Z", "X", "Y", "Z", "X")
df <- data.frame(time1 = before, time2 = after)
plot_transitions(df, from_title = "Time 1", to_title = "Time 2")

# Custom colors
plot_transitions(mat,
  from_colors = c("#FFD166", "#06D6A0", "#9D4EDD"),
  to_colors = c("#FFD166", "#EF476F", "#06D6A0")
)
}

\dontrun{
# Multi-step transitions (list of matrices)
mat1 <- matrix(c(40, 10, 5, 15, 35, 5, 5, 15, 25), 3, 3, byrow = TRUE,
               dimnames = list(c("A","B","C"), c("A","B","C")))
mat2 <- matrix(c(35, 15, 5, 10, 30, 10, 10, 10, 30), 3, 3, byrow = TRUE,
               dimnames = list(c("A","B","C"), c("A","B","C")))
mat3 <- matrix(c(30, 20, 5, 5, 25, 15, 15, 5, 35), 3, 3, byrow = TRUE,
               dimnames = list(c("A","B","C"), c("A","B","C")))
plot_transitions(list(mat1, mat2, mat3),
  from_title = c("T1", "T2", "T3", "T4"),
  show_totals = TRUE
)
}

}
