% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/methods.R
\name{boot_dr}
\alias{boot_dr}
\title{Bootstrap the Dyad Ratios estimate}
\usage{
boot_dr(
  obj,
  data,
  R = 200L,
  level = 0.95,
  pw = FALSE,
  seed = NULL,
  parallel = FALSE
)
}
\arguments{
\item{obj}{An object of class \code{"extract"} returned by
\code{\link{extract}}.  The stored \code{call} is used to replay the
estimation identically on each bootstrap draw.}

\item{data}{The original data frame that was passed to \code{\link{extract}}
to produce \code{obj}.  The index column is perturbed for each replication;
all other columns are used as-is.}

\item{R}{Integer. Number of bootstrap replications. Default \code{200}.}

\item{level}{Numeric in (0, 1). Confidence level for the interval.
Default \code{0.95}.}

\item{pw}{Logical. Whether to calculate pairwise differences between times}

\item{seed}{Integer or \code{NULL}. Passed to \code{set.seed} before
the bootstrap loop. Default \code{NULL}.}

\item{parallel}{Logical. Parallelise the outer loop using \pkg{parallel} if
available? Useful for large \code{R}. Default \code{FALSE}.}
}
\value{
A list of class \code{"boot_dr"} with two or four components
  depending on whether the original \code{obj} used one or two dimensions:
  \describe{
    \item{\code{estimates}}{A \code{data.frame} with one row per time period
      and columns \code{period}, \code{year}, \code{month}, \code{quarter},
      \code{mood} (original point estimate), \code{lower}, and \code{upper}
      (confidence bounds at \code{(1-level)/2} and \code{1-(1-level)/2}).
      When \code{n_dim = 2}, three additional columns are appended:
      \code{mood_dim2}, \code{lower_dim2}, and \code{upper_dim2}.}
    \item{\code{samples}}{An \code{n_periods} × \code{R} matrix of raw
      bootstrap dimension-1 trajectories.}
    \item{\code{samples_dim2}}{(\code{n_dim = 2} only) An \code{n_periods}
      × \code{R} matrix of raw bootstrap dimension-2 trajectories.}
  }
  The list also carries attributes \code{R} (number of successful
  replications), \code{level}, \code{agg_interval}, and \code{n_dim}.
}
\description{
The bootstrapping algorithm was added to the package and code by Dave Armstrong. 
It is worth noting that this was not something Stimson had originally implemented
nor even something that he necessarily even endorsed.  While bootstrapping is a common
method for estimating uncertainty in complex estimators, like this one, use these
results at your own risk.
}
\details{
Generates a sampling distribution around the latent mood trajectory by
repeatedly drawing synthetic survey marginals from a binomial model and
re-running \code{\link{extract}}.  The original (unperturbed) estimate is
used as the point estimate; the bootstrap draws characterise uncertainty
around it.  

All model parameters (aggregation interval, column names, smoothing, etc.)
are taken directly from the stored call inside \code{obj}, so there is no
risk of the bootstrap replications being run with different settings than
the original.


Each replication draws \eqn{y_i \sim \text{Binomial}(n_i, p_i)} where
\eqn{p_i} is the observed proportion and \eqn{n_i} is the sample size, then
replaces the index column with \eqn{y_i / n_i} (rescaled to the same 0–100
vs 0–1 convention as the original) and re-runs \code{\link{extract}} using
the exact call stored in \code{obj}.  Replications that error (e.g. due to
a degenerate draw) are silently discarded; \code{attr(result, "R")} reports
how many succeeded.
}
\examples{
# Build a small synthetic dataset: 4 items measured annually over 20 years
set.seed(42)
n_years <- 20
years   <- seq(1980, length.out = n_years)
items   <- c("item_a", "item_b", "item_c", "item_d")

dat <- do.call(rbind, lapply(items, function(item) {
  data.frame(
    varname = item,
    date    = as.Date(paste0(years, "-07-01")),
    index   = 50 + cumsum(rnorm(n_years, 0, 1.5)) + rnorm(n_years, 0, 2),
    n       = sample(800:1200, n_years, replace = TRUE)
  )
}))

# Run the original estimate first
res <- extract(dat, n_col = "n", smoothing = FALSE)

# Bootstrap with 100 replications (use more in practice)
boot <- boot_dr(res, dat, R = 100, seed = 1)

# estimates is the summary data frame
head(boot$estimates)

# mood is the original point estimate; lower/upper are the 95\% CI
boot$estimates[, c("year", "mood", "lower", "upper")]

# samples is the raw n_periods x R matrix of bootstrap trajectories
dim(boot$samples)

# Plot the trajectory with uncertainty ribbon
plot(boot)

}
\seealso{
\code{\link{extract}}, \code{\link{plot.boot_dr}}
}
