Package {varGuidTS}

varGuidTS: Variance-Guided Time-Series Modeling for Temporal Risk Detection

Description

Fits a balanced panel ARX-GARCHX model with subject-specific intercepts, shared population coefficients, and joint L1 penalization on the conditional mean and variance. Provides an exceedance-based risk score \pi_{s,t}(c) = P(Y_{s,t} > c \,|\, F_{t-1}) for personalized temporal risk assessment from wearable-sensor and other high-frequency panel time-series data.

Author(s)

Maintainer: Min Lu luminwin@gmail.com
Authors: Zihao Wang, Min Lu

References

Tibshirani R. (1996). "Regression Shrinkage and Selection Via the Lasso." Journal of the Royal Statistical Society: Series B, 58(1), 267–288. doi:10.1111/j.2517-6161.1996.tb02080.x

Bollerslev T. (1986). "Generalized Autoregressive Conditional Heteroskedasticity." Journal of Econometrics, 31(3), 307–327. doi:10.1016/0304-4076(86)90063-1

Medeiros M. C. and Mendes E. F. (2016). "L1-Regularization of High-Dimensional Time-Series Models with Non-Gaussian and Heteroskedastic Errors." Journal of Econometrics, 191(1), 255–271. doi:10.1016/j.jeconom.2015.10.011

See Also

lmvt, predict.lmvt, summary.lmvt, simulate_scenario

Extract or print coefficients from a fitted lmvt model

Description

coef() returns the list of fitted parameter blocks (subject-specific intercepts, AR coefficients, mean covariate coefficients, baseline variances, ARCH/GARCH parameters, and variance covariate coefficients).

print() produces a one-screen summary of the fit.

Usage

## S3 method for class 'lmvt'
coef(object, ...)
## S3 method for class 'lmvt'
print(x, ...)

Arguments

Value

For coef.lmvt(), a named list containing fitted coefficient blocks:

alpha

subject-specific intercepts in the conditional mean model.

theta

shared autoregressive coefficients for lagged responses.

beta

shared coefficients for covariates in the conditional mean model.

omega

subject-specific baseline variance parameters.

a

shared ARCH coefficients for lagged squared residuals.

b

shared GARCH coefficients for lagged conditional variances.

gamma

shared coefficients for covariates in the conditional variance model.

For print.lmvt(), the fitted object x is returned invisibly after printing a short model summary.

See Also

lmvt, summary.lmvt

Fit a penalized panel ARX-GARCHX model

Description

Joint maximum-quasi-likelihood fit of the conditional mean and variance across a balanced panel of subjects, with subject-specific intercepts, shared population coefficients, and L1 penalties on the mean and variance covariate vectors.

Usage

lmvt(data,
     p = 1, q = 0,
     r = 1, s_ord = 1,
     lambda_beta = 0,
     lambda_gamma = 0,
     maxit = 200, tol = 1e-4,
     standardize_X = TRUE,
     use_x_in_variance = TRUE,
     phi_cap = 0.995,
     omega_min = 1e-6,
     omega_cap_mult = 10,
     gamma_steps = 8,
     gamma_step = 1e-3,
     verbose = FALSE)

Arguments

Value

An object of class "lmvt": a list with elements alpha, theta, beta, omega, a, b, gamma, ids, xcols, x_center, x_scale, orders, penalties, call, converged, iters, mean_times, var_times, iter_times.

References

Tibshirani R. (1996). "Regression Shrinkage and Selection Via the Lasso." Journal of the Royal Statistical Society: Series B, 58(1), 267–288. doi:10.1111/j.2517-6161.1996.tb02080.x

Bollerslev T. (1986). "Generalized Autoregressive Conditional Heteroskedasticity." Journal of Econometrics, 31(3), 307–327. doi:10.1016/0304-4076(86)90063-1

Medeiros M. C. and Mendes E. F. (2016). "L1-Regularization of High-Dimensional Time-Series Models with Non-Gaussian and Heteroskedastic Errors." Journal of Econometrics, 191(1), 255–271. doi:10.1016/j.jeconom.2015.10.011

See Also

predict.lmvt, summary.lmvt, simulate_scenario

Examples

set.seed(1)
sim <- simulate_scenario(scen = 1, S = 5, T = 80, d_noise = 5,
                         noise_kind = "iid", seed = 1)
df  <- sim[, c("s","t","y", grep("^X|^Noise|^Xbin",
                                 names(sim), value = TRUE))]
fit <- lmvt(df, p = 1, q = 0, r = 1, s_ord = 1,
            lambda_beta = 0.05, lambda_gamma = 0.05)
print(fit)

Predict from a fitted lmvt object

Description

Computes the conditional mean \hat\mu_{s,t}, conditional standard deviation \hat\sigma_{s,t}, and the exceedance-based risk score \hat\pi_{s,t}(c) = P(Y_{s,t} > c \,|\, F_{t-1}) on a new (or held-out) panel data frame.

Usage

## S3 method for class 'lmvt'
predict(object, newdata, threshold = NULL,
        innov_g = TRUE, innov_t = FALSE, df_t = 6, ...)

Arguments

Value

A data frame with columns s, t, yhat = muhat, muhat, sigmahat, threshold_used, and one or both of risk_g, risk_t.

See Also

lmvt, summary.lmvt

Examples

set.seed(1)
sim <- simulate_scenario(scen = 2, S = 4, T = 70, d_noise = 4,
                         noise_kind = "iid", seed = 1)
df  <- sim[, c("s", "t", "y", grep("^X|^Noise|^Xbin",
                                   names(sim), value = TRUE))]
fit <- lmvt(df, p = 1, q = 0, r = 1, s_ord = 1,
            lambda_beta = 0.05, lambda_gamma = 0.05, maxit = 8)

# 1) Pooled/global threshold: one cutoff is applied to every row.
pr_global <- predict(fit, df, threshold = stats::quantile(df$y, 0.90))
head(pr_global)

# 2) Subject-specific thresholds: use a named vector indexed by subject ID.
subject_cutoffs <- tapply(df$y, df$s, stats::quantile, probs = 0.75,
                          na.rm = TRUE)
pr_subject <- predict(fit, df, threshold = subject_cutoffs)
head(pr_subject)

# 3) Return both Gaussian and Student-t exceedance risk scores.
pr_t <- predict(fit, df, threshold = subject_cutoffs,
                innov_g = TRUE, innov_t = TRUE, df_t = 8)
head(pr_t[, c("s", "t", "muhat", "sigmahat", "risk_g", "risk_t")])

Simulate a panel ARX-GARCHX dataset

Description

Simulates a balanced panel from one of four built-in demonstration scenarios. Returns a long-format data frame with the response y, oracle mean and variance, the covariate block, optional regime indicator, and the oracle exceedance probability.

Usage

simulate_scenario(scen = 1L, S = 8L, T = 240L, L = 20L,
                  d_noise = 20L, noise_kind = c("iid", "ar1"),
                  threshold_c = 1.0, seed = NULL,
                  floor_sigma2 = 1e-10)

Arguments

Value

A data frame with columns s, t, y, oracle mu and sigma, covariate columns, optional Xbin, and the oracle exceedance probability pi_true. Generating parameters are stored in attr(., "params").

References

Tibshirani R. (1996). "Regression Shrinkage and Selection Via the Lasso." Journal of the Royal Statistical Society: Series B, 58(1), 267–288. doi:10.1111/j.2517-6161.1996.tb02080.x

Bollerslev T. (1986). "Generalized Autoregressive Conditional Heteroskedasticity." Journal of Econometrics, 31(3), 307–327. doi:10.1016/0304-4076(86)90063-1

Medeiros M. C. and Mendes E. F. (2016). "L1-Regularization of High-Dimensional Time-Series Models with Non-Gaussian and Heteroskedastic Errors." Journal of Econometrics, 191(1), 255–271. doi:10.1016/j.jeconom.2015.10.011

Examples

set.seed(7)
sim <- simulate_scenario(scen = 2, S = 4, T = 50,
                         d_noise = 3, noise_kind = "iid", seed = 7)
head(sim)

Summarize a fitted lmvt object

Description

Produces model-level diagnostics and a coefficient summary table for a fitted penalized panel ARX-GARCHX model. The table includes subject-specific mean intercepts, autoregressive coefficients, mean covariate coefficients, subject-specific variance baselines, ARCH/GARCH coefficients, and variance covariate coefficients. Because lmvt() fits a penalized quasi-likelihood model, the table reports estimates and variable-selection indicators rather than classical standard errors or p-values.

Usage

## S3 method for class 'lmvt'
summary(object, tol = 1e-8, include_zero = TRUE,
        sort_by = c("block", "abs_estimate", "none"), top = NULL, ...)

Arguments

Value

summary.lmvt() returns an object of class "summary.lmvt", a list containing:

• model: model-level diagnostics;

• nonzero: counts of selected/nonzero coefficients by parameter block;

• table: the coefficient summary table after filtering/sorting;

• full_table: the complete coefficient table before filtering.

See Also

lmvt, coef.lmvt, predict.lmvt

Examples

set.seed(12)
sim <- simulate_scenario(scen = 1, S = 4, T = 60, d_noise = 4,
                         noise_kind = "iid", seed = 12)
df  <- sim[, c("s", "t", "y", grep("^X|^Noise|^Xbin",
                                   names(sim), value = TRUE))]
fit <- lmvt(df, p = 1, q = 0, r = 1, s_ord = 1,
            lambda_beta = 0.05, lambda_gamma = 0.05, maxit = 8)

# Printed summary
summary(fit)

# Programmatic coefficient table
sm <- summary(fit, include_zero = FALSE, sort_by = "abs_estimate")
sm$table