% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/run_kronx.R
\name{run_kronx}
\alias{run_kronx}
\title{Run the full Clock of Regimes (KRONX) analysis.}
\usage{
run_kronx(
  file = NULL,
  x = NULL,
  close_col = "close",
  K = 3L,
  n_starts = 5L,
  max_iter = 200L,
  tol = 1e-06,
  seed = 123L,
  epsilon_min = 0.01,
  c_hazard = 0.05,
  tail_alpha = 0.01,
  ruin_horizon = 250L,
  nu_grid = c(3:30, 40, 60, 100),
  verbose = TRUE,
  output_dir = "kronx_output"
)
}
\arguments{
\item{file}{Path to a CSV file containing a close-price column. Ignored if
\code{x} is supplied. Default: \code{NULL}.}

\item{x}{Optional numeric vector of returns. If supplied, \code{file} is
ignored and no CSV is read. This is intended in particular for small,
self-contained examples and tests. Default: \code{NULL}.}

\item{close_col}{Name of the close-price column. The function first tries
the exact name, then a case-insensitive match, and finally falls back to
any column whose name contains \code{"close"}. Default:
\code{"close"}.}

\item{K}{Number of hidden states. Default: \code{3L}.}

\item{n_starts}{Number of EM random restarts. Default: \code{5L}.}

\item{max_iter}{Maximum EM iterations per restart. Default: \code{200L}.}

\item{tol}{Log-likelihood convergence tolerance. Default: \code{1e-6}.}

\item{seed}{Random seed for reproducibility. Default: \code{123L}.}

\item{epsilon_min}{Minimum baseline Talebian hazard. Default: \code{0.01}.}

\item{c_hazard}{Hazard sensitivity to tail thickness. Default:
\code{0.05}.}

\item{tail_alpha}{Left-tail probability used for the empirical loss
threshold. Default: \code{0.01}.}

\item{ruin_horizon}{Horizon, in observations, used in the risk bound.
Default: \code{250L}.}

\item{nu_grid}{Candidate degrees-of-freedom values for Student-t fitting.
Default: \code{c(3:30, 40, 60, 100)}.}

\item{verbose}{Logical; if \code{TRUE}, print progress and a summary.
Default: \code{TRUE}.}

\item{output_dir}{Directory for output files. Created if it does not exist.
Pass \code{NULL} to suppress file output. Default:
\code{"kronx_output"}.}
}
\value{
A named list containing:
\describe{
  \item{close_px}{Numeric vector of raw close prices, or \code{NULL} when
    \code{x} is supplied directly.}
  \item{ret}{Numeric vector of log returns or supplied returns.}
  \item{K}{Number of hidden states.}
  \item{gauss_fit}{Fitted Gaussian HMM object.}
  \item{t_fit}{Fitted Student-t HMM object.}
  \item{A_gauss}{Gaussian transition matrix.}
  \item{A_t}{Student-t transition matrix.}
  \item{epsilon}{Per-state Talebian hazard vector.}
  \item{Q}{Hazard-adjusted operator.}
  \item{K_mat}{KRONX generator matrix.}
  \item{N_mat}{Fundamental matrix.}
  \item{pi_qs}{Quasi-stationary distribution.}
  \item{pi_res}{Residence-weight vector.}
  \item{loss_threshold}{Empirical left-tail return threshold.}
  \item{q_state}{Per-state tail probability.}
  \item{bar_q}{Residence-weighted tail probability.}
  \item{bar_lambda}{Residence-weighted hazard.}
  \item{ruin_bound}{Upper bound over \code{ruin_horizon}.}
  \item{tail_alpha}{The \code{tail_alpha} value used.}
  \item{ruin_horizon}{The \code{ruin_horizon} value used.}
  \item{state_summary}{A \code{data.frame} summarising per-state
    quantities.}
  \item{vpath_t}{Integer vector of Viterbi-decoded Student-t state labels.}
  \item{output_files}{Character vector of paths to written output files, or
    \code{NULL} if \code{output_dir} is \code{NULL}.}
  \item{input_source}{A short label describing the data source used.}
}
}
\description{
Runs the KRONX pipeline on either a CSV file of prices or a numeric vector
of returns supplied directly. When \code{file} is used, the function reads
the CSV file, extracts the close-price column (case-insensitive match on
\code{"close"} or \code{"Close"}), and computes log returns. When
\code{x} is supplied, it is treated as a numeric return series and the
file-ingestion step is skipped.
}
\details{
The function then fits Gaussian and Student-t Hidden Markov Models (HMMs),
builds the KRONX operator chain Q \eqn{\rightarrow} K \eqn{\rightarrow} N,
and computes a residence-weighted upper bound on extreme downside risk.
Results are returned as a named list and, optionally, written to
\code{output_dir}.
}
\examples{
# Small self-contained example suitable for automatic checking
set.seed(123)
x <- rnorm(120, mean = 0, sd = 0.01)
res <- run_kronx(
  x = x,
  K = 2L,
  n_starts = 1L,
  max_iter = 10L,
  tol = 1e-4,
  tail_alpha = 0.05,
  ruin_horizon = 25L,
  verbose = FALSE,
  output_dir = NULL
)
res$ruin_bound
dim(res$A_t)
# Self-contained file-based example
tmp <- tempfile(fileext = ".csv")
dat <- data.frame(
  date = sprintf("2026-01-\%02d", 1:20),
  close = c(
    100.0, 100.2, 100.1, 100.5, 100.4,
    100.8, 101.0, 100.9, 101.3, 101.1,
    101.6, 101.5, 101.9, 102.0, 101.8,
    102.2, 102.4, 102.3, 102.7, 102.9
  )
)
utils::write.csv(dat, tmp, row.names = FALSE)
res_file <- run_kronx(
  file = tmp,
  close_col = "close",
  K = 2L,
  n_starts = 1L,
  max_iter = 8L,
  tol = 1e-4,
  tail_alpha = 0.10,
  ruin_horizon = 10L,
  verbose = FALSE,
  output_dir = NULL
)
res_file$ruin_bound
}
