% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plot-transitions.R
\name{plot_trajectories}
\alias{plot_trajectories}
\title{Plot Individual Trajectories}
\usage{
plot_trajectories(
  x,
  from_title = NULL,
  title = NULL,
  from_colors = NULL,
  flow_color_by = "first",
  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,
  line_alpha = 0.3,
  line_width = 0.5,
  jitter_amount = 0.8,
  show_totals = FALSE,
  total_size = 4,
  total_color = "white",
  total_fontface = "bold",
  show_values = FALSE,
  value_position = c("center", "origin", "destination"),
  value_size = 3,
  value_color = "black",
  value_halo = NULL,
  value_fontface = "bold",
  value_nudge = 0.03,
  value_min = 0,
  value_digits = 2,
  column_gap = 1,
  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}{Data frame with one column per time point and one row per
individual trajectory.}

\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{title}{Optional plot title. Applied via ggplot2::labs(title = title).}

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

\item{flow_color_by}{Color trajectory lines by state. Supports
\code{"source"}, \code{"destination"}, \code{"first"}, \code{"last"}, or
NULL. Default \code{"first"}.}

\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{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{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{show_values}{Logical: show transition counts on flows? Default FALSE.}

\item{value_position}{Position of trajectory value labels: \code{"center"},
\code{"origin"}, or \code{"destination"}. Default \code{"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{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{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 alluvial-style diagram where each individual's trajectory is shown
as a separate line. This is an alias for \code{plot_transitions()} with
\code{track_individuals = TRUE}.
}
\examples{
df <- data.frame(
  Baseline = c("Light", "Light", "Intense", "Resource"),
  Week4    = c("Light", "Intense", "Intense", "Light"),
  Week8    = c("Resource", "Intense", "Light", "Light"))
plot_trajectories(df, flow_color_by = "first")

}
\seealso{
\code{\link{plot_transitions}}, \code{\link{plot_alluvial}}
}
