# sssvcqr

<!-- badges: start -->
[![R-CMD-check](https://github.com/Stork343/sssvcqr/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/Stork343/sssvcqr/actions/workflows/R-CMD-check.yaml)
[![Lifecycle: stable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable)
[![License: GPL v3](https://img.shields.io/badge/License-GPL_v3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
<!-- badges: end -->

**Sparse-Smooth Spatially Varying Coefficient Quantile Regression in R.**
`sssvcqr` fits a convex global–local quantile regression model that
decomposes each candidate spatial coefficient into a global baseline and a
location-specific deviation, selects global versus local effects with a
group penalty, and smooths the surviving deviations with a graph Laplacian
over a $k$-nearest-neighbor proximity graph.

<p align="center">
  <img src="man/figures/README-lucas-all-coefficients.png" width="100%"
       alt="SS-SVCQR local coefficient surfaces for six candidate effects in the full Lucas County housing sample." />
</p>

The figure above is reproduced by the replication script: each panel maps
one local hedonic effect (age, log living area, log lot size, rooms,
bedrooms, garage area) at the median quantile, anchored on Lucas County,
Ohio. Age has by far the largest spatial heterogeneity; the other effects
are nearly globally constant.

## Installation

```r
# Development version from GitHub
remotes::install_github("Stork343/sssvcqr")

# Or, from a downloaded source tarball
install.packages("sssvcqr_0.0.3.tar.gz", repos = NULL, type = "source")
```

A CRAN release is planned alongside the JSS software paper.

## Sixty-second example

```r
library("sssvcqr")

# Synthetic data with known active set: x1 and x3 are spatial, x2 is global.
dat <- simulate_sssvcqr_data(n = 120, q = 2, p = 3, seed = 20260505)

# Fit at the median quantile.
fit <- ss_svcqr(
  y = dat$y, Z = dat$Z, X = dat$X, u = dat$u,
  tau = 0.5, lambda1 = 5, lambda2 = 0.1, k_nn = 8,
  control = list(max_iter = 180, warn_nonconvergence = FALSE)
)

summary(fit)
#> Sparse-smooth SVC quantile regression summary
#>   n = 120  q = 2  p = 3  tau = 0.5
#>   lambda1 = 5  lambda2 = 0.1
#>   iterations = 77  converged = TRUE
#>
#> alpha:
#> [1] 1.0826 0.8039
#> beta_G:
#> [1] 1.3700 0.9479 0.2285
#> delta L2 norms:
#> [1] 1.0598 0.0000 1.1764       # <- x2 correctly selected as global
```

The estimated deviation L2 norms are the visual signature of
global-versus-local selection: the second one is *exactly* zero, while the
first and third reflect the recovered spatial structure.

<p align="center">
  <img src="man/figures/README-synthetic-recovery.png" width="80%"
       alt="Truth versus SS-SVCQR estimate of the three candidate deviation fields on the synthetic example." />
</p>

## Main functions

| Function | Purpose |
| --- | --- |
| `ss_svcqr()` | Fit SS-SVCQR by ADMM at a fixed quantile level. |
| `cv_ss_svcqr()` | Tune `lambda1`, `lambda2` by spatially blocked cross-validation. |
| `predict.sssvcqr()` | Predict fitted quantiles or local coefficient surfaces. |
| `plot.sssvcqr()` | Map deviations, local coefficients, residuals, or convergence traces. |
| `build_graph_laplacian()` | Sparse `k`-nearest-neighbor graph and Laplacian. |
| `make_spatial_folds()` | Spatially coherent CV folds. |
| `simulate_sssvcqr_data()` | Synthetic data with known truth. |
| `selection_recovery_table()` | Compare known truth with estimated active set. |
| `kkt_sssvcqr()` | First-order KKT diagnostics for a fitted model. |

## Vignettes and documentation

- `vignette("sssvcqr-introduction")` — full synthetic walkthrough (fit,
  plot, predict, CV, diagnostics).
- `vignette("lucas-county-example")` — case study on the bundled Lucas
  County subset.
- Function reference and articles: see the package help pages
  (`?ss_svcqr`, `?cv_ss_svcqr`, ...) and the vignettes listed above.

## Related R workflows

`sssvcqr` is for users who need *all three* of the following in one
fitted object: conditional quantile regression, spatially varying
coefficient surfaces over observed locations, and exact global-versus-local
selection of complete candidate coefficient surfaces.

| Adjacent package | Strength | What it does *not* do |
| --- | --- | --- |
| [`quantreg`](https://CRAN.R-project.org/package=quantreg) | Global quantile regression and inference. | No spatial coefficient fields or selection. |
| [`GWmodel`](https://CRAN.R-project.org/package=GWmodel) | Geographically weighted mean regression. | Mean-loss focus, no exact zero selection. |
| [`qgam`](https://CRAN.R-project.org/package=qgam) | Smooth additive quantile regression. | Smooth additive terms, not graph-smoothed surfaces with exact zero selection. |
| [`mgcv`](https://CRAN.R-project.org/package=mgcv) | Smooth conditional mean models. | Mean-focused; no quantile-loss SS-SVCQR target. |

## Replication and JSS materials

The repository includes a top-level `replication/` directory for the JSS
software-paper workflow:

```r
source("replication/code.R")
```

regenerates the synthetic example, blocked-CV results, software-comparison
tables, the full-sample Lucas County case study and its multi-quantile
comparison, plus a session log under `replication/output/`. The fast mode
(`SSSVCQR_FAST_REPLICATION=true`) skips the full Lucas fit; the default
mode reproduces the entire manuscript.

## Citation

If you use `sssvcqr` in published work, please cite both the methodological
manuscript and the software:

> Hou, H. (2026). *Sparse-Smooth Spatially Varying Coefficient Quantile
> Regression.* Spatial Statistics. Accepted for publication.

> Hou, H. (2026). *sssvcqr: Sparse-Smooth Spatially Varying Coefficient
> Quantile Regression.* R package version 0.0.3.
> <https://github.com/Stork343/sssvcqr>

A `CITATION` file is shipped with the package: run
`citation("sssvcqr")` for the canonical entry.

## Lifecycle

This package is in a stable research-software state. The exported API is
small, documented, and covered by unit and numerical tests (line coverage
≈ 84%). Future releases may add a formula interface, compiled linear
algebra kernels, uncertainty summaries, and grid-prediction helpers in
response to user and reviewer feedback.

## License

GPL (>= 3). See the `LICENSE` file shipped with the package.
