% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cluster_boot.R
\name{cluster_boot}
\alias{cluster_boot}
\title{Generic Cluster Bootstrap Engine}
\usage{
cluster_boot(
  data,
  cluster,
  B,
  fn,
  ...,
  strata = NULL,
  seed = NULL,
  verbose = FALSE
)
}
\arguments{
\item{data}{A data frame containing the cluster ID column named by
\code{cluster}. All other columns are passed through unchanged to
\code{fn}.}

\item{cluster}{Character. Name of the cluster ID column.}

\item{B}{Integer. Number of bootstrap replications.}

\item{fn}{Function. Called as \code{fn(boot_data, ...)} once per
bootstrap replicate. Must return a numeric vector of fixed length
(the length must be the same across replicates -- typically achieved
by evaluating the statistic on a fixed grid of times).}

\item{...}{Additional arguments passed to \code{fn}.}

\item{strata}{Optional named vector mapping each unique cluster ID
(as character) to a stratum label. When supplied, resampling is
stratified: in each replicate, the original number of clusters in
each stratum is drawn with replacement from the clusters in that
stratum (so per-stratum cluster counts are preserved across
replicates). When \code{NULL} (default), unstratified resampling
is used.}

\item{seed}{Optional integer. If non-NULL, \code{set.seed(seed)} is
called before bootstrapping for reproducibility.}

\item{verbose}{Logical. If \code{TRUE}, prints a progress message
every 100 replicates. Default \code{FALSE}.}
}
\value{
A numeric matrix with \code{length(fn(data, ...))} rows and
  \code{B} columns. Column \code{b} is the result of \code{fn} applied
  to bootstrap replicate \code{b}.
}
\description{
Performs the nonparametric cluster bootstrap: resamples whole clusters
with replacement and applies a user-supplied statistic function to
each bootstrap replicate.
}
\details{
The bootstrap is nonparametric and at the cluster level: in each
replicate, n clusters are sampled with replacement (where n is the
number of unique values of \code{data[[cluster]]}), and the resulting
cluster-bound rows are stacked into a new data frame.

Resampled clusters are re-IDed (1, 2, ..., n) so that downstream
code treating cluster IDs as distinct labels (e.g., \code{tapply}
aggregations) works correctly even when the same original cluster
appears multiple times in a replicate.

Stratified resampling (\code{strata}) supports cluster-randomized
designs in which each cluster belongs to a single group (case ii of
Bakoyannis & Bandyopadhyay 2022): the per-stratum cluster counts
are fixed across replicates, so a replicate can never wipe out one
of the groups.

The bootstrap is statistic-agnostic: the same engine is used for
point-estimator standard errors, two-sample tests, and confidence
bands. Whatever \code{fn} returns is what gets bootstrapped.
}
\examples{
data(example_msm)

# Cluster-bootstrap a simple summary: the mean of Tstop across
# rows. The user-supplied fn can return any fixed-length numeric
# vector; the typical use case is a transition probability curve
# evaluated on a fixed time grid (which is exactly what patp() does
# under the hood).
boot <- cluster_boot(
  data = example_msm, cluster = "cluster", B = 50,
  fn   = function(d) mean(d$Tstop),
  seed = 1
)
c(point = mean(boot, na.rm = TRUE),
  se    = stats::sd(boot, na.rm = TRUE))

}
