bulkshift: Sonar backscatter bulk shift

In benjaminmisiuk/bulkshift: Backscatter raster harmonization for seabed mapping in R

Sonar backscatter bulk shift

Description

Relative calibration of two partially overlapping sonar backscatter datasets using the methods presented in Misiuk et al. (2020). This is largely a wrapper for the terra package to facilitate relative calibration of backscatter rasters. Supports several modelling methods and optionally, spatially explicit subsampling and validation.

Usage

bulkshift(
  shift,
  target,
  preds = NULL,
  model = "glm",
  model_params = list(),
  mosaic = FALSE,
  mosaicmethod = "bilinear",
  savedata = TRUE,
  sample = NULL,
  samplemethods = "uniform",
  crossvalidate = NULL,
  ...
)

Arguments

shift	SpatRaster. Backscatter dataset undergoing correction.
target	SpatRaster. Backscatter dataset used as reference.
preds	SpatRaster. One or more layers to use as additional predictor variables for backscatter calibration model.
model	Character. Method used to model error between backscatter datasets. Currently supported models are "mean" (i.e., intercept-only), "glm", "randomForest", and "earth" (multivariate adaptive regression splines). Model defaults are generally retained (but see Details); use ... to specify additional parameters.
model_params	List of named model-specific parameters, for example, as used in a call to glm() or earth().
mosaic	Logical. Mosaic and output the backscatter layers?
mosaicmethod	Character. Which method to use to resample the corrected backscatter layer for mosaicking? See terra::resample() for details.
savedata	Logical. Whether to output the model data.frame. If crossvalidate is used, the validation data is additionally returned as dataVal.
sample	Numeric. Proportion of overlapping data to sample for modelling using samplemethods.
samplemethods	Character vector. The method used to subsample the data. One or several of "uniform" (the default), "stratify", or "autocorrelation". Specifying multiple methods results in a combined output. See Details.
crossvalidate	Numeric. Proportion of data to use for validation. Validation data are drawn from the dataset following saubsampling if sample is used.
...	Additional parameters passed to the model.

Details

By default, this function fits a linear regression to the error between two backscatter datasets using glm. The modelling method can be changed using the model argument, but extrapolation is important, and regression has performed well in simulations. Additional predictors such as bathymetry can be added as a single SpatRaster (potentially with multiple layers) using preds. If ⁠method = 'randomForest⁠ the default nodesize is n/10 of the overlapping raster cells to prevent overfitting on highly redundant data with a low number of predictors.

sample calls on bSample to draw a random sample of the data for modelling. This has two purposes:

1. to facilitate computation for large datasets, and

2. two represent the data more equitably (e.g., where backscatter values are over-represented at a certain level).

To handle the latter issue, samplemethods can be set to "stratify", which uses backscatter data quartiles to stratify the sampling. Setting samplemethods to "autocorrelation" weights the sampling spatially using local Moran's I, as calculated by terra::autocor(), so that sampling is reduced at areas of high autocorrelation. Multiple samplemethods can be combined by providing them as a vector.

Value

List of bulkshift objects.

References

Misiuk, B., Brown, C.J., Robert, K., Lacharite, M., 2020. Harmonizing Multi-Source Sonar Backscatter Datasets for Seabed Mapping Using Bulk Shift Approaches. Remote Sensing 12, 601. https://doi.org/10.3390/rs12040601

Examples

bb2016 <- rast(system.file('extdata', 'bb2016.tif', package='bulkshift'))
bb2017 <- rast(system.file('extdata', 'bb2017.tif', package='bulkshift'))
bbdepth <- rast(system.file('extdata', 'bbdepth.tif', package='bulkshift'))

#run bulkshift using bathymetry as an additional predictor
b <- bulkshift(bb2017, bb2016, bbdepth)
plot(b$shifted)

#cross-validate the model and create a mosaic
b <- bulkshift(bb2017, bb2016, bbdepth, mosaic = TRUE, crossvalidate = 0.25)
b$fitStats
b$testStats

benjaminmisiuk/bulkshift documentation built on May 24, 2023, 9:32 p.m.