% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/validate.R
\name{validate_calibration}
\alias{validate_calibration}
\title{Validate a model via a procedure based on simulated data.}
\usage{
validate_calibration(spec, N, T = 1000, x = NULL, seed = 9000,
  nCores = NULL, ...)
}
\arguments{
\item{spec}{A \code{\link{Specification}} object.}

\item{N}{An integer with the number of repetitions of the validation protocol.}

\item{T}{An optional integer with the length of the time series to be simulated. It defaults to 1000 observations.}

\item{x}{An optional numeric matrix with covariates for Markov-switching regression. It defaults to NULL (no covariates).}

\item{seed}{An optional integer with the seed used for the simulations. It defaults to 9000.}

\item{nCores}{An optional integer with the number of cores to use to run the protocol in parallel. It defaults to half the number of available cores}

\item{...}{Arguments to be passed to \code{\link{draw_samples}}.}
}
\value{
A named list with two elements. The first element \emph{chains} is a data.frame with Markov-chain Monte Carlo convergence diagnostics (number of divergences, number of times max tree depth is reached, maximum leapfrogs, warm up and sampling times) and posterior predictive checks (observation ranks, Kolmogorov-Smirnov statistic for observed sample vs posterior predictive samples). The second element, \emph{parameters}, compare true versus estimated values for the unknown quantities (mean, sd, quantiles and other posterior measures, Monte Carlo standard error, estimated sample size, R Hat, and rank).
}
\description{
Validation protocol inspired on Simulation Based Calibration (cite). Also known as fake data.
}
\details{
\enumerate{
  \item Compile the prior predictive model (i.e. no likelihood statement in the Stan code).
  \item Draw \eqn{N} samples of the parameter vector \eqn{\theta} and the observation vector \eqn{\strong{y}_t} from prior predictive density.
  \item Compile the posterior predictive model (i.e. Stan code includes both prior density and likelihood statement).
  \item For all \eqn{n \in 1, \dots, N}:
  \enumerate{
    \item Feed \eqn{\strong{y}_t^{(n)}} to the full model.
    \item Draw one posterior sample of the observation variable \eqn{\strong{y_t}^{(n)}_{new}}.
    \item Collect Hamiltonian Monte Carlo diagnostics: number of divergences, number of times max tree depth is reached, maximum leapfrogs, warm up and sample times.
    \item Collect posterior sampling diagnostics: posterior summary measures (mean, sd, quantiles), comparison against the true value (rank), MCMC convergence measures (Monte Carlo SE, ESS, R Hat).
    \item Collect posterior predictive diagnostics: observation ranks, Kolmogorov-Smirnov statistic for observed sample vs posterior predictive samples.
  }
}
}
\examples{
\dontrun{
mySpec   <- hmm(
  K = 2, R = 1,
  observation = Gaussian(
    mu    = Gaussian(0, 10),
    sigma = Student(
      mu = 0, sigma = 10, nu = 1, bounds = list(0, NULL)
    )
  ),
  initial     = Dirichlet(alpha = c(1, 1)),
  transition  = Dirichlet(alpha = c(1, 1)),
  name = "Univariate Gaussian Hidden Markov Model"
)

myVal <- validate_calibration(
  myFit, N = 50, T = 300, seed = 90, nCores = 10, iter = 500
)
}
}
