Package {BMEmapping}

Type:	Package
Title:	Spatial Interpolation using Bayesian Maximum Entropy (BME)
Version:	2.0.0
Maintainer:	Kinspride Duah <kinspride2020@gmail.com>
Description:	Provides an accessible and robust implementation of core BME methodologies for spatial prediction. It enables the systematic integration of heterogeneous data sources including both hard data (precise measurements) and soft interval data (bounded or uncertain observations) while incorporating prior knowledge and supporting variogram-based spatial modeling. The BME methodology is described in Christakos (1990) <doi:10.1007/BF00890661>, Serre and Christakos (1999) <doi:10.1007/s004770050029> and Duah (2025, 2026) <doi:10.1016/j.spasta.2026.100974>.
License:	MIT + file LICENSE
Encoding:	UTF-8
LazyData:	true
URL:	https://github.com/KinsprideDuah/BMEmapping
BugReports:	https://github.com/KinsprideDuah/BMEmapping/issues
RoxygenNote:	7.3.3
Suggests:	dplyr, knitr, rmarkdown, scales, testthat (≥ 3.0.0), tidyr
Config/testthat/edition:	3
Imports:	ggplot2, gridExtra, gstat, sf, mvtnorm, stats
Depends:	R (≥ 3.5)
VignetteBuilder:	knitr
Config/Needs/website:	rmarkdown
NeedsCompilation:	no
Packaged:	2026-07-12 19:49:21 UTC; kwaku
Author:	Kinspride Duah [aut, cre, cph], Yan Sun [aut]
Repository:	CRAN
Date/Publication:	2026-07-13 07:10:32 UTC

Leave-one-out cross validation (LOOCV) at hard data locations.

Description

bme_cv performs cross-validation to evaluate the predictive performance of the Bayesian Maximum Entropy (BME) spatial interpolation method using both hard and soft (interval) data. The function supports both leave-one-out cross-validation (LOOCV) and K-fold cross-validation, depending on the value of k. If k equals the number of hard data locations, LOOCV is performed by removing one hard observation at a time and predicting it using the remaining hard and all soft data. If k is less than the number of hard data locations, the hard data are randomly partitioned into k folds, with each fold used once as the validation set while the remaining folds are used for prediction. Depending on the type argument, predictions are returned as posterior means, posterior modes, or posterior medians.

This function is useful for validating the BME interpolation method and tuning variogram parameters.

Usage

bme_cv(data_object, model, nugget, sill, range,
              nsmax = 5, nhmax = 5, n = 50,
              zk_range = extended_range(data_object), type,
              k = 5)

Arguments

Value

A data frame containing the coordinates of the hard data locations, the observed values, the corresponding BME predictions (posterior mean, mode, or median, depending on type), the posterior variance (when type = "mean"), the prediction residuals, and the cross-validation fold indices.

Examples

data("utsnowload")
ch <- utsnowload[2:10, c("latitude", "longitude")]
cs <- utsnowload[68:232, c("latitude", "longitude")]
zh <- utsnowload[2:10, c("hard")]
a <- utsnowload[68:232, c("lower")]
b <- utsnowload[68:232, c("upper")]
data_object <- bme_map(ch, cs, zh, a, b)
bme_cv(data_object,
  model = "exp", nugget = 0.0953, sill = 0.3639,
  range = 1.0787, type = "mean", k = 5
)

Create BMEmapping object

Description

Function that creates BMEmapping objects; objects that hold all the data information necessary for BME interpolation.

Usage

bme_map(ch, cs, zh, a, b)

Arguments

Value

A list containing the input arguments ch, cs, zh, a, and b, with class "BMEmapping".

Examples

ch <- matrix(c(1, 2, 3, 4), ncol = 2)
cs <- matrix(c(5, 6, 7, 8), ncol = 2)
zh <- c(10, 20)
a <- c(8, 9)
b <- c(12, 13)
obj <- bme_map(ch, cs, zh, a, b)
class(obj) # "BMEmapping"

BME prediction

Description

bme_predict performs BME spatial interpolation at user-specified estimation locations. It uses both hard data (precise measurements) and soft data (interval or uncertain measurements), along with a specified variogram model, to compute either the posterior mean (and its associated variance), mode or median for each location. This function enables spatial prediction in settings where uncertainty in data must be explicitly accounted for, improving estimation accuracy when soft data is available.

Usage

bme_predict(x, data_object, model, nugget, sill, range,
                   nsmax = 5, nhmax = 5, n = 50,
                   zk_range = extended_range(data_object), type)

Arguments

Value

A data frame with either 3 or 4 columns, depending on the prediction type. The first two columns contain the geographic coordinates. If type = "mean", the third and fourth columns represent the posterior mean and its associated variance, respectively. If type = "mode" or "median", only a third column is returned for the posterior mode or median.

Examples

data("utsnowload")
x <- utsnowload[1:3, c("latitude", "longitude")]
ch <- utsnowload[6:67, c("latitude", "longitude")]
cs <- utsnowload[68:232, c("latitude", "longitude")]
zh <- utsnowload[6:67, c("hard")]
a <- utsnowload[68:232, c("lower")]
b <- utsnowload[68:232, c("upper")]
data_object <- bme_map(ch, cs, zh, a, b)
bme_predict(x, data_object,
  model = "exp", nugget = 0.0953,
  sill = 0.3639, range = 1.0787, type = "mean"
)

BME credible interval

Description

bme_predict_ci computes posterior credible intervals for each estimation location at a user-specified credibility level. The function explicitly incorporates uncertainty in the available data, providing interval estimates that quantify the uncertainty associated with BME spatial predictions.

Usage

bme_predict_ci(x, data_object, model, nugget, sill, range,
                      nsmax = 5, nhmax = 5, n = 50,
                      zk_range = extended_range(data_object), level)

Arguments

Value

A data frame whose first two columns contain the geographic coordinates of the estimation locations. The remaining two columns contain the lower and upper bounds of the posterior credible interval corresponding to the specified level. For example, if level = 0.90, the returned bounds represent the 90% posterior credible interval.

Examples

data("utsnowload")
x <- utsnowload[1:3, c("latitude", "longitude")]
ch <- utsnowload[5:67, c("latitude", "longitude")]
cs <- utsnowload[68:232, c("latitude", "longitude")]
zh <- utsnowload[5:67, c("hard")]
a <- utsnowload[68:232, c("lower")]
b <- utsnowload[68:232, c("upper")]
data_object <- bme_map(ch, cs, zh, a, b)
bme_predict_ci(x, data_object,
  model = "exp", nugget = 0.0953,
  sill = 0.3639, range = 1.0787, level = 0.90
)

California Snow Load Data

Description

A subset of data from the 7964 measurement locations included in the 2020 National Snow Load Study. This data is basically on reliability-targeted snow loads (RTSL) in the state of California.

Usage

casnowload

Format

A data frame with 346 rows and 8 columns.

STATION

Name of the snow measuring station

LATITUDE

Latitude coordinate position

LONGITUDE

Longitude coordinate position

ELEVATION

Elevation of the measring station (measured in meters)

RTSL

The hard data RTSL value

LOWER

The lower endpoint RTSL

UPPER

The upper endpoint RTSL

TYPE

Type of snow measurement, WESD is direct and SNWD is indirect measurement. Direct measurements are hard data and have the lower, upper and center values are the same. Indirect measurements have LOWER < RTSL < UPPER.

Source

https://www.ncei.noaa.gov/pub/data/ghcn/daily/

Computes an extended numeric range that includes all elements from three numeric vectors: x, y, z. The range is extended by 10\ range on both sides

Description

Computes an extended numeric range that includes all elements from three numeric vectors: x, y, z. The range is extended by 10\ range on both sides

Usage

extended_range(x)

Plot Method for BMEmapping Objects

Description

Generates graphical displays for objects of class "BMEmapping". The output depends on the object type:

• Objects returned by bme_map() produce a spatial plot showing hard and soft data locations.

• Objects returned by prob_zk() produce posterior density plots.

• Objects returned by bme_predict() or bme_interval() produce spatial prediction maps.

• Objects returned by bme_cv() produce diagnostic plots for evaluating prediction performance.

Usage

## S3 method for class 'BMEmapping'
plot(x, ...)

Arguments

Value

A ggplot2 object or an arranged collection of plots, returned invisibly.

Posterior Density Estimation at a Single Location

Description

Computes the posterior and plots probability density function (PDF) at a single unobserved spatial location using the Bayesian Maximum Entropy (BME) framework. This function integrates both hard data (precise measurements) and soft data (interval or uncertain observations), together with a specified variogram model, to numerically estimate the posterior density across a range of possible values.

Usage

prob_zk(x, data_object, model, nugget, sill, range,
               nsmax = 5, nhmax = 5, n = 50,
               zk_range = extended_range(data_object))

Arguments

Value

A data frame with two columns: zk_i (assumed zk values) and prob_zk_i (corresponding posterior densities).

Examples

data("utsnowload")
x <- utsnowload[1, c("latitude", "longitude")]
ch <- utsnowload[2:67, c("latitude", "longitude")]
cs <- utsnowload[68:232, c("latitude", "longitude")]
zh <- utsnowload[2:67, "hard"]
a <- utsnowload[68:232, "lower"]
b <- utsnowload[68:232, "upper"]
data_object <- bme_map(ch, cs, zh, a, b)
prob_zk(x, data_object,
  model = "exp",
  nugget = 0.0953, sill = 0.3639, range = 1.0787
)

Leave-one-out cross validation (LOOCV) at hard data locations using the random quantile approach.

Description

bme_cv performs cross-validation to evaluate the predictive performance of the Bayesian Maximum Entropy (BME) spatial interpolation method using both hard and soft (interval) data. The function supports both leave-one-out cross-validation (LOOCV) and K-fold cross-validation, depending on the value of k. If k equals the number of hard data locations, LOOCV is performed by removing one hard observation at a time and predicting it using the remaining hard and all soft data. If k is less than the number of hard data locations, the hard data are randomly partitioned into k folds, with each fold used once as the validation set while the remaining folds are used for prediction. Depending on the type argument, predictions are returned as posterior means, posterior modes, or posterior medians.

This function is useful for validating the BME interpolation method and tuning variogram parameters.

Usage

q_bme_cv(data_object, nsmax = 5, nhmax = 5, n = 50, nq = 3,
              zk_range = extended_range(data_object), type,
              k = 5)

Arguments

Value

A data frame containing the coordinates of the hard data locations, the observed values, the corresponding BME predictions (posterior mean, mode, or median, depending on type), the posterior variance (when type = "mean"), the prediction residuals, and the cross-validation fold indices.

Examples

data("utsnowload")
ch <- utsnowload[2:10, c("latitude", "longitude")]
cs <- utsnowload[68:232, c("latitude", "longitude")]
zh <- utsnowload[2:10, c("hard")]
a <- utsnowload[68:232, c("lower")]
b <- utsnowload[68:232, c("upper")]
data_object <- bme_map(ch, cs, zh, a, b)
q_bme_cv(data_object, type = "mean", k = 5)

BME prediction using the random quantile approach

Description

bme_predict performs BME spatial interpolation at user-specified estimation locations. It uses both hard data (precise measurements) and soft data (interval or uncertain measurements), along with a specified variogram model, to compute either the posterior mean (and its associated variance), mode or median for each location. This function enables spatial prediction in settings where uncertainty in data must be explicitly accounted for, improving estimation accuracy when soft data is available.

Usage

q_bme_predict(x, data_object, nsmax = 5, nhmax = 5, n = 50, nq = 3,
                   zk_range = extended_range(data_object), type)

Arguments

Value

A data frame with either 3 or 4 columns, depending on the prediction type. The first two columns contain the geographic coordinates. If type = "mean", the third and fourth columns represent the posterior mean and its associated variance, respectively. If type = "mode" or "median", only a third column is returned for the posterior mode or median.

Examples

data("utsnowload")
x <- utsnowload[1:3, c("latitude", "longitude")]
ch <- utsnowload[6:67, c("latitude", "longitude")]
cs <- utsnowload[68:232, c("latitude", "longitude")]
zh <- utsnowload[6:67, c("hard")]
a <- utsnowload[68:232, c("lower")]
b <- utsnowload[68:232, c("upper")]
data_object <- bme_map(ch, cs, zh, a, b)
q_bme_predict(x, data_object, type = "mean")

BME credible interval

Description

bme_predict_ci computes posterior credible intervals for each estimation location at a user-specified credibility level using the random quantile approach. The function explicitly incorporates uncertainty in the available data, providing interval estimates that quantify the uncertainty associated with BME spatial predictions.

Usage

q_bme_predict_ci(x, data_object, nsmax = 5, nhmax = 5,n = 50, nq = 3,
                        zk_range = extended_range(data_object), level)

Arguments

Value

A data frame whose first two columns contain the geographic coordinates of the estimation locations. The remaining two columns contain the lower and upper bounds of the posterior credible interval corresponding to the specified level. For example, if level = 0.90, the returned bounds represent the 90% posterior credible interval.

Examples

data("utsnowload")
x <- utsnowload[1:3, c("latitude", "longitude")]
ch <- utsnowload[5:67, c("latitude", "longitude")]
cs <- utsnowload[68:232, c("latitude", "longitude")]
zh <- utsnowload[5:67, c("hard")]
a <- utsnowload[68:232, c("lower")]
b <- utsnowload[68:232, c("upper")]
data_object <- bme_map(ch, cs, zh, a, b)
q_bme_predict_ci(x, data_object, level = 0.90)

Posterior Density Estimation at a Single Location

Description

Computes the posterior and plots probability density function (PDF) at a single unobserved spatial location using the Bayesian Maximum Entropy (BME) framework. This function integrates both hard data (precise measurements) and soft data (interval or uncertain observations), together with a specified variogram model, to numerically estimate the posterior density across a range of possible values.

Usage

q_prob_zk(x, data_object, nsmax = 5, nhmax = 5, n = 50, nq = 3,
                 zk_range = extended_range(data_object))

Arguments

Value

A data frame with two columns: zk_i (assumed zk values) and prob_zk_i (corresponding posterior densities).

Examples

data("utsnowload")
x <- utsnowload[1, c("latitude", "longitude")]
ch <- utsnowload[2:67, c("latitude", "longitude")]
cs <- utsnowload[68:232, c("latitude", "longitude")]
zh <- utsnowload[2:67, "hard"]
a <- utsnowload[68:232, "lower"]
b <- utsnowload[68:232, "upper"]
data_object <- bme_map(ch, cs, zh, a, b)
q_prob_zk(x, data_object)

Summary Method for BME Cross-Validation Results

Description

Provides a concise summary of LOOCV performance for BME predictions at hard data locations. Computes standard residual-based accuracy metrics, including Mean Error (ME), Mean Absolute Error (MAE), and Root Mean Squared Error (RMSE).

Usage

## S3 method for class 'BMEmapping'
summary(object, ...)

Arguments

Value

A data frame containing three columns:

ME

Mean Error (average residual).

MAE

Mean Absolute Error.

RMSE

Root Mean Squared Error.

A detrended reliability-targeted design ground snow loads in Utah

Description

This dataset contains detrended reliability-targeted design ground snow load measurements from 232 locations in state of Utah. Of these, 65 sites report precise measurements, treated as hard data, while the remaining 167 sites report imprecise measurements, represented as interval (soft) data. The dataset is structured such that the first 67 rows contain hard (point) measurements, and the remaining rows represent soft data using lower and upper interval bounds. For a detailed explanation of the dataset and its use, refer to the related version described in Duah et al. (2025) https://doi.org/10.1016/j.spasta.2025.100894

Usage

utsnowload

Format

A data frame with 232 rows and 5 variables:

latitude

Latitude coordinate position

longitude

Longitude coordinate position

hard

The hard data value

lower

The lower endpoint of the soft-interval

upper

The upper endpoint of the soft-interval

Source

doi:10.1016/j.spasta.2025.100894