Fit a Bayesian Gaussian-process regression with brms
Source:R/model-bayesian.R
fit_bayesian_spatial_model.RdFits a regression whose residual spatial structure is modelled as a
Gaussian process over the coordinates, and so kept out of the errors.
Every quantity has a posterior, so predictions come with intervals;
cv_bayes() reports their held-out coverage and CRPS. The
spatial term is a smooth surface at a stated resolution. The Gaussian
process is fitted through a reduced-rank basis, and that basis has a
floor: an effective range below which it cannot represent structure,
reported in CRS units as $info$gp_resolution and by print().
With the defaults the floor is about 32 km along each axis on points
spread evenly over a 100 km square. Structure shorter than the floor is
counted as noise: the fitted range comes out too long, the residual
standard deviation too large, and the intervals too narrow where the
structure is. See "What the basis resolves" below.
Usage
fit_bayesian_spatial_model(
data_sf,
response_var,
predictor_vars,
family = NULL,
gp_k = NULL,
gp_c = NULL,
gp_iso = FALSE,
prior = NULL,
chains = 4,
iter = 2000,
warmup = floor(iter/2),
cores = getOption("mc.cores", 1L),
seed = 123,
backend = c("auto", "cmdstanr", "rstan"),
control = list(),
compute_loo = TRUE,
standardize_predictors = FALSE,
check_convergence = TRUE,
pointize = "auto",
boundary = NULL,
gp_resolution = NULL,
.already_prepped = FALSE
)Arguments
- data_sf
An sf object with response, predictors, and geometries.
- response_var
Response column name.
- predictor_vars
Predictor column names. May be
character(0)for an intercept-only model: the response is then explained by the intercept and the spatial Gaussian process alone, the baseline for asking how much of the surface is spatial structure and how much covariate effect, and the null model to compare a covariate model with incompare_models().- family
A model family accepted by
brms::brm(): a stats family function such aspoisson(), or a brms family object such asbrms::zero_inflated_poisson(),brms::negbinomial(),brms::hurdle_poisson(),brms::bernoulli()orbrms::Beta(). DefaultNULL, resolved tostats::gaussian(). The family reachesbrms::brm()unchanged with the spatial GP term still in the formula. A factor response is accepted only underbrms::categorical()or an ordinal family, and those fits have no single expected value per row, so several methods cannot use them; see "Non-Gaussian responses" for what each family supports, and the count example below.- gp_k
Positive integer giving the number of GP basis functions per dimension, or NULL (default) to derive it from the length-scale/domain ratio. The fitted model carries
gp_k^2basis functions, notgp_k(see "GP basis count and boundary factor"). A value above the derived one makes the basis finer, and the length-scale prior's lower tail moves down to the length-scale that basis resolves, because a finer basis under the default prior gains almost nothing. A value below the derived one leaves the prior where it was, mostly below what the basis resolves; that share is stored as$info$gp_adequacy$prior_mass_below, logged when it passes 10 percent and flagged byprint(). To ask for a resolution in CRS units, usegp_resolutionand leave thisNULL.- gp_c
Positive numeric boundary factor for the approximate GP, or NULL (default) to derive it alongside
gp_k. The boundary must be wide enough to contain the longest plausible effective range; a value that is too small truncates the domain and degrades the approximation for smooth, long-range surfaces. When you setgp_cand leavegp_k = NULL,gp_kis derived for your boundary: a wider boundary needs more basis functions to resolve the same length-scale, so raisinggp_craises the derivedgp_kwith it, up to the cap of 50 per dimension (a capped value is logged).- gp_iso
Logical; passed to
brms::gp(iso = ).FALSE(the default) fits a separate length-scale per coordinate axis, so the model learns any directional structure from the data.TRUEfits a single length-scale shared by both standardised axes, which makes the kernel anisotropic in the original CRS by the ratiosd(X)/sd(Y), because the coordinates are standardised per axis beforehand. See "Coordinate scaling and anisotropy".- prior
Optional brms prior specification. When NULL and
standardize_predictors = TRUE, a weakly informative prior is set on the regression coefficients, on the scale of the linear predictor:normal(0, 2.5 * sd(y))under an identity link (gaussian, student, skew-normal and mixtures of them),normal(0, 2.5 * sd(log(y)))for the lognormal families, whose location is on the log scale, and the fixednormal(0, 5)under any other link (log, logit and so on), where the linear predictor has a scale of its own.sd()is taken over the training rows. The result therefore does not depend on the units of the response. The prior brms used is stored as$info$b_priorand shown byprint(). Whenprioris given, no slope prior is added. A prior given here on a class that lives on the response's scale (b,Intercept,sigma,sdgp, andbetaofexgaussian()) keeps the response as it is; see "The response's centre and scale". A GP length-scale prior set from the data is added unlessprioralready contains an entry withclass = "lscale".- chains
Number of MCMC chains. Default 4.
- iter
Total iterations per chain. Default 2000.
- warmup
Warmup iterations. Default
floor(iter / 2).- cores
Number of cores for the sampler, one chain per core. Default
getOption("mc.cores", 1L), the convention brms uses itself, sooptions(mc.cores = 4)once per session runs the four default chains in parallel everywhere.- seed
Integer seed. Default 123.
- backend
"auto"(default),"cmdstanr"or"rstan"."auto"uses cmdstanr only when a CmdStan build is available, and rstan otherwise, which brms always brings. The cmdstanr package is a thin interface and can be installed without a CmdStan build (cmdstanr::install_cmdstan()builds one). An explicit"cmdstanr"with no usable CmdStan raises an error that says how to install it, before the sampler starts.- control
Named list of sampler controls, merged over the package defaults
list(adapt_delta = 0.99, max_treedepth = 12)rather than replacing them, solist(max_treedepth = 15)keepsadapt_delta = 0.99. See "Sampler settings".- compute_loo
Logical; compute PSIS-LOO. Default TRUE.
- standardize_predictors
Logical; centre and scale numeric predictors before fitting. Default FALSE. When TRUE, the centre and scale of each predictor are stored in
$info$predictor_scalingand applied again bypredict(). The model is then fitted on the standardised predictors, socoef()reports a slope per standard deviation of each predictor and an intercept at the predictor means, not the raw-unit valuesstats::lm()would give (see spatial_fit-coef).- check_convergence
Logical, default TRUE. After fitting, read the sampler's diagnostics and the GP basis against the posterior and the residuals, and set
$info$convergence_okand$info$gp_adequacy. See "Convergence checks" and "What the basis resolves".FALSEskips both, leavesconvergence_okNA(not checked) and sets the adequacy status to"not_checked".- pointize
How a feature that is not a point is reduced to one: one of
"auto"(default),"centroid","point_on_surface","surface","line_midpoint"or"bbox_center"; seecoerce_to_points().- boundary
Optional polygonal sf/sfc whose CRS the data are projected to. It is not a clip: rows outside it are kept.
- gp_resolution
The shortest effective range the basis should resolve, as a single positive number in the units of the data's CRS (metres for a UTM layer), or NULL (default) for the rule described under "GP basis count and boundary factor".
gp_kis derived from it, and the length-scale prior's lower tail moves with the basis. It can only refine: a value the default basis already resolves leaves the default basis in place. It is an error when the basis it needs exceeds the cap of 50 functions per dimension (2,500 in all); the message gives the basis size needed and the shortest range the cap reaches on this layout. Cost grows withgp_k^2. Givegp_resolutionorgp_k, not both.- .already_prepped
Internal; leave at the default.
Value
A bayesian_fit object (inherits from spatial_fit).
Supports predict(), fitted(), residuals(),
coef(), summary(), and model_metrics().
Model-specific metadata lives in $info (coords: the names of the
scaled coordinate columns handed to brms::gp(); coord_scaling,
predictor_scaling, gp_k, gp_c, gp_iso, gp_n_basis, gp_ell_min,
gp_resolution: the smallest effective range the basis resolves, as
c(x, y) in CRS units; gp_resolution_requested: the
gp_resolution argument, or NULL;
gp_prefit: the check made before sampling, a list with status
("ok"; "below_floor", the one that warns;
"below_floor_no_autocorrelation" and
"below_floor_long_range", a range below the floor that the
short-lag or the floor-distance test did not bear out;
"not_estimated" or "not_run"), range (the
estimated range in CRS units), floor, k_needed,
moran and moran_floor (the two Moran's I tests, each with
I, z and a one-sided p; NULL where the
test is not run, or where the residuals are the rounding of an exact
fit), reason and
unit;
gp_adequacy: a list with status (see "What the basis resolves"), frac_below
(the share of length-scale draws below gp_ell_min),
identified and identified_by ("spatial_share" or
"length_scale", the rule that decided it; see "What the basis resolves"),
contraction (one minus the ratio of posterior to prior variance,
per length-scale, negative when the posterior is the wider of the two)
and prior_gap (the largest gap between the posterior's and the
prior's distribution functions, per length-scale; both NA for a
length-scale prior this function did not set), spatial_share and
sdgp (2.5,
50 and 97.5 percent quantiles; the share only for a gaussian or lognormal
family), effective_range (the posterior effective range per axis
in CRS units, same quantiles), residual_moran (the test on the
residuals the status rests on: I, z, a one-sided p
and k, the number of neighbours; absent when it could not be
run, and residual_untested then says why), resolution,
unit and prior_mass_below;
b_prior: the slope prior brms used ("(flat)" for its default,
NA for a model with no slopes), and b_prior_source: where it came
from; predictor_levels: the levels each factor or character predictor
has in the training rows, which predict() holds new data to;
gp_S: the pooled centred range brms::gp(c = ) multiplies;
gp_cmeans: the column means brms centred the scaled coordinates on;
gp_xy_range: the training extrema of the scaled coordinates, which
predict() uses, with gp_S and gp_cmeans, to hold the GP boundary
at its fitted value;
gp_lengthscale_bounds: the c(lower, upper) the length-scale prior
was calibrated over; gp_lscale_prior: the length-scale prior
brms::validate_prior() reports the model will actually use,
which is not necessarily the one this function requested (several entries,
semicolon-separated, if brms resolved the axes differently); loo, looic,
convergence_ok (TRUE or FALSE, and NA when nothing
was checked, as under check_convergence = FALSE),
convergence_diagnostics: n_divergent, n_max_treedepth,
ebfmi (per chain), max_rhat, min_neff_ratio,
min_ess (the smallest bulk or tail effective sample size) and
ess_required (100 per chain), and rhat_failed /
neff_failed / ess_failed, the parameters that failed each
check by name with their values (R-hat, ESS ratio and ESS; empty when
none failed), which is what makes a failed check actionable,
rhat_caution, the parameters whose R-hat is between 1.01 and 1.05
with enough effective draws, which do not fail the verdict, plus
gp_lscale_below_resolution and gp_adequacy, the share and
status described under "What the basis resolves"; and 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));
response_scaling: the centre and scale the response was
handed to brms with, absent when it was handed over as it is (see "The
response's centre and scale").
The raw brmsfit is in $engine.
Details
The fitted length-scale is an estimate of how far the spatial dependence
reaches only when its posterior sits clear of both that floor and its
prior. $info$gp_adequacy says whether it does, and when it does
$info$gp_adequacy$effective_range holds the posterior effective range
per axis in CRS units (the raw lscale draws are in per-axis
standardised units and are not a distance).
Choose it over fit_gwr_model() when you want one global
relationship plus a spatial random field, with posterior intervals; choose
GWR when the question is how a coefficient varies across the map. Choose
fit_rf_model() when predictive accuracy matters more than an
interpretable model and the response is non-linear in the predictors. The
cost is time: this is full MCMC through brms and Stan, so a fit takes
minutes rather than seconds, and the basis size (gp_k) trades
fidelity against run time.
Sampler settings
adapt_delta defaults to 0.99, not Stan's 0.8, because one divergent
transition sets convergence_ok to FALSE (see "Convergence
checks") and lower values can leave a few on ordinary data. A lower
value, such as list(adapt_delta = 0.9), runs faster, since the
smaller step of 0.99 costs sampling time. Some divergent transitions can
remain at 0.99 too, for example on a layer whose spatial field is weak
against the noise; then raise it to 0.995 or 0.999, which costs more time
again.
Convergence checks
Under check_convergence = TRUE the verdict in
$info$convergence_ok follows Stan's own diagnostics, with these
thresholds:
any divergent transition after warmup;
bulk or tail effective sample size below 100 per chain for any parameter (Vehtari et al. 2021; the rule rstan warns on). It is an absolute count, not a share of the draws;
rank-normalised split R-hat, in two tiers. Above 1.05, the value rstan's own sampler warning uses, for any parameter. Above 1.01, the value Vehtari et al. (2021) recommend, for a parameter whose effective sample size is also below the count in the previous item, or cannot be read;
E-BFMI below 0.3 in any chain (Betancourt 2016).
An R-hat between 1.01 and 1.05 on a parameter with enough effective
draws is a caution, not a failure: it is stored by name in
$info$convergence_diagnostics$rhat_caution, logged, and counted
by print(). The model has one weight per basis function, about
540 parameters at the basis derived for points spread evenly over a
square, and among that many the largest R-hat sits near 1.01 in a fit
that has converged. Vehtari et al. give 1.01 beside an effective sample
size above 400, so the two are read together here.
Transitions that stop at max_treedepth are counted and logged but
do not change the verdict: Stan treats them as a cost, not as invalid
draws. A failed verdict sets convergence_ok to FALSE,
raises one R warning of class spatialkit_convergence naming each
failed check with its count and its first five parameters, and
print() flags it; $info$convergence_diagnostics holds every
value. The warning closes with the remedy for the checks that failed: a
higher adapt_delta for divergent transitions, which more
iterations do not remove, and more iterations for R-hat and effective
sample size. A short run usually fails on effective sample size.
cv_bayes() marks such folds
in fold_metrics$convergence_ok and compare_models()
names such a model.
The same step checks the GP basis against the posterior and the
residuals (see "What the basis resolves") and stores the result as
$info$gp_adequacy. The residuals need the fitted values, one
pass over the posterior that fitted() caches for later calls.
That check is about the approximation, not the sampler, so it does not
change convergence_ok; print() and summary() show
its status, and two of its states raise a warning of class
spatialkit_gp_adequacy.
GP basis count and boundary factor
brms::gp() builds a full tensor grid over its covariates, so a term
gp(..x, ..y, k = gp_k) carries gp_k^2 basis functions: the
gp_k argument is the count per dimension, not the total rank.
Both gp_k and gp_c are therefore chosen from the ratio of the
estimated length-scale to the domain extent, following
Riutort-Mayol et al. (2023): gp_c is set large enough to contain the
upper length-scale bound, and gp_k large enough to resolve the lower
one. The derived value depends on the layout, not on n: about 23
for points spread evenly over a square; other layouts give other values,
up to the cap of 50.
The domain extent used is the one brms::gp(c = ) itself multiplies:
the full pooled range of the column-centred coordinates
(brms:::choose_L(), taken over the unique coordinate rows,
because brms:::.data_gp() reduces the covariates to unique rows first
under the default gr = TRUE, so repeat visits to one location do not
widen the domain), not the per-axis half-range in which
Riutort-Mayol et al. state their inequalities. Both constraints are on
the boundary \(L = c \times S\), and stating them in brms's units keeps
gp_c, gp_k and $info$gp_ell_min describing the basis
brms builds. A
gp_c derived on the half-range convention and handed to
brms::gp() produces a boundary twice as wide as intended, against
which gp_k under-resolves by a factor of two.
The GP term is built with scale = FALSE. brms::gp() otherwise
rescales its covariates so the maximum Euclidean distance between two points
is 1, and reports lscale in that space; since this function already
standardises the coordinates, and the length-scale prior, gp_c and the
adequacy check below are all expressed in those standardised units, a second
normalisation would leave every length-scale quantity in the wrong units.
What the basis resolves
The smallest length-scale the chosen basis can resolve is
1.75 * gp_c * S / gp_k, stored in standardised units as
$info$gp_ell_min. As an effective range (the distance at which the
squared-exponential correlation has fallen to 5 percent, 2.45 length-scales)
and in CRS units it is $info$gp_resolution, one value per axis
because each coordinate is divided by its own standard deviation. The
floor is soft: the basis keeps 99 percent of a process's variance at the
floor, 69 percent at half of it and 41 percent at a third. The default
length-scale prior is what makes it bind, with 1 percent of its mass below
the floor and about one part in a hundred million below half of it.
Three checks hold the basis against the data.
Before anything is compiled, the autocorrelation range of the response (of its OLS residuals when there are predictors) is estimated with
estimate_sac_range()and compared with the coarser axis's floor. That range is a variogram estimate and can be wrong in both directions, so a range below the floor raises a warning only when two other things agree with it. The same variable is autocorrelated at short range (Moran's I over 4 nearest neighbours, one-sided, at 5 percent): a variogram fitted to a response with no spatial structure can still return a short range, thoughestimate_sac_range()refuses most such layers itself. And it is no longer autocorrelated at the floor's distance (Moran's I over the pairs 0.75 to 1.25 floors apart is not both above 0.05, the correlation that defines an effective range, and significant at 5 percent): a variogram can also return a short range for a surface that is smooth over long distances. The warning has classspatialkit_gp_resolution, gives both numbers and the basis size that would resolve the range, says that it is an estimate which the check after sampling tests against the residuals of the fitted model, and says when the basis size is past the cap or past the number of rows, where kriging is the better tool if the range is right. A short range the floor-distance test contradicts is logged and shown byprint()without a warning: it can still mean short-range structure beside a longer one, which the basis counts as noise. Nothing before sampling separates the two; the residuals after it do (the third check). A range that cannot be estimated is logged with the reason and shown byprint(); the result is in$info$gp_prefit. An exponential field has structure at every scale, so the warning on one is not plainly wrong.Also before sampling, the share of the length-scale prior below the floor is computed (
$info$gp_adequacy$prior_mass_below). A derived basis keeps it near 0.01; a smallgp_kdoes not, and a share above 0.10 is logged and flagged byprint().After sampling, under
check_convergence = TRUE, the posterior and the residuals are read. The posterior says whether the Gaussian process carries a share of the variance and where its length-scale sits against the floor. It cannot say what the surface left behind, so the residuals are tested for autocorrelation at short range in every fit (Moran's I over 4 nearest neighbours, one-sided, at 5 percent;$info$gp_adequacy$residual_moran).$info$gp_adequacy$statusis one of:"ok"The Gaussian process carries a share of the variance, its length-scale is clear of the floor, and the residuals show no autocorrelation at short range. A surface smoother than the prior expects (a plane, a range longer than the extent) is
"ok": its length-scale posterior sits on the long side of the prior and is wider than it."below_resolution"The Gaussian process carries a share of the variance and more than 10 percent of the length-scale draws fall below the floor. The 10 percent trigger is this package's operationalisation of the check Riutort-Mayol et al. recommend, not a figure from the paper.
"unresolved_short_range"The residuals are autocorrelated at short range: the signature of structure finer than the basis, counted as noise. It is reached two ways, and
$info$gp_adequacy$identifiedsays which. The Gaussian process carries no variance that can be told from zero (FALSE): all of the structure is below the floor. Or it carries a share and its length-scale is clear of the floor (TRUE): it fitted a surface, and finer structure sits beside it, as with a regional trend plus short-range structure."no_signal_above_floor"The Gaussian process carries no variance that can be told from zero, and the residuals show nothing left over. A response with no spatial structure gives this, so it is not a failure by itself.
"not_checked"check_convergence = FALSE.
The second and third raise a warning of class
spatialkit_gp_adequacy; the fourth is logged. When the residuals cannot be tested (an ordinal or categorical family has no residual per row; a posterior that cannot be drawn), the status rests on the posterior alone, a line is logged, the reason is in$info$gp_adequacy$residual_untested, andprint()keeps its flag on a variogram range that was below the floor.On a fit with nothing left over the test is conservative, because the surface takes up part of the noise and leaves the residuals slightly negatively autocorrelated. It is not sharp just below the floor, where the length-scale draws report the structure (
"below_resolution"). An exponential field has structure at every scale and can be reported with a range above the floor. The 5 percent level is the usual one and is not tuned; with many rows a small leftover autocorrelation is significant, so read the size of I beside its p."No variance that can be told from zero" is decided on the Gaussian process's share of the variance,
sdgp^2 / (sdgp^2 + sigma^2): its 2.5 percent quantile is under 0.01. It does not mark off a response whose structure is all below the floor: such a process can still carry a share, and the residual test reports it. The share exists for a gaussian or lognormal family. For any other family the length-scales decide instead: the process is not identified when on every axis the posterior kept more than three quarters of its prior's variance and the largest gap between its distribution function and the prior's is under 0.30.$info$gp_adequacy$identified_bysays which rule was used. The width of the length-scale posterior does not decide by itself, because a posterior that moved to longer length-scales is wider than its prior; and the share of draws below the floor cannot detect an unidentified process, because a posterior the data did not move puts 1 percent below the floor, the same as the prior.
A response whose range is below the floor needs a finer basis and a prior
that allows the shorter length-scale, both of which gp_resolution
sets, up to the cap. Past the cap this model cannot resolve the range,
and kriging, which has no such floor, is the better tool; see
kriging_adequacy() for cell means.
Coordinate scaling and anisotropy
Before fitting the GP, X and Y coordinates are each centred and divided by their own standard deviation. This is a conditioning step: easting and northing frequently span very different ranges in a projected CRS, and handing Stan raw metres samples poorly.
Because the axes are scaled independently, a single shared
length-scale in the scaled space corresponds to an anisotropic kernel in the
original CRS, stretched by the ratio sd(X)/sd(Y). That ratio is a
property of how the sampling locations are laid out, not of the process
being modelled.
gp_iso = FALSE (the default) therefore fits one length-scale per
axis, letting the model estimate directional structure from the data instead
of inheriting it from the standardisation. Set gp_iso = TRUE for
one length-scale shared by both standardised axes.
gp_iso does not affect cost: brms::gp() builds a
tensor grid either way, so the model carries gp_k^2 basis functions
regardless. The stored $info$coord_scaling list records the scaling
strategy, and $info$gp_iso records which kernel was used.
Warnings
Every warning this function raises carries a condition class, so a caller can catch or muffle exactly one of them by name:
spatialkit_rows_dropped,spatialkit_constant_predictorFrom
prep_model_data(): incomplete rows were dropped, with the counts; a predictor takes one value in every row kept.spatialkit_response_scaleThe response lies far from zero or its standard deviation far from 1, and
priorsets a prior on a class on the response's scale, so the response is handed to brms as it is; see "The response's centre and scale".spatialkit_gp_basis_sizeFewer than one row per ten basis functions.
spatialkit_gp_resolutionA variogram fitted before compiling puts the response's range below what the basis resolves, and the autocorrelation of the response agrees. An estimate; the check after sampling tests it against the residuals of the fitted model.
spatialkit_convergenceThe sampler's diagnostics fail.
spatialkit_gp_adequacyThe basis is too coarse for the data: the posterior asks for a shorter length-scale than it resolves (
"below_resolution"), or the residuals are autocorrelated at short range ("unresolved_short_range").
A response that takes a single value is an error, raised before anything
is compiled, and so is one whose values differ only by rounding (1e15 and
the next double). A fit that comes back from brms with no posterior
draws, as when Stan rejects every starting value, is an error that names
the response's size as brms was given it. The convergence warning
carries the checks that failed as
failed ("divergent", "ebfmi", "rhat",
"ess"). cv_bayes() fits once per fold; it collects
the last four classes from its folds and raises each once for the run,
naming the folds, and cv_spatial() does the same for a
fit_fn that calls this function.
The response's centre and scale
Stan starts every parameter between -2 and 2, and brms sets its default
priors for the intercept, the residual standard deviation and the
Gaussian process's standard deviation from the response it is given, with
scales of at least 2.5 in its units. A response at 1e8 plus a spread of 1,
or in units of 1e-20, lies far from both, and brms can miss the data by
orders of magnitude. So under the gaussian, student, skew_normal,
exgaussian and asym_laplace families with an identity link, a response
whose centre is more than 1,000 times its spread from zero is handed to
brms less that centre, and one whose standard deviation lies outside
\(2^{-20}\) to \(2^{20}\) is divided by the power of two nearest that
standard deviation. Under exgaussian and asym_laplace the rule is
narrower: a centre more than 4 times the spread from zero is taken off,
and a standard deviation outside \(2^{-2}\) to \(2^{2}\) is divided
out, because brms's default prior on exgaussian's beta and Stan's
starting values do not follow the response. Both steps are exact, and the model is the same
model of the response: the shift moves the location only, and the scale
multiplies the location, sigma and the mean beta of
exgaussian's exponential part, and leaves the degrees of freedom of
student, the skewness of skew_normal and the quantile of asym_laplace as
they are. Every other response, and every response under another
family, is handed over as it is.
fitted(), predict() and its draws, residuals(),
coef(), $info$loo, $info$looic and
$info$gp_adequacy$sdgp are put back in the response's units, and
$info$b_prior gives the automatic slope prior in those units. The
same data from another origin or in other units then give the same fit,
up to Monte Carlo error. The centre and scale are in
$info$response_scaling. $engine is the fit of the response
brms was given, so brms's own functions on it (brms::fixef(),
brms::posterior_epred()) answer on that scale.
A prior given in prior on a class on the response's scale
(b, Intercept, sigma, sdgp, and beta
of exgaussian) is read by brms on the response it is given. With such a
prior the response is handed over as it is, and the warning
spatialkit_response_scale says so.
Non-Gaussian responses
Nothing in this function is Gaussian-specific except its default. A numeric count, binary (0/1 or logical) or bounded response passes through to brms under the family you name, with the GP term in the formula and the length-scale prior attached to each distributional parameter's GP.
The response check is family-aware. A factor or character response is
accepted only under brms::categorical() or an ordinal family
(cumulative, sratio, cratio, acat), and refused
under every other family before anything is compiled; under gaussian a
logical response is refused too. The case to watch is a two-level factor
under brms::bernoulli(): brms would fit it, but
residuals(), summary(), model_metrics() and
cv_bayes() could not score a factor, so convert it to 0/1
first.
An ordinal or categorical fit has a probability per response category, not
one expected value per row. predict() with its default
type = "epred", fitted(), residuals(),
summary() and model_metrics() therefore stop with a message
saying so, and cv_bayes() refuses the family before fitting
anything. predict(type = "predict", draws = TRUE) returns the
posterior predicted categories, as category indices, for new rows as well
as the training ones (the share of draws in each category estimates its
probability), and brms::posterior_epred(fit$engine) the
probabilities for the training rows.
For the numeric families two things follow. First, the metrics that come
back from model_metrics() and the cv_*() functions are
not all meaningful for such a response: RMSE and MAE are, MAPE, SMAPE and R-squared
are Gaussian-shaped, and for this backend cv_bayes()'s CRPS
and interval coverage are the proper scores to read. See
model_metrics(), section "Which metrics survive a
non-Gaussian response". Second, estimate_sac_range() fits
a variogram to the raw response (or OLS residuals), whose variance tracks
its mean for a count; the range it reports is then less trustworthy than
for a Gaussian response, and its help page says how.
The response check reads the family's name through brms's own accessor. If brms cannot name the family object, the check is skipped, and a wrong response type surfaces as a Stan error with no message from this function.
Spatial confounding
A fixed-effect coefficient estimated alongside a spatial random effect is a
different quantity from the same coefficient in a non-spatial fit. When a
covariate is itself spatially smooth, the GP term absorbs part of its
effect and the two estimates can disagree sharply; when the response is
smoother than the covariate, the estimate can shrink toward zero regardless
of the true effect (Bolin and Wallin 2026). Under a correctly specified
spatial model this is not a bias but a change of estimand (Zimmerman and
Ver Hoef 2022): the spatial coefficient is the effect net of whatever
the spatial field can explain, and the non-spatial one is not. The right
one depends on the question, so report both side by side, unadjusted: fit
the same formula with stats::lm() or stats::glm() and
compare. Compare like
with like: under standardize_predictors = TRUE the coefficients here
are per standard deviation of each predictor, so either fit the
non-spatial model on the same standardised columns or divide these slopes
by $info$predictor_scaling[[name]]$scale first (see
spatial_fit-coef).
Published work on remedies is unsettled, and this function takes no side. Restricted spatial regression (Hughes and Haran 2013) projects the spatial effect off the covariate space; later work argues it does not deliver what it promises (Hanks et al. 2015; Khan and Calder 2022). Within this backend, modelling the covariate and the spatial field as explicitly correlated (Marques, Kneib and Klein 2022) is expressible in a brms formula with no new code, and a spectral adjustment (Guan et al. 2023) is the principled route that suits a Hilbert-space basis; this function does not implement it.
References
Betancourt, M. (2016). Diagnosing suboptimal cotangent disintegrations in Hamiltonian Monte Carlo. arXiv:1604.00695.
Vehtari, A., Gelman, A., Simpson, D., Carpenter, B. and Burkner, P.-C. (2021). Rank-normalization, folding, and localization: an improved R-hat for assessing convergence of MCMC (with discussion). Bayesian Analysis 16, 667–718. doi:10.1214/20-BA1221
Riutort-Mayol, G., Burkner, P.-C., Andersen, M. R., Solin, A. and Vehtari, A. (2023). Practical Hilbert space approximate Bayesian Gaussian processes for probabilistic programming. Statistics and Computing 33, 17. doi:10.1007/s11222-022-10167-2
Bolin, D. and Wallin, J. (2026). Spatial self-confounding: smoothness-related estimation bias in spatial regression models. Biometrika 113(1), asaf076. doi:10.1093/biomet/asaf076
Guan, Y., Page, G. L., Reich, B. J., Ventrucci, M. and Yang, S. (2023). Spectral adjustment for spatial confounding. Biometrika 110, 699–719. doi:10.1093/biomet/asac069
Hanks, E. M., Schliep, E. M., Hooten, M. B. and Hoeting, J. A. (2015). Restricted spatial regression in practice: geostatistical models, confounding, and robustness under model misspecification. Environmetrics 26, 243–254. doi:10.1002/env.2331
Hughes, J. and Haran, M. (2013). Dimension reduction and alleviation of confounding for spatial generalized linear mixed models. Journal of the Royal Statistical Society: Series B 75, 139–159. doi:10.1111/j.1467-9868.2012.01041.x
Khan, K. and Calder, C. A. (2022). Restricted spatial regression methods: implications for inference. Journal of the American Statistical Association 117, 482–494. doi:10.1080/01621459.2020.1788949
Marques, I., Kneib, T. and Klein, N. (2022). Mitigating spatial confounding by explicitly correlating Gaussian random fields. Environmetrics 33, e2727. doi:10.1002/env.2727
Zimmerman, D. L. and Ver Hoef, J. M. (2022). On deconfounding spatial confounding in linear models. The American Statistician 76, 159–167. doi:10.1080/00031305.2021.1946149
See also
cv_bayes() to score the fit on spatial folds;
predict() (spatial_fit-predict) and coef()
(spatial_fit-coef); gp_lengthscale_bounds() for the
length-scale range the prior is set over.
Other model fitting:
fit_gwr_model(),
fit_rf_model(),
gp_lengthscale_bounds(),
new_spatial_fit()
Examples
if (FALSE) { # \dontrun{
# Not run: fits with Stan, which needs a working C++ toolchain and takes
# minutes of sampling.
if (requireNamespace("brms", quietly = TRUE)) {
library(sf)
set.seed(1)
n <- 60
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
)
dat$price <- 10 + 0.01 * (st_coordinates(dat)[, 1] - 5e5) +
2 * dat$elev + rnorm(n)
# Two short chains keep this to a few minutes; Stan may warn about
# effective sample size, which is the cost of that. Use its defaults
# (chains = 4, iter = 2000) for a fit to report.
fit <- fit_bayesian_spatial_model(dat, "price", "elev",
chains = 2, iter = 1000,
compute_loo = FALSE)
print(summary(fit))
head(predict(fit, newdata = dat))
# A zero-inflated count. The family is the only thing that changes.
# summary()'s R2 and MAPE assume a Gaussian response, so for a count
# read the coefficients here and score the model with cv_bayes(), whose
# CRPS and interval coverage are defined for any response.
dat$count <- rpois(n, exp(0.5 + 0.8 * dat$elev)) * rbinom(n, 1, 0.7)
fit_zip <- fit_bayesian_spatial_model(dat, "count", "elev",
family = brms::zero_inflated_poisson(),
chains = 2, iter = 1000,
compute_loo = FALSE)
coef(fit_zip)
}
} # }