Package {gwrf}

gwrf: Geographically Weighted Random Forests

Description

Fits geographically weighted random forest models using spatially localized training neighborhoods and 'ranger' as the random forest engine. Supports fixed-distance and adaptive neighborhoods defined by observation rows or unique spatial locations, including repeated observations at the same location. Provides local predictions and permutation-based variable importance for examining spatial variation in predictive relationships. The geographical random forest approach is described by Georganos et al. (2021) doi:10.1080/10106049.2019.1595177, and the 'ranger' engine by Wright and Ziegler (2017) doi:10.18637/jss.v077.i01.

Author(s)

Maintainer: Erich Seamon erich_seamon@baylor.edu [copyright holder]

Authors:

• Erich Seamon erich_seamon@baylor.edu [copyright holder]

See Also

Useful links:

• https://github.com/hac-lab/gwrf

• Report bugs at https://github.com/hac-lab/gwrf/issues

Build a Spatial Neighborhood

Description

Identifies neighboring observations or unique spatial locations for a focal observation.

Usage

build_neighbors(
  coords,
  focal_index,
  bandwidth,
  adaptive = TRUE,
  neighbor_unit = c("row", "location"),
  location_id = NULL
)

Arguments

Value

A list describing the spatial neighborhood of the focal observation. The list contains:

neighbor_index

Integer vector giving the rows of coords included in the local neighborhood.

distances

Numeric vector containing the distance from the focal location to each selected neighboring row.

local_bandwidth

Numeric value giving the realized local bandwidth. For adaptive neighborhoods this is the distance to the most distant selected neighbor; for fixed neighborhoods it is the supplied bandwidth.

all_distances

Numeric vector of distances from the focal location to all candidate rows or unique locations, depending on neighbor_unit.

neighbor_unit

Character string indicating whether the neighborhood was constructed using rows or unique locations.

neighbor_location_id

For location-based neighborhoods, the identifiers of the selected unique locations; NULL for row-based neighborhoods.

Examples

coords <- matrix(
  c(0, 0,
    1, 0,
    2, 0,
    3, 0,
    4, 0),
  ncol = 2,
  byrow = TRUE
)

build_neighbors(
  coords = coords,
  focal_index = 3,
  bandwidth = 3,
  adaptive = TRUE
)

Validate inputs for GWRF fitting

Description

Validate inputs for GWRF fitting

Usage

check_gwrf_inputs(formula, data, coords)

Arguments

Value

Invisibly TRUE if checks pass.

Extract diagnostics from a gwrf_fit object

Description

Extract diagnostics from a gwrf_fit object

Usage

diagnostics(object, ...)

Arguments

Value

A named list containing overall model diagnostics:

rmse

Root mean squared error across fitted focal observations.

mae

Mean absolute error across fitted focal observations.

r2

Coefficient of determination calculated from observed and predicted focal values.

n_focal

Number of focal observations for which local models were requested.

Examples

example_fit <- structure(
  list(
    diagnostics = list(
      rmse = 0.25,
      mae = 0.18,
      r2 = 0.80,
      n_focal = 3
    )
  ),
  class = "gwrf_fit"
)

diagnostics(example_fit)

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

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

Fit one local random forest

Description

Fit one local random forest

Usage

fit_local_rf(
  data,
  formula,
  coords,
  focal_index,
  bandwidth,
  adaptive = TRUE,
  kernel = "bisquare",
  num.trees = 500,
  mtry = NULL,
  min.node.size = 5,
  importance = "permutation",
  use_case_weights = TRUE,
  seed = NULL,
  keep_model = FALSE,
  neighbor_unit = "row",
  location_id = NULL
)

Arguments

Value

A named list containing the results for one focal local random forest:

focal_index

Integer index of the focal observation.

observed

Observed response value at the focal observation.

prediction

Prediction from the local random forest for the focal observation.

residual

Observed minus predicted response for the focal observation.

n_local

Number of complete observations used to fit the local random forest.

local_bandwidth

Realized spatial bandwidth of the local neighborhood.

variable_importance

Named numeric vector of local variable importance values, or NA when importance cannot be calculated.

ranger_model

The fitted ranger model when keep_model = TRUE; otherwise NULL.

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))

local_fit <- fit_local_rf(
  data = dat,
  formula = y ~ x1 + x2,
  coords = coords,
  focal_index = 10,
  bandwidth = 12,
  adaptive = TRUE,
  num.trees = 10,
  seed = 1
)

local_fit$prediction

Compute kernel weights from distances

Description

Compute kernel weights from distances

Usage

kernel_weights(distances, bandwidth, kernel = "bisquare")

Arguments

Value

A numeric vector with the same length as distances. Each element is the spatial kernel weight assigned to the corresponding observation, with larger weights generally assigned to observations closer to the focal location.

Examples

distances <- c(0, 1, 2, 3)

kernel_weights(
  distances = distances,
  bandwidth = 3,
  kernel = "bisquare"
)

Return fitted local predictions

Description

Return fitted local predictions

Usage

## S3 method for class 'gwrf_fit'
predict(object, ...)

Arguments

Value

A numeric vector containing the fitted local prediction for each focal observation represented in object$local_results, in the same order as the rows of that table.

Examples

example_fit <- structure(
  list(
    local_results = data.frame(
      prediction = c(1.2, 2.1, 2.8)
    )
  ),
  class = "gwrf_fit"
)

predict(example_fit)

Print a gwrf_fit object

Description

Print a gwrf_fit object

Usage

## S3 method for class 'gwrf_fit'
print(x, ...)

Arguments

Value

Invisibly returns x, the input object of class "gwrf_fit". The function is primarily called for its side effect of printing a concise summary of the fitted model, including the model specification and global diagnostic statistics.

Examples

example_fit <- structure(
  list(
    formula = y ~ x,
    kernel = "bisquare",
    adaptive = TRUE,
    bandwidth = 10,
    num.trees = 50,
    diagnostics = list(
      rmse = 0.25,
      mae = 0.18,
      r2 = 0.80,
      n_focal = 3
    )
  ),
  class = "gwrf_fit"
)

print(example_fit)