Fits a Gaussian GWR on an sf layer with an adaptive or a fixed bandwidth.
Each location gets its own regression, weighted towards nearby
observations, so the coefficients can vary across the map. Use it when
that variation is the question; fit_bayesian_spatial_model()
fits one global relationship plus a spatial random field.
Usage
fit_gwr_model(
data_sf,
response_var,
predictor_vars,
adaptive = TRUE,
bandwidth = NULL,
kernel = c("bisquare", "gaussian", "tricube", "boxcar", "exponential"),
.already_prepped = FALSE
)Arguments
- data_sf
An sf object with response, predictors, and geometries.
- response_var
Response column name.
- predictor_vars
Predictor column names (numeric columns; a name given twice counts once).
character(0)fits the model with a local intercept alone: the fitted value at a location is the kernel-weighted mean of the response around it. That is the baseline a GWR with predictors has to beat, since any GWR beats a global mean through its local intercept, andselect_features_forward()fits it as the null model of a GWR sweep.- adaptive
Logical; use adaptive bandwidth. Default TRUE. When TRUE, bandwidth is an integer number of nearest neighbours. When FALSE, bandwidth is a fixed distance in CRS units.
- bandwidth
Optional numeric bandwidth value. For adaptive mode this is an integer (number of neighbours); for fixed mode a distance in the units of the projected CRS the fit runs in.
prep_model_data()projects geographic input before the bandwidth is used, so 0.2 supplied for lon/lat data is 0.2 metres, not 0.2 degrees. Read the CRS offsf::st_crs(fit$data_sf), or passtarget_crstoensure_projectedbeforehand to fix the units yourself. If NULL (default), the bandwidth with the lowest AICc is searched for (the lowest leave-one-location-out error when observations share a location); see Bandwidth selection. Withadaptive = FALSE, a bandwidth smaller than a ten-thousandth of the data's extent raises a warning naming the extent and the CRS the fit runs in: every local window then holds its own observation alone. Withadaptive = TRUEthe count is rounded, and one too small for the model is raised, with a warning, to the smallest that gives every local regression more points of non-zero weight than parameters: the number of predictors plus 3 for the bisquare and tricube kernels (which give the farthest neighbour in a window weight 0), plus 2 for the others. That floor is enough unless several neighbours tie at the kernel's edge (a regular grid), which leaves a window fewer weighted points; then use a larger bandwidth. A count above the number of observations is capped at it, with a warning (a distance meant foradaptive = FALSE, most often).- kernel
Weighting kernel: one of
"bisquare"(default),"gaussian","tricube","boxcar"or"exponential". The boxcar gives weight 1 within the bandwidth (with an adaptive bandwidth, the distance to thebandwidth-th nearest neighbour) and 0 beyond it; see "The local solve" for how a neighbour at the edge is counted.- .already_prepped
Internal; leave at the default.
Value
A gwr_fit object (inherits from spatial_fit).
Supports predict(), fitted(), residuals(),
coef(), summary(), and model_metrics().
Model-specific metadata lives in $info: bandwidth, adaptive,
kernel, AICc (NA, with a warning, where AICc is
undefined: its effective number of parameters \(tr(S)\) is not below
\(n - 2\), the local regressions all but interpolate the data, and the
large negative value the formula gives would rank the fit above any
other; also where the fit reproduces the mean of the observations at
each location, see Observations that share a location),
bandwidth_is_fallback (TRUE when no bandwidth could
be selected: the search failed and the arbitrary fallback was used, or
no bandwidth has a defined criterion and the widest was used),
condition_index (the global index), local_collinearity
(one row per observation: row, x, y,
n_window, cn and cn_slopes, see
Collinearity diagnostics, then rank, the rank the local
solve found, and leverage, the observation's diagonal of the hat
matrix), n_local_collinear (the
locations whose slopes count as collinear), n_local_singular
(the locations with a local coefficient that is NA),
n_rank_deficient (the windows whose rank is below the number of
parameters), n_saturated (the windows whose fitted value is their
own observation: leverage 1),
nonfinite_coef (a logical matrix, one row per observation and
one column per term, with Intercept first, TRUE where the
local coefficient is NA, so the count in
n_local_singular can be placed), n_dropped (the rows
prep_model_data() removed for missing or non-finite values or a
bad geometry, so $n can be read against nrow(data_sf)),
n_locations (the distinct locations of the rows fitted; see
Observations that share a location),
tr_S, enp, edf and sigma2 (the trace of the
hat matrix, the effective number of parameters
\(2\,tr(S) - tr(S^\top S)\), the effective residual degrees of freedom
and the residual variance, as GWmodel defines them),
global_ols (RSS, RMSE and AICc of one
least-squares regression on the same rows, the AICc by the same formula
with the regression's rank as its trace; a GWR whose AICc is no lower
has not shown that its coefficients vary, and summary() prints
the two side by side),
rank_tolerance, max_kernel_width (the widest kernel at any
observation, which predict() measures new locations against) and
bandwidth_search (see Bandwidth selection; NULL
when a bandwidth was supplied).
$engine holds the fit in the layout of the object
GWmodel::gwr.basic() returns, under the same names: SDF (a
SpatialPointsDataFrame of the local coefficients, y,
yhat, residual, CV_Score, Stud_residual, the
standard errors <term>_SE, the t values <term>_TV and
Local_R2), GW.diagnostic, GW.arguments and
lm (the global least-squares fit). It is a plain list, not a
gwrm object. Where a predictor or the response was taken less
its centre (see "The local solve"), lm is solved on the
centred columns and returned as the fit at the data's origin: its
coefficients, fitted values, qr and effects are those of
the raw columns, so summary(), vcov(), confint()
and predict() on it give the intercept at the data's 0 and its
standard error, and the slopes and residuals are those of the centred
fit. With a predictor more than about 1e7 times its spread from 0,
predict(se.fit = TRUE) on it stops with "singular matrix":
qr.solve() reads the triangular factor at the data's origin as
singular. predict() on the fit itself has no such limit.
centres holds what was taken off: predictors, the centre
of each column of the design (Intercept first, 0 for a column
used as it is), NULL where none was, and response, 0
where none was.
Details
The kernels, the bandwidth conventions and the diagnostics are those of GWmodel. This package solves the local regressions itself, each as a weighted least squares by pivoted QR, so a window whose design is rank deficient neither stops the fit nor returns coefficients made of rounding error.
The local solve
At every observation the model is a weighted least squares on the observations whose kernel weight is above zero. It is solved by a Householder QR with column pivoting of the window's weighted design, never by inverting \(X^\top W X\). Before the factorisation each row is multiplied by the square root of its weight over the window's largest weight, and each predictor is divided by its standard deviation over the whole data and centred in the window, so nothing below depends on a predictor's origin or units: an indicator coded 0/1 and one coded 288.7/289.3 give the same fit.
Under the boxcar kernel an observation whose squared distance is within
one part in ten million of the window's edge counts as at the edge, and
inside, so on a regular grid every neighbour tied with the last one is in
the window in any unit and at any origin where the doubles hold the
coordinates to better than about one part in 1e8 of the distances
between neighbours. Farther from the origin the doubles round the
coordinates more coarsely, and where a neighbour lies past the edge by
less than that rounding the call warns, with class
"spatialkit_xy_imprecise" (see "Coordinates far from the origin"
in spatialkit-geometry); the windows are those the coordinates as
stored give.
A predictor whose centre is more than 1000 times its spread (a timestamp
in seconds, a northing, 1e8 plus a spread of 1) is taken less its centre
first. So is a response whose centre is more than 1000 times its spread
(1e8 plus a spread of 1), whose raw values lose their spread to rounding
(1e15 plus a spread of 1, stored to an eighth), or whose least-squares
residuals on the predictors do. The bandwidth search, the
local regressions, the global least-squares fit and the centred condition
indices (info$condition_index, cn_slopes) then work on the
spread and not on the rounding of the offset, and the centres are added
back only to what is returned in the data's units: the fitted values, the
local intercepts, the intercept and fitted values of $engine$lm,
and predict()'s values, which take a new row's predictors about the
same centres. Residuals, slopes and their standard errors, AICc and the
bandwidth are those of the same values at 0, to rounding; the fitted
values and predictions of a response at 1e15 are held to the eighth a
double holds there. model_metrics(), summary() and the
cross-validations score the fit on the response, the fitted values and
the predictions less the response's centre, so their RMSE, MAE and
R-squared are those of the same values at 0 too. Every other predictor
and response is used as it is.
A response whose values, less any centre, reach beyond 1e100, or whose
spread is below 1e-100, is divided by a power of two, which rounds
nothing: the residual sum of squares, AICc and the bandwidth search
square the residuals, and at 1e160 those squares overflow and at 1e-160
they lose their bits. The bandwidth is then that of the same values in
ordinary units, and the fitted values, the residuals, the coefficients,
their standard errors and $engine$lm are those of the same values
times the factor; AICc, the AICc of info$bandwidth_search among
them, gains \(2 n \log\) of the factor, and a cross-validation score
of the search is multiplied by its square. The residual sum of
squares, info$sigma2 and such a score are in the response's units
squared, and are NA, with a warning, where a double cannot hold
them there;
predict(se.fit = TRUE) then takes its standard errors from the
residual standard deviation, which it can hold.
One tolerance, 1e-7, decides what a window can estimate:
Rank. A predictor is aliased in a window when the part of it that the terms entered before it do not explain varies there by less than
1e-7of its standard deviation over the study area (the length of that part over the weighted rows). A predictor that is constant among the weighted observations, two predictors that are exactly collinear there, and a window with fewer weighted observations than parameters are the cases. No weight is cut off: under a Gaussian or exponential kernel every observation enters, and distant ones stop counting only through this rule.Coefficients. A coefficient is returned when it has one value over all least-squares solutions of the window, and is
NAotherwise. The slope of an aliased predictor isNA. So is the intercept when a predictor is constant in the window at a value other than 0, because it would absorb that value times the slope; when the constant is 0 the intercept is identified and returned. The slopes of the other predictors are returned.Fitted values. The fitted value at an observation is always estimable (its own row is in its window) and is returned, also where a coefficient is
NA.
A window of deficient rank does not stop the fit. A warning of class
"spatialkit_gwr_rank_deficient" says how many windows are affected
and how many coefficients of each term are NA;
info$n_rank_deficient, info$n_local_singular,
info$nonfinite_coef and the rank column of
info$local_collinearity locate them. When many windows hold a
predictor constant, a local coefficient is the wrong model for it: its
effect is identified only as one global coefficient (a mixed GWR, as
GWmodel::gwr.mixed() fits).
The leverage of each observation, the trace of the hat matrix, the
residual sum of squares, AICc and the coefficients' standard errors come
from the same decomposition. On a window of full rank every one of them
equals what GWmodel::gwr.basic() returns, to rounding error: the
largest relative difference in any cell of the six fits the package's
tests compare is 3e-12. They are not bit-identical, since GWmodel
inverts the normal equations.
Bandwidth selection
With bandwidth = NULL the AICc is scored on 16 bandwidths spaced
evenly in the logarithm over the whole range, and then refined by a
golden-section search between the grid points either side of the best
(and, for a count of neighbours, at the counts next to the one it ends
on). That is about 20 to 35 fits of the model in all.
The range runs, for an adaptive bandwidth, from the smallest count the
model's parameters allow to every observation; for a fixed one, from the
distance at which half of the windows hold one observation more than the
model has parameters (a third of it for the Gaussian and exponential
kernels) to the largest distance between two observations. The bandwidth
returned is the best of all those scored.
A golden-section search over the whole range, which
GWmodel::bw.gwr() runs, assumes the criterion has one minimum. It
has several when the coefficients vary at a range that only a few dozen
observations resolve, and that search then returns a bandwidth near the
top of the range, a nearly global regression, as the selected one.
A candidate bandwidth with windows of deficient rank is scored on its fitted values, which those windows do estimate. One at which AICc is undefined (\(tr(S)\) not below \(n - 2\)) cannot be selected, and neither can one at which a term of the model is estimable at no location: the fit would have no coefficient for it anywhere.
The criterion at a candidate comes from the local solve. Under a Gaussian
or an exponential kernel, which weight every observation at every
location, the fitted value and leverage of a window that is far from rank
deficient are computed from its centred cross-products, many windows to
one matrix product, and the windows that are not are left to the QR; the
two routes agree to rounding error (1e-9 relative in the package's
tests) and take the same rank decisions. With several strongly
correlated predictors more windows are left to the QR and the search is
slower. The fit at the selected bandwidth is always the QR's.
Everything scored is kept in info$bandwidth_search:
approach (the criterion minimised, "AICc" or "CV"),
by_location and n_locations (see Observations
that share a location), curve
(bandwidth, criterion, trace of the hat matrix, windows of deficient rank,
and whether the point belongs to the grid or the refinement),
undefined (how many of the bandwidths scored have no criterion,
by reason),
n_local_minima and multimodal (local minima on the grid),
within and flat (the range of bandwidths whose AICc is
within 2 of the minimum, and whether half the grid is),
near_global (the widest bandwidth of the range is within 2 of the
minimum), at_upper and at_lower (the minimum is at an end
of the range). When any of these holds, one logged line says so (on the
console, unless spatialkit_quiet() is on; in the trace only
for the folds of a cross-validation); it is a
message, not a warning, because a minimum at or near the top of the range
is the ordinary outcome for a process whose coefficients do not vary.
Read near_global as "AICc does not tell this fit from one global
regression".
AICc is an in-sample criterion and rewards interpolation between
neighbours. The bandwidth it selects can score worse than a wider one on
held-out spatial blocks; cv_gwr with a supplied
bandwidth is the check.
Observations that share a location
Rows with the same coordinates (several years at one station, replicate
samples of one plot, records geocoded to one address) get one kernel
weight at every regression point. info$n_locations is the number
of distinct locations, and when it is below n a warning of class
"spatialkit_gwr_repeated_locations" gives the counts.
The bandwidth is then not selected by AICc. AICc counts the rows at one
location as independent observations. When a location has an effect of
its own, a window that holds little but the location reproduces its
mean, the residual sum of squares falls to the spread within locations,
and AICc is lowest where the windows interpolate, which is where the
error of predicting new sites is largest. A floor on the bandwidth does
not repair that, because the criterion keeps falling towards the floor.
With bandwidth = NULL the search therefore minimises the
leave-one-location-out sum of squares: each location's
observations are predicted by the local regression there without any of
them, the kernel keeping its width, and the squared errors are summed.
It is computed from the hat matrix of the fit at each bandwidth, without
refitting. A bandwidth at which some location cannot be predicted from
the others cannot be selected. info$bandwidth_search$approach is
then "CV" and by_location is TRUE. On a layer
without repeat locations nothing changes: the criterion is AICc.
The range of the search counts locations. For an adaptive bandwidth it starts at the smallest count that gives every window one location more than the model has parameters, and for a fixed bandwidth at the distance at which half the windows hold that many locations.
AICc and the standard errors still assume independence.
info$AICc, the comparison with the global regression in
summary() and the standard errors of coef(se = TRUE) and
predict(se.fit = TRUE) treat every row as an independent
observation. With an effect shared by the rows of a location the standard
errors are too small, and AICc compared across bandwidths favours the
small ones. info$AICc is NA, with a warning, when the fit
(nearly) reproduces the mean of the observations at each location:
\(tr(S)\) is then not below the number of rows that differ in location
or in a predictor, minus 2, and the value the formula gives measures only
the spread among observations that share a location. If the repeats are
replicates of one measurement, fit their means, one row per location.
Collinearity diagnostics
The function computes scaled condition indices of the design and
warns when one exceeds 30, the conventional threshold, which Wheeler &
Tiefelsdorf (2005) carry over to the local designs of GWR. An index is
the ratio of the largest to the smallest singular value (from an SVD) after
each column is scaled (Belsley, Kuh & Welsch 1980); an exactly singular
design gives Inf, which counts as the worst case, not an exempt one.
Scaling makes the index independent of the predictors' units;
kappa() on the raw matrix is not, and a threshold on it is a
threshold on nothing in particular.
A global index is computed on the predictors centred at their means
(with the intercept, which centring makes orthogonal to them), and kept as
info$condition_index. It measures how nearly the predictors are
collinear with one another over the whole study area; it is 1 for a single
predictor, and a change of origin (degrees C or kelvin, a year or years
since 2000) does not move it.
Local indices are then computed at every location, on the weighted
design of the local regression there: each row weighted by the square root
of its kernel weight at the bandwidth the model is fitted with (supplied or
selected), with rows of negligible weight (below 1e-8) dropped. A window
left with fewer rows than columns counts as singular. Two indices are
kept for each window, as columns of info$local_collinearity:
cnBelsley's index of the intercept plus the predictors, scaled to unit length but not centred. A predictor whose values in the window are far from 0 against their spread (a year, a temperature in kelvin) is collinear with the intercept and raises it: the local intercept is then an extrapolation to 0 and is ill-determined, but the slopes are not.
cn_slopesThe index for the slopes: the predictors centred at their weighted mean in the window and each divided by its standard deviation over the whole study area. It is 1 when the predictors vary as much, and as independently, inside the window as they do across the study area; it grows as a predictor becomes nearly constant inside the window (a regional covariate) or two predictors move together there. It does not depend on the predictors' origin or units.
A window's slopes count as collinear when cn_slopes is above 30 or
singular. Those windows are counted in info$n_local_collinear. A
predictor that is constant, or nearly so, inside a window is caught this
way whether it is alone or has company, so a single predictor is surveyed
too. cn does not enter: the local solve centres each predictor in its
window, so a predictor far from zero (a year, a temperature in kelvin, a
coordinate) has the slopes it would have at any other origin, and is not
flagged, however large cn is. The one exception is a cn that is
singular to machine precision, where the predictor's spread is lost in the
rounding of its own values.
A warning is issued whenever any location has collinear slopes; the
wording reports a percentage when more than 25% of locations are affected
and a count otherwise. Both are real R warnings, not log lines.
Coefficients at a near-singular window are least-squares estimates with
little to rest on, and can be implausibly large. An exactly singular
window (an indicator that is constant inside it, or fewer observations
than parameters) is of deficient rank: the coefficients it cannot estimate
are NA and the fit is returned (see "The local solve").
A window with only cn above 30 raises no warning:
plot(fit, type = "coefficients", term = "Intercept") masks it, and slope
maps do not. Centre such a predictor if you want an interpretable local
intercept. The survey is a caution about how well a coefficient is
determined, on rows whose weight is not negligible; the solve's rank is
the statement about whether it is determined at all.
A further warning counts local regressions that have no fitted value.
That happens where the kernel weights are undefined: with an adaptive
bandwidth of k, a location where k or more observations share the same
coordinates has a kernel of zero width, and every kernel but the boxcar
divides 0 by 0 there. The warning names that cause when it applies.
fitted(), residuals(), summary() and model_metrics() all drop those
rows, so when this warning fires the metrics describe only the part of the
study area that fitted.
See also
cv_gwr() to score the fit on spatial folds;
predict() (spatial_fit-predict) and coef()
(spatial_fit-coef) for predictions and local coefficients;
gwr_model_selection() and
select_features_forward() to choose the predictors;
plot.spatial_fit() to map the coefficients.
Other model fitting:
fit_bayesian_spatial_model(),
fit_rf_model(),
gp_lengthscale_bounds(),
new_spatial_fit()
Examples
library(sf)
set.seed(1)
n <- 80
dat <- st_as_sf(
data.frame(x = 5e5 + runif(n, 0, 1000), y = 5e6 + runif(n, 0, 1000),
elev = rnorm(n)),
coords = c("x", "y"), crs = 32632
)
# The slope on elev rises from 1 in the west to 3 in the east.
east <- (st_coordinates(dat)[, 1] - 5e5) / 1000
dat$price <- 10 + (1 + 2 * east) * dat$elev + rnorm(n, 0, 0.3)
fit <- fit_gwr_model(dat, "price", "elev", bandwidth = 30)
summary(fit)
#> Summary of <gwr_fit> fit (n = 80)
#>
#> Formula: price ~ elev
#>
#> In-sample metrics:
#> RMSE = 0.2906
#> MAE = 0.2224
#> R^2 = 0.9798
#> SMAPE = 2.45%
#>
#> Effective parameters: 18.1 (residual degrees of freedom 61.9)
#> Global least squares on the same rows: AICc 155.84, RMSE 0.6161
#> This fit: AICc 65.80 (below the global fit's by 90.04)
# The local slopes follow the west-east change.
summary(coef(fit)$elev)
#> Min. 1st Qu. Median Mean 3rd Qu. Max.
#> 1.325 1.596 1.967 2.075 2.603 2.780
head(coef(fit, se = TRUE)$se) # their standard errors
#> Intercept elev
#> 1 0.07569645 0.07924018
#> 2 0.07355111 0.08520330
#> 3 0.07902655 0.08016434
#> 4 0.07856923 0.08452376
#> 5 0.07336864 0.08750536
#> 6 0.07956501 0.08663857
head(predict(fit, newdata = dat))
#> [1] 9.221713 9.677920 12.614503 6.046987 10.849371 11.063047