% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plot_entropy_trajectories.R
\name{plot_entropy_trajectories}
\alias{plot_entropy_trajectories}
\title{Plot Shannon Entropy Trajectories}
\usage{
plot_entropy_trajectories(
  part_data,
  sites = NULL,
  labels = NULL,
  site_colors = NULL,
  by_group = FALSE,
  groups_list = NULL,
  line_type_groups = NULL,
  line_size_groups = NULL,
  transformation = NULL,
  line_size = 1.5,
  legend = TRUE,
  legend_text_size = 12,
  x_angle = 45,
  grayscale = FALSE,
  plot_title = "Shannon Entropy Trajectories"
)
}
\arguments{
\item{part_data}{Named list.  Output of \code{\link{partition_time_windows}},
optionally with per-partition \code{Clusters[[i]]$DataFrame} already
relabeled by the user via \code{\link{relabel_entropy_classes}}.  Must
contain elements \code{Clusters}, \code{Max_Entropy}, \code{Dates_Labels},
and \code{N_partitions}.}

\item{sites}{Integer vector.  Site indices to include.  Defaults to the
union of all sites observed across all partitions (i.e. every site that
has non-zero, non-singleton entropy in at least one partition window).}

\item{labels}{Character vector of length \code{N_partitions}.  Partition
labels used on the x-axis.  Defaults to \code{part_data$Dates_Labels}.}

\item{site_colors}{Named character vector.  Names are site indices as
character strings (e.g. \code{"681"}); values are colour strings
(e.g. \code{"#FB8072"}).  Sites absent from \code{site_colors} receive
automatically assigned colours.  Default is \code{NULL} (all colours
auto-assigned).}

\item{by_group}{Logical.  If \code{TRUE}, maps line type and line width to
site groups defined by \code{groups_list}.  Default is \code{FALSE}.}

\item{groups_list}{List of integer vectors.  Each element specifies the
site indices belonging to one explicit group.  Sites in \code{sites} not
covered by any explicit group are automatically assigned to a remainder
group appended as the final element.  Total group count (explicit plus
remainder) must not exceed 6.  Required when \code{by_group = TRUE}.}

\item{line_type_groups}{Character vector.  One line-type string per group
(in order, including the automatic remainder group).  Must have length
equal to the total number of groups.  Defaults to \code{"solid"} for the
first group and \code{"dashed"} for all remaining groups.}

\item{line_size_groups}{Numeric vector.  One line-width value per group
(in order, including the automatic remainder group).  Must have length
equal to the total number of groups.  Defaults to \code{2} for the first
group and \code{1} for all remaining groups.}

\item{transformation}{Object of class \code{"transform"} or \code{"trans"}
as returned by \code{\link[scales]{trans_new}}, or \code{NULL} (identity,
no transformation).  Applied to the y-axis via
\code{\link[ggplot2]{scale_y_continuous}}.  Default is \code{NULL}.}

\item{line_size}{Numeric.  Line width used when \code{by_group = FALSE}.
Default is \code{1.5}.}

\item{legend}{Logical.  If \code{TRUE} (default), the site colour legend is
displayed.}

\item{legend_text_size}{Numeric.  Font size of legend text in points.
Default is \code{12}.}

\item{x_angle}{Numeric.  Rotation angle of x-axis tick labels in degrees.
Default is \code{45}.}

\item{grayscale}{Logical.  If \code{TRUE}, overrides \code{site_colors} and
renders all trajectories in greyscale.  Default is \code{FALSE}.}

\item{plot_title}{Character.  Plot title string.  Default is
\code{"Shannon Entropy Trajectories"}.}
}
\value{
A named list with five elements:
\item{Data_Frame}{Long-format data frame with columns \code{sites}
(factor), \code{entropies} (numeric), \code{class} (factor),
\code{max_class} (integer), \code{period} (integer), and
\code{coverage} (character, partition label).  Suitable for direct
input to \code{\link{plot_site_class_trajectory}}.}
\item{Plot}{A \code{ggplot} object.  Augment with additional layers
(e.g. \code{\link[ggplot2]{geom_vline}} for VOC emergence events) before
printing or saving with \code{\link[ggplot2]{ggsave}}.}
\item{Colors}{Named character vector mapping each plotted site index
(character) to its assigned colour string.  Pass as \code{site_colors}
to subsequent calls to \code{plot_entropy_trajectories} for a consistent
colour scheme across figures.}
\item{XBreaks}{Integer vector of partition period indices.  Pass as
\code{xbreaks} to \code{\link{plot_site_class_trajectory}}.}
\item{XLabels}{Character vector of partition labels aligned with
\code{XBreaks}.  Pass as \code{xlabels} to
\code{\link{plot_site_class_trajectory}}.}
}
\description{
Plots per-site Shannon entropy as continuous trajectories across
time partitions for a selected set of sequence sites, using the output of
\code{\link{partition_time_windows}}.
}
\details{
For each partition the function extracts the GMM clustering result from
\code{part_data$Clusters} and assembles a long-format data frame spanning
all selected sites across all partitions.  Sites absent from a given
partition (removed by zero-entropy or singleton filtering, or because the
partition window was empty) are silently omitted from that partition's
trajectory and do not interrupt adjacent observations.

\strong{Class relabeling.}  This function does not perform any relabeling of
GMM class labels.  If class 1 must denote the highest-entropy group
throughout the returned \code{$Data_Frame} (e.g. before passing it to
\code{\link{plot_site_class_trajectory}}), the user should call
\code{\link{relabel_entropy_classes}} on each partition's
\code{Clusters[[i]]$DataFrame} and update \code{Max_Entropy[i]} to
\code{1L} prior to calling this function.

\strong{Colour scheme.}  Site colours are specified through
\code{site_colors}, a named character vector whose names are site indices
(as character strings) and whose values are valid R colour strings.  Any
site not listed in \code{site_colors} receives an automatically assigned
colour from the HCL \code{"Dark 2"} qualitative palette.  The final colour
mapping is returned as \code{$Colors} so the same scheme can be passed to
subsequent calls for cross-plot consistency.

\strong{Group-stratified trajectories (\code{by_group = TRUE}).}  When
biological groupings must be distinguished visually (e.g. defining SNP
sites vs. other mutation sites), \code{groups_list} partitions
\code{sites} into explicitly named groups.  Any site not assigned to an
explicit group is automatically collected into a remainder group appended
as the final element of \code{groups_list}.  Line type and line width are
mapped to group membership via \code{line_type_groups} and
\code{line_size_groups}, both of which must have length equal to the
total number of groups (explicit plus the automatic remainder).  At most
six groups are supported.

\strong{\code{max_class} column.}  The returned \code{$Data_Frame} carries
a \code{max_class} column recording the label of the highest-entropy GMM
component for each partition, taken directly from
\code{part_data$Max_Entropy[i]}.  This column is consumed by
\code{\link{plot_site_class_trajectory}} (red labels) and by downstream
class-assignment tables.
}
\examples{
# Three-period synthetic dataset with distinct trajectory shapes:
# Site 1: up-then-down (peak in P2).
# Site 2: monotone up.
# Per-partition Shannon entropy (bits):
#   P1 (Jan)  s1: 0.469  s2: 0.469
#   P2 (Feb)  s1: 1.522  s2: 0.881
#   P3 (Mar)  s1: 0.722  s2: 1.522
df <- data.frame(
  s1 = c(
    c(1L, 1L, 1L, 1L, 1L, 1L, 1L, 1L, 1L, 2L),         # P1: 9:1
    c(1L, 1L, 1L, 1L, 2L, 2L, 2L, 2L, 3L, 3L),         # P2: 4:4:2
    c(1L, 1L, 1L, 1L, 1L, 1L, 1L, 1L, 2L, 2L)          # P3: 8:2
  ),
  s2 = c(
    c(1L, 1L, 1L, 1L, 1L, 1L, 1L, 1L, 1L, 2L),         # P1: 9:1
    c(1L, 1L, 1L, 1L, 1L, 1L, 1L, 2L, 2L, 2L),         # P2: 7:3
    c(1L, 1L, 1L, 1L, 2L, 2L, 2L, 2L, 3L, 3L)          # P3: 4:4:2
  ),
  Date = rep(
    seq(as.Date("2020-01-01"), by = "month", length.out = 3L),
    each = 10L
  )
)

part_data <- partition_time_windows(
  data          = df,
  n_sites       = 2L,
  window_length = 1L,
  window_type   = 3L,
  start_date    = "2020-01-01",
  end_date      = "2020-04-01",
  removez       = FALSE,
  removesngl    = FALSE
)

result <- plot_entropy_trajectories(part_data = part_data)
print(result$Plot)
}
\seealso{
\code{\link{partition_time_windows}},
\code{\link{relabel_entropy_classes}},
\code{\link{plot_site_class_trajectory}}
}
