sssvcqr

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.

SS-SVCQR local coefficient surfaces for six candidate effects in the full Lucas County housing sample.

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

# 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

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.

Truth versus SS-SVCQR estimate of the three candidate deviation fields on the synthetic example.

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.

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`	Global quantile regression and inference.	No spatial coefficient fields or selection.
`GWmodel`	Geographically weighted mean regression.	Mean-loss focus, no exact zero selection.
`qgam`	Smooth additive quantile regression.	Smooth additive terms, not graph-smoothed surfaces with exact zero selection.
`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:

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.