cf_downscale: Coarse-to-fine spatial downscaling (CF-DS)
In spCF: Coarse-to-Fine Spatial and Spatio-Temporal Modeling

cf_downscale

R Documentation

Coarse-to-fine spatial downscaling (CF-DS)

Description

Scalable downscaling via CF-DS for predicting disaggregate-level responses from aggregate-level response Y, while ensuring that predictions aggregate exactly to the observed aggregate-level values.

Usage

cf_downscale(
  Y,
  x = NULL,
  prop_weight = NULL,
  coords,
  agg_id,
  mod_hv,
  adj = TRUE,
  nonneg = TRUE
)

Arguments

`Y`	Vector of aggregate-level response variables (length `N`).
`x`	Matrix of disaggregate-level covariates (`n x K`), assumed to match the `x` used in `cf_downscale_hv`.
`prop_weight`	Vector of disaggregate-level proportional allocation weights (length `n`), assumed to match the `prop_weight` used in `cf_downscale_hv`. See `cf_downscale_hv` for the role and examples of choices.
`coords`	Matrix of disaggregate-level coordinates (`n x 2`).
`agg_id`	Area ID for each disaggregate-level unit (length `n`).
`mod_hv`	Output object from `cf_downscale_hv`.
`adj`	Logical (default `TRUE`). When `TRUE`, a per-area multiplicative adjustment is applied to satisfy the aggregation constraint so that the downscaled predictions aggregate exactly to the observed 'Y'. When `FALSE`, the constraint is satisfied only approximately, which may be preferable when 'Y' contains noise.
`nonneg`	If `TRUE` (default), clip negative predictions to zero before the multiplicative adjustment.

Value

A list with the following elements:

beta: Regression coefficients, their standard errors, and the lower and upper limits of the 95 percent confidence intervals.
sd_summary: Standard deviation of the regression term (xb), spatial processes (spatial_scale1, spatial_scale2,...), and residuals.
e_summary: Aggregate-level holdout validation accuracy, evaluated on the validation units: R-squared (validation_R2), root mean squared error (validation_RMSE), and mean absolute error (validation_MAE). All are NA when no validation areas are available (e.g. train_rat = 1).
pred: Predictive mean (pred) and standard deviation (pred_sd) of the disaggregate-level response. The spatial-process contribution to pred_sd is rescaled by a holdout-calibrated factor (stored as other$tau) estimated on the validation areas.
bands: Bandwidth values for each accepted scale during the holdout validation in cf_downscale_hv.
Z: Predictive mean of each single-scale spatial process at the disaggregate-level (data.frame; one column per scale).
Z_sd: Predictive standard deviation of the single-scale process at the disaggregate-level units (data.frame).
other: Other internally used output objects.

Author(s)

Daisuke Murakami

References

Murakami, D., Chun, Y., Yoshida, T., & Seya, H. (2026). Scalable coarse-to-fine spatial downscaling. *ArXiv preprint*, 2606.29798.

Examples

set.seed(123)
require(sf); require(CARBayesdata)
data(GGHB.IZ)
data(pollutionhealthdata)
d  <- pollutionhealthdata[pollutionhealthdata$year == 2010, ]
ar <- merge(GGHB.IZ, d, by = "IZ")

### Disaggregate-level data (271 units)
coords <- st_coordinates(suppressWarnings(st_centroid(ar)))
x      <- data.frame(pm10 = ar$pm10, jsa = ar$jsa, price = ar$price)
prop_weight <- as.numeric(ar$expected)

### Aggregate-level data (30 units).
agg_id <- as.integer(stats::kmeans(coords, centers = 30)$cluster)

### Two types of response variables are possible:
# Y_type = "sum"  : Y_I = sum(response variable for each aggregate unit)
# Y_type = "mean" : Y_I = mean(response variable for each aggregate unit)
Y_type <- "sum"   # change to "mean" for the density-type data
Y      <- as.numeric(stats::aggregate(ar$observed, by = list(agg_id),
                       FUN = if (Y_type == "sum") sum else mean)[, 2])

### Downscaling
mh <- cf_downscale_hv(Y = Y, Y_type = Y_type, x = x,
                      prop_weight = prop_weight,
                      coords = coords, agg_id = agg_id)
md <- cf_downscale(Y = Y, x = x, prop_weight = prop_weight,
                   coords = coords, agg_id = agg_id, mod_hv = mh)

### Mapping
ar$agg_id <- agg_id
agg_poly  <- stats::aggregate(ar["agg_id"], by = list(agg_id = agg_id),
                              FUN = function(z) z[1])
agg_poly$Y<- Y
ar$pred   <- md$pred$pred
plot(agg_poly["Y"], nbreaks = 20, main = "Aggregated data")
plot(ar["pred"], nbreaks = 20, main = "Downscaling result")

spCF documentation built on Oct. 5, 2026, 5:07 p.m.