fit_gwrf: Fit a Geographically Weighted Random Forest

In gwrf: Geographically Weighted Random Forests

Fit a Geographically Weighted Random Forest

Description

Fits a separate random-forest model for each focal observation or spatial location using observations selected from a geographically defined local neighborhood. Neighborhoods may be defined using individual data rows or unique spatial locations, allowing the function to support repeated observations at the same location, including spatial panel data.

Usage

fit_gwrf(
  formula,
  data,
  coords,
  bandwidth,
  adaptive = TRUE,
  kernel = "bisquare",
  neighbor_unit = c("row", "location"),
  location_id = NULL,
  num.trees = 500,
  mtry = NULL,
  min.node.size = 5,
  importance = "permutation",
  use_case_weights = TRUE,
  focal_indices = NULL,
  keep_local_models = FALSE,
  seed = NULL,
  verbose = TRUE
)

Arguments

formula	A model formula specifying the response and predictor variables.
data	A data frame containing the response, predictors, and any location identifiers used in the model.
coords	A numeric matrix or data frame with two columns containing the spatial coordinates associated with the rows of data.
bandwidth	A positive numeric value defining the local neighborhood. When adaptive = TRUE, this is the number of neighboring rows or unique spatial locations included in each local neighborhood. When adaptive = FALSE, this is a fixed distance threshold expressed in the units of coords.
adaptive	Logical. If TRUE, adaptive neighborhoods are defined using the nearest observations or unique locations. If FALSE, fixed-distance neighborhoods are used.
kernel	Character string specifying the spatial weighting kernel. The default is "bisquare".
neighbor_unit	Character string indicating whether neighborhoods are defined using individual data rows ("row") or unique spatial locations ("location").
location_id	Optional vector identifying the spatial location associated with each observation. Required when neighbor_unit = "location". All eligible observations associated with selected neighboring locations are retained for local model fitting.
num.trees	Number of trees grown in each local random forest.
mtry	Number of predictor variables randomly sampled as candidates at each split. If NULL, the value is determined by ranger::ranger().
min.node.size	Minimum terminal-node size used by each local random forest.
importance	Character string specifying the variable-importance method passed to ranger::ranger(). The default is "permutation".
use_case_weights	Logical indicating whether spatial kernel weights are supplied to the local random forest as case weights.
focal_indices	Optional integer vector identifying the focal observations for which local models should be fitted. If NULL, local models are fitted for all eligible focal observations.
keep_local_models	Logical indicating whether fitted local ranger model objects are retained in the returned object.
seed	Optional integer random seed used for reproducible local random-forest fitting.
verbose	Logical indicating whether progress messages are displayed during model fitting.

Details

For each focal observation, the function constructs a spatial neighborhood, fits a local random forest using the observations contained in that neighborhood, and returns the focal prediction and predictor-importance values. When neighbor_unit = "location", adaptive bandwidth refers to the number of nearest unique spatial locations rather than the number of individual rows. This prevents repeated observations from the same location from being treated as separate spatial neighbors.

Spatial weights are determined by the selected kernel and the distances between the focal location and neighboring observations or locations. Variable importance describes predictive reliance within each fitted local forest and does not indicate effect direction, statistical significance, or causality.

Value

An object of class "gwrf_fit". The object is a named list containing the model call and specification, input data and coordinates, neighborhood and random-forest settings, local model results, optional fitted local models, and model diagnostics.

The local_results component is a tibble with one row per fitted focal observation and columns for the focal index, observed response, local prediction, residual, local sample size, realized bandwidth, coordinates, and, when available, local variable-importance values prefixed with "vi_".

The diagnostics component is a list containing overall RMSE, MAE, R-squared, and the number of focal models fitted.

See Also

ranger

Examples

set.seed(1)

n <- 20
dat <- data.frame(
  y = rnorm(n),
  x1 = rnorm(n),
  x2 = runif(n)
)
coords <- cbind(seq_len(n), rep(0, n))

fit <- fit_gwrf(
  y ~ x1 + x2,
  data = dat,
  coords = coords,
  bandwidth = 12,
  adaptive = TRUE,
  num.trees = 10,
  focal_indices = 1:3,
  seed = 1,
  verbose = FALSE
)

fit
fit$local_results

gwrf documentation built on Aug. 24, 2026, 5:15 p.m.