% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ctOptimUncertainty.R
\name{ctOptimUncertainty}
\alias{ctOptimUncertainty}
\title{Update optimized ctsem uncertainty estimates}
\usage{
ctOptimUncertainty(
  fit,
  uncertainty = c("hessian", "surrogate", "is", "bootstrap", "fullbootstrap", "sandwich",
    "opg"),
  draws = c("auto", "normal", "empirical", "imis"),
  finishsamples = NULL,
  cores = NULL,
  control = list(),
  verbose = 0,
  ...
)
}
\arguments{
\item{fit}{Optimized \code{ctStanFit} object.}

\item{uncertainty}{Uncertainty approximation. \code{'hessian'} uses the
finite-difference Hessian, \code{'surrogate'} fits a local quadratic
surrogate around the optimum, \code{'is'} uses Hessian-based importance
sampling and computes uncertainty from the weighted importance-sampling
distribution, \code{'bootstrap'} uses one-step score bootstrap draws with
Hessian bread, \code{'fullbootstrap'} resamples subjects and fully
re-optimizes each sample from the original maximum likelihood or MAP
estimate using mize L-BFGS, \code{'sandwich'} uses Hessian bread with score
covariance meat, and \code{'opg'} uses an OPG-style score information
approximation.}

\item{draws}{Approximate raw-parameter draw method. \code{'auto'} uses
empirical draws for \code{uncertainty='bootstrap'} and
\code{uncertainty='fullbootstrap'} and normal draws otherwise.
\code{'normal'} draws from a multivariate normal using the selected
covariance, \code{'empirical'} uses empirical draws when available, and
\code{'imis'} runs the importance sampler using the selected covariance as
proposal. For \code{uncertainty='is'}, \code{draws} is set to \code{'imis'}.}

\item{finishsamples}{Number of approximate raw-parameter samples. If
\code{NULL}, the existing number of rows in \code{fit$stanfit$rawposterior}
is reused when available; otherwise 1000 samples are used.}

\item{cores}{Number of cores. If \code{NULL}, one core is used. Hessian,
surrogate, and IMIS calculations use these cores by splitting each
log-probability/gradient evaluation across subjects. Score-based methods use
these cores for score contribution calculations. Transformed-quantity
calculations also use these cores.}

\item{control}{List of method-specific options. Useful entries include
\code{ridge}, \code{hessianStep}, \code{surrogateNpoints},
\code{surrogateScale}, \code{surrogateProfile},
\code{surrogateProfileTargetDrop}, \code{surrogateProfileMaxStep},
\code{bootstrapFitCores}, \code{bootstrapTol}, \code{imisMaxIter},
\code{imisScaleInit}, \code{imisTailScale}, \code{isESS}, and
\code{isitersize}. Omitted entries use
\code{ridge = 1e-8}, \code{hessianStep = 1e-3},
\code{surrogateScale = .5}, \code{surrogateNpoints = NULL},
\code{surrogateProfile = TRUE},
\code{surrogateProfileTargetDrop = NULL},
\code{surrogateProfileMaxStep = 64},
\code{bootstrapFitCores = 1}, \code{bootstrapTol = 1e-5},
\code{imisMaxIter = 50}, \code{imisScaleInit = 1.1},
\code{imisTailScale = 1.1}, \code{isESS = 100}, and
\code{isitersize = 1000}. When
\code{surrogateNpoints} is \code{NULL}, the
surrogate uses at least \code{max(4 * npars, 50)} local directions. The
surrogate is fit in whitened coordinates relative to the proposal covariance.
Each direction is radially adjusted with a small evaluation budget so that
the retained points are close to an informative local log-probability drop,
rather than relying on a random cloud to land in the desired range. With
\code{surrogateProfile = TRUE}, all fitted surrogate curvature directions
are then profiled until they reach \code{surrogateProfileTargetDrop}, or the
surrogate target drop when \code{NULL}. The profile search uses the fitted
surrogate curvature to choose direction-specific starting distances, so very
flat directions can be checked beyond \code{surrogateProfileMaxStep} when
the surrogate itself predicts that a larger distance is needed. If the
observed profile is still flatter than the fitted surrogate predicted, a
small magnitude-adjusted expansion budget is used before reporting a missed
target. \code{parsteps} may be supplied internally to keep stepwise-fixed
raw parameters fixed while estimating uncertainty for the remaining
parameters.
Hessian-based covariance construction first attempts the unmodified
\code{solve(-hessian)} covariance and a Cholesky check. It warns when
numerical repair is needed, such as positive-definite projection, ridge
flooring of information eigenvalues, or fallback to \code{MASS::ginv};
diagnostics are stored in
\code{fit$stanfit$uncertainty$details$covariance}.
Score-based methods use subject-level score contributions when there are
at least two subjects; single-subject models warn and use case-level
contributions. Score-based methods warn when there are fewer than ten
independent subjects or no more score rows than raw parameters. Full
bootstrap requires at least two subjects and warns below ten independent
subjects. Bootstrap-style methods require at least two returned samples /
refits.}

\item{verbose}{Integer controlling progress detail.}

\item{...}{Unused.}
}
\value{
Updated \code{ctStanFit} object.
}
\description{
Recomputes the approximate raw-parameter uncertainty for an optimized
\code{\link{ctFit}} object and refreshes the approximate raw-parameter
samples.
}
