% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/simstudy.R
\name{htdv_simstudy}
\alias{htdv_simstudy}
\title{Factorial Monte Carlo Simulation Study for Dependent-Unbalanced Data}
\usage{
htdv_simstudy(
  n_grid = c(40L, 80L, 200L, 500L),
  phi_grid = c(0, 0.3, 0.6, 0.85),
  tail_grid = c("normal", "t5", "t3", "t2_1"),
  imb_grid = c(1, 1.5, 3, 6),
  delta_grid = c(0, 0.1, 0.25, 0.5),
  R = 500L,
  seed = 20260422L,
  n_cores = 1L,
  layers = c("har", "boot", "bayes"),
  bayes_chains = 2L,
  bayes_iter = 600L,
  bayes_warmup = 300L,
  boot_R = 999L,
  rope = c(-0.1, 0.1),
  alpha = 0.05,
  out_dir = NULL,
  progress = TRUE
)
}
\arguments{
\item{n_grid}{Integer vector of primary sample sizes \eqn{n_1}.}

\item{phi_grid}{Numeric vector of AR(1) coefficients in \eqn{(-1,1)}.}

\item{tail_grid}{Character vector; any subset of \code{"normal"},
\code{"t5"}, \code{"t3"}, \code{"t2_1"}.}

\item{imb_grid}{Numeric vector of imbalance ratios \eqn{n_1/n_2}.}

\item{delta_grid}{Numeric vector of location shifts in units of
\eqn{\sigma_\infty}.}

\item{R}{Integer number of Monte Carlo replications per cell.}

\item{seed}{Integer master seed.}

\item{n_cores}{Integer number of workers for cell-level parallelism.
On non-Unix platforms parallelism falls back to serial.}

\item{layers}{Character vector; any subset of \code{c("har","boot","bayes")}.}

\item{bayes_chains}{Number of HMC chains per Bayesian fit.}

\item{bayes_iter}{Total HMC iterations (warmup + sampling).}

\item{bayes_warmup}{HMC warmup iterations.}

\item{boot_R}{Bootstrap replicates per call.}

\item{rope}{Length-2 numeric vector; ROPE for the Bayesian decision on
the raw (non-standardized) delta.}

\item{alpha}{Significance level (nominal size of tests; \eqn{1-\alpha} is
the coverage target for intervals).}

\item{out_dir}{Optional directory for per-cell incremental RDS results.
Each cell is written to its own \code{cell_<id>.rds} so that concurrent
workers cannot collide on a shared file. Final aggregation reads the
directory back, so successful cells are preserved even if some workers
later die. If \code{NULL}, no per-cell artifacts are written and the
only result is the in-memory return value.}

\item{progress}{Logical; print a one-line status per completed cell.}
}
\value{
A data frame with one row per (cell, replication, layer). Columns:
\code{cell_id, n, phi, tail, imb, n1, n2, delta, sigma_inf, layer,
replicate, reject, ci_lo, ci_hi, estimate, covered, ci_length,
rhat_max, ess_min, divergences, diag_pass, runtime_sec}.
}
\description{
Runs the pre-registered factorial Monte Carlo study of Section 12-bis of
the companion paper. The study crosses four factors (per-group sample
size, AR(1) coefficient, innovation tail, imbalance ratio) and evaluates
three inferential layers (HAR-Wald, stationary block bootstrap,
hierarchical Bayesian HMC) on each replication.
}
\section{Data-generating process}{

Two independent AR(1) series \eqn{x^{(1)}_t} of length \eqn{n_1=n} and
\eqn{x^{(2)}_t} of length \eqn{n_2 = \max(2, \mathrm{round}(n / \mathrm{imb}))}
are generated. The innovations are drawn from \code{rnorm},
scaled Student-\eqn{t_{(5)}}, scaled Student-\eqn{t_{(3)}} or scaled
Student-\eqn{t_{(2.1)}} so that the nominal innovation variance is one
when the law has a finite second moment. Group one has mean zero; group
two has mean \eqn{\Delta\cdot\sigma_\infty} where
\eqn{\sigma_\infty = 1/\sqrt{1 - \phi^2}}.
}

\section{Inferential layers}{

\itemize{
  \item \strong{HAR-Wald (\code{"har"}).} Welch-style two-sample statistic
    \eqn{z = (\bar x_1 - \bar x_2) / \sqrt{\hat\sigma_1^2/n_1 + \hat\sigma_2^2/n_2}}
    with long-run variances estimated via \code{\link{htdv_lrv}} (QS
    kernel, Andrews bandwidth) on each group's demeaned series.
    Rejection at asymptotic \eqn{\chi^2_1} critical value.
  \item \strong{Stationary block bootstrap (\code{"boot"}).} Each group
    resampled independently using
    \code{\link{htdv_boot}} with \code{block_length = "auto"} (Patton-
    Politis-White). Percentile interval on
    \eqn{\bar x_1^* - \bar x_2^*}.
  \item \strong{Hierarchical Bayesian (\code{"bayes"}).} Two-sample AR(1)
    Stan model (\code{simstudy_two_sample.stan}); posterior interval on
    \eqn{\delta = \alpha_2 - \alpha_1}. A run is flagged
    \code{diag_pass = TRUE} only if \eqn{\hat R < 1.01}, bulk and tail
    ESS above \eqn{200}, and zero divergences.
}
}

\examples{
\donttest{
res <- htdv_simstudy(n_grid = c(40, 80),
                     phi_grid = c(0, 0.6),
                     tail_grid = c("normal"),
                     imb_grid = c(1, 3),
                     delta_grid = c(0, 0.25),
                     R = 5L, n_cores = 1L,
                     layers = c("har", "boot"))
head(htdv_simstudy_summary(res))
}

}
\references{
Kiefer, N.M., & Vogelsang, T.J. (2005). Econometric Theory 21(6):
1130-1164.
Patton, A., Politis, D.N., & White, H. (2009). Econometric Reviews
28(4): 372-375.
Kruschke, J.K. (2018). Advances in Methods and Practices in
Psychological Science 1(2): 270-280.
}
