% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/partition_time_windows.R
\name{partition_time_windows}
\alias{partition_time_windows}
\title{Partition Data into Time Windows}
\usage{
partition_time_windows(
  data,
  n_sites,
  window_length = 1,
  window_type = 3,
  start_date = NULL,
  end_date = NULL,
  date_format = "\%b-\%Y",
  verbose = FALSE,
  ...
)
}
\arguments{
\item{data}{Data frame. Must contain a column named \code{Date}
coercible to \code{Date}. Columns \code{1} through \code{n_sites}
must be the numeric site columns; any additional columns (such as
\code{Country} or other per-sequence metadata) may follow.}

\item{n_sites}{Integer. Number of site columns. Site columns must
occupy positions \code{1} through \code{n_sites} of \code{data};
any other columns (\code{Date}, optionally \code{Country}, etc.)
must come after.}

\item{window_length}{Integer. Window duration in months.
Default is \code{1}.}

\item{window_type}{Integer (1, 2, or 3). Windowing strategy:
\code{1} = Cumulative, \code{2} = Sliding, \code{3} = Disjoint.
Default is \code{3}.}

\item{start_date}{Date or character. Window start. Defaults to earliest date
in \code{data}.}

\item{end_date}{Date or character. Window end (cutoff). Defaults to latest
date in \code{data}.}

\item{date_format}{Character. Format string for date labels. Default is
\code{"\%b-\%Y"}.}

\item{verbose}{Logical. If \code{TRUE}, prints a progress bar and completion
summary. Default is \code{FALSE}.}

\item{...}{Additional arguments passed to
\code{\link{cluster_sites_by_entropy}}.}
}
\value{
A named list:
\item{Partitions}{List of data frame chunks, one per window.}
\item{Entropies}{List of numeric entropy vectors, one per window.}
\item{Clusters}{List of clustering results from
\code{\link{cluster_sites_by_entropy}}, one per window.}
\item{Max_Entropy}{Numeric vector. Maximum cluster class label per window
(equals number of clusters found; \code{NA} if window was empty).}
\item{Dates_Labels}{Character vector of window label strings.}
\item{N_partitions}{Integer. Total number of windows.}
}
\description{
Splits a data frame of time-stamped sequences into discrete time
windows, computes per-site entropy and Mclust clustering for each window.
}
\details{
Three windowing strategies are supported via \code{window_type}.
Throughout the descriptions below, \code{T} denotes the number of whole
months between \code{start_date} and \code{end_date}, and \code{w}
denotes \code{window_length}:
\itemize{
\item \strong{1 — Cumulative}: Start is fixed; end expands by
\code{w} months each step. Each window includes all prior data
plus one more period. Produces \code{floor(T / w)} chunks.
\item \strong{2 — Sliding}: A window of \code{w} months slides one
month at a time. Produces \code{T - w + 1} chunks.
\item \strong{3 — Disjoint}: Consecutive non-overlapping windows of
\code{w} months. Produces \code{floor(T / w)} chunks. Default.
}

For example, with \code{T = 12} months and \code{w = 2}: cumulative
produces 6 chunks (each progressively larger); sliding produces 11
chunks (overlapping, each 2 months wide); disjoint produces 6 chunks
(each exactly 2 months, non-overlapping).

\strong{Empty windows.} When a window contains no observations, the
corresponding entries in the returned lists carry placeholder values:
\code{Entropies} is a zero-vector of length \code{n_sites};
\code{Clusters} is a schema-consistent empty result matching
\code{cluster_sites_by_entropy}'s empty-input return; \code{Max_Entropy}
is \code{NA_integer_}. Downstream consumers can guard on
\code{nrow(Partitions[[i]]) > 0} or \code{!is.na(Max_Entropy[i])}.

\strong{Column layout requirement.} The function extracts site columns
as \code{data[, seq_len(n_sites), drop = FALSE]}. The site columns
must therefore occupy positions \code{1} through \code{n_sites}.
\code{Date} (and any other metadata columns such as \code{Country})
must come after the site columns. A common error is to place
\code{Date} first; this will produce incorrect entropy values.
}
\examples{
dates <- seq(as.Date("2020-01-01"), as.Date("2020-06-01"), by = "month")
df <- data.frame(
  s1   = 1L,
  s2   = c(rep(1L, 15), rep(2L, 15)),
  Date = rep(dates, each = 5)
)
res <- partition_time_windows(df, n_sites = 2, window_length = 2,
                              window_type = 3, verbose = TRUE)
print(res$Dates_Labels)
print(res$Max_Entropy)

}
\seealso{
\code{\link{calculate_entropy}} for the per-site entropy
computation; \code{\link{cluster_sites_by_entropy}} for the GMM
clustering applied per window; \code{\link{relabel_entropy_classes}}
for standardizing the cluster labels in downstream consumers; and
\code{\link{calculate_hellinger_matrix}} for typical downstream use
of the \code{Partitions} output.
}
