% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/simulations.R
\name{simCalibrationSim}
\alias{simCalibrationSim}
\title{Asymptotic Calibration Check for RESI Variance Estimates}
\usage{
simCalibrationSim(
  nsim = 500L,
  n.vec = c(100L, 200L, 500L, 1000L, 2000L, 5000L),
  alpha = 0.05,
  output.dir = "resiCalibrationSim",
  fixed.knots = FALSE,
  deriv_method = c("corrected", "original", "population", "population2", "zeroB",
    "zero_phi_cross", "extended"),
  mc.cores.reps = 1L
)
}
\arguments{
\item{nsim}{Integer, replicates per (setting, \eqn{n}) cell. Default 500.}

\item{n.vec}{Integer vector of sample sizes.
Default \code{c(100, 200, 500, 1000, 2000, 5000)}.}

\item{alpha}{Numeric, nominal CI level. Default 0.05.}

\item{output.dir}{Character, directory for raw per-cell RDS files.
Default \code{"resiCalibrationSim"}.}

\item{fixed.knots}{Logical. Fix spline knots at full-dataset quantiles.
Default \code{FALSE}.}

\item{deriv_method}{Character, type of derivative being evaluated. Package now only includes "extended" in resi implementation.}

\item{mc.cores.reps}{Integer, cores for within-cell parallelism. Default 1.}
}
\value{
Invisibly returns the combined metrics \code{data.frame}.
}
\description{
Runs a plasmode simulation to verify that the asymptotic normal CI machinery
is correctly calibrated for all four model settings (lm/glm x
parametric/robust).  For each (setting, sample size) cell the function
checks:
\enumerate{
  \item \strong{Bias(theta)}: \eqn{\hat\theta \to \theta_{\rm true}} --
    raw coefficients (and \eqn{\phi = \hat\sigma^2} for \code{lm}) converge
    to the full-dataset values.
  \item \strong{vcov check A} (estimator consistency):
    \eqn{n \cdot \bar V_{\rm analytic} / (n_{\rm full} \cdot V_{\rm true}) \to 1}.
  \item \strong{vcov check B} (calibration):
    \eqn{n \cdot \widehat{\rm Var}(\hat\beta) / (n_{\rm full} \cdot V_{\rm true}) \to 1}.
  \item \strong{Bias(R)}: RESI point estimates converge to the full-dataset
    values.
  \item \strong{sigma2S check A} (estimator consistency):
    \eqn{\bar{\hat\sigma}^2_S / \sigma^2_{S,\rm true} \to 1}.
  \item \strong{sigma2S check B} (CI calibration):
    \eqn{n \cdot \widehat{\rm Var}(\hat R) / \sigma^2_{S,\rm true} \to 1}.
}
True values are taken from the full \code{\link{insurance}} dataset using the
same definitions as \code{\link{insurancePlasmodeSim}}.  \eqn{\sigma^2_S} is
extracted from the asymptotic-normal CI half-width:
\eqn{\hat\sigma^2_S = n \cdot ({\rm hw}/z_{\alpha/2})^2}.
}
\seealso{
\code{\link{insurancePlasmodeSim}}, \code{\link{simCompareMethodsFigures}}
}
