Repository Mirror for your Cloud Server and Webhosting

Type:

Package

Title:

Clock of Regimes for Regime-Switching Fragility Analysis

Version:

0.1.0

Date:

2026-04-22

Description:

Implements the Clock of Regimes (KRONX) framework for regime-switching fragility analysis of financial time series. The package fits Gaussian and Student-t Hidden Markov Models (HMMs) to return data, constructs a hazard-adjusted transition operator Q, derives the associated generator K = Q - I, and computes the fundamental matrix N = -K inverse to characterize expected residence times under structural fragility.

License:

GPL (≥ 3)

Encoding:

UTF-8

Depends:

R (≥ 4.0.0)

Imports:

stats, utils

Suggests:

testthat (≥ 3.0.0), knitr, rmarkdown

VignetteBuilder:

utils

Config/testthat/edition:

RoxygenNote:

7.3.3

NeedsCompilation:

Packaged:

2026-04-22 21:02:59 UTC; olinaresmd

Author:

Oscar Linares [aut, cre]

Maintainer:

Oscar Linares <olinares@umich.edu>

Repository:

CRAN

Date/Publication:

2026-04-24 20:20:27 UTC

Compute log returns from a close-price vector.

Description

Compute log returns from a close-price vector.

Usage

compute_log_returns(close)

Arguments

close

Numeric vector of close prices.

Value

Numeric vector of log returns (length = length(close) - 1).

Fit a Gaussian or Student-t HMM via EM with multiple random restarts.

Description

Fit a Gaussian or Student-t HMM via EM with multiple random restarts.

Usage

fit_hmm_em(
  x,
  K = 3L,
  model = c("gaussian", "student"),
  n_starts = 5L,
  max_iter = 200L,
  tol = 1e-06,
  nu_grid = c(3:30, 40, 60, 100),
  verbose = TRUE
)

Arguments

x

Numeric vector of observations (log returns).

K

Integer number of hidden states.

model

"gaussian" or "student".

n_starts

Number of random restarts.

max_iter

Maximum EM iterations per restart.

tol

Log-likelihood convergence tolerance.

nu_grid

Candidate degrees-of-freedom for Student-t grid search.

verbose

Logical; if TRUE print iteration progress.

Value

A list with components:

model: Model type string.
A: K x K transition matrix.
delta: Length-K initial state probability vector.
params: List with mu, sigma, and (Student-t) nu.
gamma: T x K posterior state probabilities.
xi: (T-1) x K x K posterior joint transition probabilities.
logLik: Scalar log-likelihood at convergence.
n: Number of observations.
K: Number of states.

Read a close-price series from a CSV file.

Description

The function is case-insensitive: it accepts close, Close, CLOSE, or any capitalisation. The first matching column is used.

Usage

read_close_series(file, close_col = "close")

Arguments

file

Path to the CSV file.

close_col

Name of the close-price column (default "close").

Value

A numeric vector of finite close prices (length >= 10).

Run the full Clock of Regimes (KRONX) analysis.

Description

Runs the KRONX pipeline on either a CSV file of prices or a numeric vector of returns supplied directly. When file is used, the function reads the CSV file, extracts the close-price column (case-insensitive match on "close" or "Close"), and computes log returns. When x is supplied, it is treated as a numeric return series and the file-ingestion step is skipped.

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

file

Path to a CSV file containing a close-price column. Ignored if x is supplied. Default: NULL.

x

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

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 "close". Default: "close".

K

Number of hidden states. Default: 3L.

n_starts

Number of EM random restarts. Default: 5L.

max_iter

Maximum EM iterations per restart. Default: 200L.

tol

Log-likelihood convergence tolerance. Default: 1e-6.

seed

Random seed for reproducibility. Default: 123L.

epsilon_min

Minimum baseline Talebian hazard. Default: 0.01.

c_hazard

Hazard sensitivity to tail thickness. Default: 0.05.

tail_alpha

Left-tail probability used for the empirical loss threshold. Default: 0.01.

ruin_horizon

Horizon, in observations, used in the risk bound. Default: 250L.

nu_grid

Candidate degrees-of-freedom values for Student-t fitting. Default: c(3:30, 40, 60, 100).

verbose

Logical; if TRUE, print progress and a summary. Default: TRUE.

output_dir

Directory for output files. Created if it does not exist. Pass NULL to suppress file output. Default: "kronx_output".

Details

The function then fits Gaussian and Student-t Hidden Markov Models (HMMs), builds the KRONX operator chain Q \rightarrow K \rightarrow N, and computes a residence-weighted upper bound on extreme downside risk. Results are returned as a named list and, optionally, written to output_dir.

Value

A named list containing:

close_px: Numeric vector of raw close prices, or NULL when x is supplied directly.
ret: Numeric vector of log returns or supplied returns.
K: Number of hidden states.
gauss_fit: Fitted Gaussian HMM object.
t_fit: Fitted Student-t HMM object.
A_gauss: Gaussian transition matrix.
A_t: Student-t transition matrix.
epsilon: Per-state Talebian hazard vector.
Q: Hazard-adjusted operator.
K_mat: KRONX generator matrix.
N_mat: Fundamental matrix.
pi_qs: Quasi-stationary distribution.
pi_res: Residence-weight vector.
loss_threshold: Empirical left-tail return threshold.
q_state: Per-state tail probability.
bar_q: Residence-weighted tail probability.
bar_lambda: Residence-weighted hazard.
ruin_bound: Upper bound over ruin_horizon.
tail_alpha: The tail_alpha value used.
ruin_horizon: The ruin_horizon value used.
state_summary: A data.frame summarising per-state quantities.
vpath_t: Integer vector of Viterbi-decoded Student-t state labels.
output_files: Character vector of paths to written output files, or NULL if output_dir is NULL.
input_source: A short label describing the data source used.

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

Decode the most likely hidden-state path via the Viterbi algorithm.

Description

Decode the most likely hidden-state path via the Viterbi algorithm.

Usage

viterbi_decode(x, fit)

Arguments

x

Numeric vector of observations (log returns).

fit

A fitted HMM object returned by fit_hmm_em.

Value

An integer vector of length length(x) with state labels (1-indexed).