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 [email protected]
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

object, x	A fitted lmvt object.
...	Unused.

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

data	A data frame containing columns s (subject ID), t (integer time), y (outcome), and any number of covariate columns.
p	Autoregressive order in the mean.
q	Distributed-lag order for covariates $x$.
r	ARCH order in the variance.
s_ord	GARCH order in the variance.
lambda_beta	L1 penalty for the mean covariate coefficients.
lambda_gamma	L1 penalty for the variance covariate coefficients.
maxit	Maximum number of outer block-coordinate iterations.
tol	Absolute tolerance on the QML objective for convergence.
standardize_X	Center and scale covariates before fitting.
use_x_in_variance	Include the lagged-X block in the variance equation.
phi_cap	Upper bound on $\sum a + \sum b$.
omega_min	Lower bound on subject-specific baseline variance.
omega_cap_mult	Multiplier on median(eps^2) used as the upper bound for $\omega_s$ in the L-BFGS-B update.
gamma_steps	Inner proximal-gradient steps for $\gamma$ per outer iter.
gamma_step	Step size for the proximal-gradient update of $\gamma$.
verbose	Logical; print per-iteration diagnostics.

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

object	A fitted lmvt object.
newdata	A data frame containing columns s, t, y and the same covariate columns used during fitting.
threshold	Threshold $c$. Numeric scalar, vector of length nrow(newdata), or per-subject vector. Defaults to the pooled 90th percentile of newdata$y.
innov_g	Logical; return Gaussian-innovation exceedance probability risk_g.
innov_t	Logical; return Student-t-innovation exceedance probability risk_t.
df_t	Degrees of freedom for the Student-t innovation.
...	Unused, kept for S3 compatibility.

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

scen	Integer 1:4 selecting one of the four scenarios.
S	Number of subjects.
T	Number of post-burn-in time points per subject.
L	Mean run length for the piecewise regime in Scenario 4.
d_noise	Number of nuisance covariates with zero true effect.
noise_kind	Either "iid" or "ar1".
threshold_c	Threshold $c$ at which the oracle exceedance probability is computed.
seed	Random seed.
floor_sigma2	Lower clamp on simulated variance.

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

object	A fitted lmvt object.
tol	Absolute value used to flag a coefficient as selected/nonzero.
include_zero	Logical; if FALSE, return only coefficients with abs(estimate) > tol.
sort_by	Sorting rule for the coefficient table. Use "block" for model order, "abs_estimate" for decreasing absolute estimate, or "none" to keep construction order.
top	Optional positive integer limiting the returned coefficient table to the first top rows after filtering and sorting.
...	Unused, kept for S3 compatibility.

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

---