# varGuidTS

> Variance-Guided Time-Series Modeling for Temporal Risk Detection

`varGuidTS` fits a balanced panel ARX-GARCHX model with subject-specific
intercepts,
shared population coefficients, and joint $\ell_1$ penalization on the
conditional mean and variance covariate vectors. The fitted object also
exposes an exceedance-based risk score

$$
\hat\pi_{s,t}(c) = P\!\left(Y_{s,t} > c \;\middle|\; \mathcal{F}_{t-1}\right),
$$

useful as a personalized, scale-normalized temporal risk score from
high-frequency multimodal panel data such as wearable-sensor streams.

## Installation

```r
# from GitHub
install.packages("remotes")
remotes::install_github("zionwzz/variance-guided-risk-demo")

# or from a local source tree
remotes::install_local("path/to/varGuidTS")
```

Project URL: <https://github.com/zionwzz/variance-guided-risk-demo>

## Quick start

```r
library(varGuidTS)

set.seed(1)
sim <- simulate_scenario(scen = 2, S = 4, T = 60,
                         d_noise = 4, noise_kind = "ar1", 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,
            use_x_in_variance = TRUE, maxit = 8)
print(fit)

pred <- predict(fit, df, threshold = quantile(df$y, 0.9))
head(pred)

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

# Subject-specific thresholds for personalized exceedance probabilities
subject_cutoffs <- tapply(df$y, df$s, quantile, probs = 0.75, na.rm = TRUE)
pred_subject <- predict(fit, df, threshold = subject_cutoffs,
                        innov_g = TRUE, innov_t = TRUE, df_t = 8)
head(pred_subject)
```

The README quick start gives the main workflow; the simulation function can be used to generate built-in scenarios for examples, tests, and method demonstrations.

## What the package provides

| Function | Purpose |
|---|---|
| `lmvt()` | Fit penalized panel ARX–GARCHX |
| `predict.lmvt()` | Conditional mean, variance, and exceedance probability |
| `summary.lmvt()` | Model diagnostics and coefficient summary table |
| `simulate_scenario()` | Generate panels under the four canonical scenarios |

## Maintainer

Min Lu <luminwin@gmail.com>.

## License

MIT.

## Citation

Please cite the package repository or the CRAN package record when using
`varGuidTS`.
