% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/estim.R
\name{svp}
\alias{svp}
\title{Estimate a Stochastic Volatility Model}
\usage{
svp(
  y,
  p = 1,
  J = 10,
  leverage = FALSE,
  errorType = "Gaussian",
  rho_type = "pearson",
  del = 1e-10,
  trunc_lev = TRUE,
  wDecay = FALSE,
  logNu = FALSE,
  sigvMethod = "factored",
  winsorize_eps = 0
)
}
\arguments{
\item{y}{Numeric vector. Observed returns (e.g., de-meaned log returns).}

\item{p}{Integer. Order of the volatility process. Default is 1.}

\item{J}{Integer. Winsorizing parameter controlling the number of
autocovariance blocks used. Default is 10.}

\item{leverage}{Logical. If \code{TRUE}, estimate leverage parameter
\eqn{\rho}. Default is \code{FALSE}.}

\item{errorType}{Character. Error distribution: \code{"Gaussian"} (default),
\code{"Student-t"}, or \code{"GED"}.}

\item{rho_type}{Character. Correlation type for leverage estimation. One of
\code{"pearson"} (default), \code{"kendall"}, or \code{"both"}.}

\item{del}{Numeric. Small constant for log transformation:
\eqn{\log(y_t^2 + \delta)}. Default is \code{1e-10}.}

\item{trunc_lev}{Logical. If \code{TRUE}, truncate the estimated leverage
parameter to \code{[-0.999, 0.999]}. Default is \code{TRUE}. Setting to
\code{FALSE} can reduce bias in some cases but may yield estimates
outside the parameter space.}

\item{wDecay}{Logical. Use linearly decaying weights in the WLS estimation.
Default is \code{FALSE}.}

\item{logNu}{Logical. Solve for \eqn{\nu} in log-space for numerical
stability (Student-t only). Default is \code{FALSE}.}

\item{sigvMethod}{Character. Method for estimating \eqn{\sigma_v}. One of:
\code{"factored"} (default) — factored-variance estimator (recommended;
dominates RMSE in most settings, see ADRR 2025);
\code{"direct"} — direct variance decomposition;
\code{"hybrid"} — AD2021 closed-form for \eqn{p = 1}, falls back to
\code{"direct"} for \eqn{p \ge 2} (Student-t and GED only).}

\item{winsorize_eps}{Integer. Number of extreme autocovariance lags to
winsorize (\code{0} = none). Used in Student-t and GED
\eqn{\sigma_\varepsilon^2} estimation. Default \code{0}.}
}
\value{
Depending on \code{errorType}:
\itemize{
  \item \code{"Gaussian"}: An object of class \code{"svp"} (see below).
  \item \code{"Student-t"}: An object of class \code{"svp_t"}.
  \item \code{"GED"}: An object of class \code{"svp_ged"}.
}

The \code{"svp"} class contains:
\describe{
  \item{mu}{Mean of \eqn{\log(y_t^2 + \delta)}.}
  \item{phi}{Numeric vector of AR coefficients.}
  \item{sigv}{Standard deviation of volatility innovations.}
  \item{sigy}{Unconditional standard deviation.}
  \item{rho}{Leverage parameter (if estimated, otherwise \code{NA}).}
  \item{y}{The original data.}
  \item{p, J}{Model order and winsorizing parameter.}
  \item{errorType}{The error distribution used.}
  \item{call}{The matched call.}
}
}
\description{
Master estimation function for SV(p) models using the Winsorized ARMA-SV
(W-ARMA-SV) method. Supports Gaussian, Student-t, and GED error
distributions, with optional leverage effects.
}
\details{
The model is:
\deqn{y_t = \sigma_y \exp(w_t / 2) z_t}
\deqn{w_t = \phi_1 w_{t-1} + \cdots + \phi_p w_{t-p} + \sigma_v v_t}

where \eqn{z_t} follows a distribution specified by \code{errorType}
(Gaussian, Student-t, or GED), and \eqn{v_t} is i.i.d. standard normal.
When \code{leverage = TRUE}, the correlation between \eqn{z_t} and
\eqn{v_t} is estimated as \eqn{\rho}.

For Student-t errors with leverage, the correction factor
\eqn{C_t(\nu)} from the scale-mixture representation is applied.
For GED errors with leverage, the exact implicit equation is solved
via 1D root-finding with Gauss-Hermite quadrature.
}
\examples{
\donttest{
# Gaussian SV(1) without leverage (default)
y <- sim_svp(1000, phi = 0.95, sigy = 1, sigv = 0.2)$y
fit <- svp(y)
summary(fit)

# With leverage
y2 <- sim_svp(1000, phi = 0.95, sigy = 1, sigv = 0.2, leverage = TRUE, rho = -0.3)$y
fit2 <- svp(y2, leverage = TRUE)
coef(fit2)

# Student-t errors
y3 <- sim_svp(1000, phi = 0.9, sigy = 1, sigv = 0.2, errorType = "Student-t", nu = 5)$y
fit3 <- svp(y3, errorType = "Student-t")
summary(fit3)
}

}
\references{
Ahsan, N. and Dufour, J.-M. (2021). Simple estimators and inference for
higher-order stochastic volatility models. \emph{Journal of Econometrics},
224(1), 181-197.

Ahsan, N., Dufour, J.-M., and Rodriguez Rondon, G. (2025). Estimation and
inference for stochastic volatility models with heavy-tailed distributions.
}
\seealso{
\code{\link{svpSE}} for standard errors.
}
