remap {remap}

Build separate models for mapping multiple regions.

Description

Separate models are built for each given region and combined into one S3 object that can be used to predict on new data using generic function predict().

Usage

remap(
  data,
  regions,
  region_id,
  model_function,
  buffer,
  min_n = 1,
  distances,
  cores = 1,
  progress = FALSE,
  ...
)

Arguments

data

An sf data frame with point geometry.

regions

An sf dataframe with polygon or multipolygon geometry.

region_id

Optional name of column in 'regions' that contains the id that each region belongs to (no quotes). If null, it will be assumed that each row of 'regions' is its own region.

model_function

A function that can take a subset of 'data' and output a model that can be used to predict new values when passed to generic function predict().

buffer

The length of the buffer zone around each region in km where observations are included in the data used to build models for each region. (Can be a named vector with different values for each unique 'region_id' in 'region'.)

min_n

The minimum number of observations to use when building a model. If there are not enough observations in the region and buffer, then the closest min_n observations are used. min_n must be at least 1.

distances

An optional matrix of distances between 'data' and 'regions' generated by redist() function (calculated internally if not provided). Note that unless you know that you have min_n within a certain distance, no max_dist parameter should be used in redist().

cores

Number of cores for parallel computing. 'cores' above default of 1 will require more memory.

progress

If true, a text progress bar is printed to the console. (Progress bar only appears if 'cores' = 1.)

...

Extra arguments to pass to 'model_function' function.

Details

If a model fails for a region, a warning is given but the modeling process will continue.

A description of the methodology can be found in Wagstaff and Bean (2023) "remap: Regionalized Models with Spatially Smooth Predictions" <doi:10.32614/RJ-2023-004>.

Value

A remap S3 object containing:

models

A list of models containing a model output by 'model_function' for each region.

regions

'regions' object passed to the function (used for prediction). The first column is 'region_id' or the row number of 'regions' if 'region_id is missing. The second column is the region geometry.

call

Shows the parameters that were passed to the function.

See Also

predict.remap - used for predicting on new data. redist - used for pre-computing distances.

Examples

library(remap)
data(utsnow)
data(utws)

# We will keep these examples simple by only modeling non-zero values of
# snow water equivalent (WESD)

utsnz <- utsnow[utsnow$WESD > 0, ]

# Build a remap model with lm that has formula WESD ~ ELEVATION
# The buffer to collect data around each region is 30km
# The minimum number of observations per region is 10
remap_model <- remap(data = utsnz,
                     regions = utws,
                     region_id = HUC2,
                     model_function = lm,
                     formula = log(WESD) ~ ELEVATION,
                     buffer = 20,
                     min_n = 10,
                     progress = TRUE)

# Resubstitution predictions
remap_preds <- exp(predict(remap_model, utsnz, smooth = 10))
head(remap_preds)