% 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). In
multi-step and individual-tracking plots, ignored when \code{flow_color_by}
is set; simple two-column aggregate plots use \code{flow_fill}.}

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

\item{flow_color_by}{Color flows by state. For multi-step aggregate flows,
use \code{"source"} or \code{"destination"}; for individual trajectories,
\code{"first"} and \code{"last"} are also supported. Default NULL uses
\code{flow_fill}; simple two-column aggregate plots ignore this argument.}

\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 in individual-tracking plots. 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". Applied to
multi-step and individual-tracking plots; simple two-column aggregate plots
use black external labels and white inside labels.}

\item{label_fontface}{Font face of state name labels ("plain", "bold", "italic",
"bold.italic"). Default "plain". Applied to multi-step and
individual-tracking plots; simple two-column aggregate plots use fixed
label font faces.}

\item{label_nudge}{Distance between node edge and label (in plot units).
Default 0.02. Used by multi-step and individual-tracking plots.}

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

\item{title_color}{Color of column title text. Default "black". Applied to
multi-step and individual-tracking plots; simple two-column aggregate plots
use black titles.}

\item{title_fontface}{Font face of column titles. Default "bold". Applied to
multi-step and individual-tracking plots.}

\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}). Applied to multi-step and
individual-tracking plots.}

\item{value_fontface}{Font face of flow value labels. Default "bold".
Applied to multi-step and individual-tracking plots.}

\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 in multi-step and
individual-tracking plots. Default 0 (show all). Simple two-column
aggregate plots show all nonzero value labels when \code{show_values = TRUE}.}

\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) for multi-step and
individual-tracking plots. 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 in
individual-tracking plots? Default TRUE.}

\item{node_label_format}{Format string for node labels with \code{{state}} and
\code{{count}} placeholders in individual-tracking plots. 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{
# From a transition matrix
mat <- matrix(c(50, 10, 5, 15, 40, 10, 5, 20, 30), 3, 3, byrow = TRUE,
              dimnames = list(c("Light","Resource","Intense"),
                              c("Light","PBL","Resource")))
plot_transitions(mat, from_title = "Time 1", to_title = "Time 2")

# From a 2-column data frame (auto-contingency)
df <- data.frame(time1 = c("A","A","B","B","C"),
                 time2 = c("X","Y","X","Z","Y"))
plot_transitions(df)

}
