Whitebox Workflows for R {wbw}

The {wbw} R package provides R bindings to the Whitebox Workflows for Python — a powerful and fast library for advanced geoprocessing, with focus on hydrological, geomorphometric and remote sensing analysis of raster, vector and LiDAR data.

Basic workflow

The {wbw} R package introduces several new S7 classes, including WhiteboxRaster and WhiteboxVector which serves as a bridge between Python and R.

library(wbw)

raster_path <- system.file("extdata/dem.tif", package = "wbw")
dem <- wbw_read_raster(raster_path)
dem
#> +------------------------------------------+ 
#> | WhiteboxRaster                           |
#> | dem.tif                                  |
#> |..........................................| 
#> | bands       : 1                          |
#> | dimensions  : 726, 800  (nrow, ncol)     |
#> | resolution  : 5.002392, 5.000243  (x, y) |
#> | EPSG        : 2193  (Linear_Meter)       |
#> | min value   : 63.698193                  |
#> | max value   : 361.020721                 |
#> +------------------------------------------+

The true power of {wbw} unleashes when there’s a need to run several operations sequentially, i.e., in a pipeline. Unlike the original Whitebox Tools, WbW stores files in memory, reducing the amount of intermediate I/O operations.

For example, a DEM can be smoothed (or filtered), and then the slope can be estimated as follows:

dem |>
  wbw_mean_filter() |> 
  wbw_slope(units = "d")
#> +------------------------------------------+ 
#> | WhiteboxRaster                           |
#> | Slope (degrees)                          |
#> |..........................................| 
#> | bands       : 1                          |
#> | dimensions  : 726, 800  (nrow, ncol)     |
#> | resolution  : 5.002392, 5.000243  (x, y) |
#> | EPSG        : 2193  (Linear_Meter)       |
#> | min value   : 0.005972                   |
#> | max value   : 50.069439                  |
#> +------------------------------------------+

Yet Another RSpatial Package? Why?

The above example may remind you of the {terra} package, and it is not a coincidence. The {wbw} package is designed to be fully compatible with {terra}, and the conversion between WhiteboxRaster and SpatRaster objects happens in milliseconds (well, depending on the raster size, of course).

library(terra)

wbw_read_raster(raster_path) |> 
  wbw_gaussian_filter(sigma = 1.5) |> 
  wbw_aspect() |> 
  as_rast() |> # Conversion to SpatRaster
  plot(main = "Aspect")

Even though {wbw} can be faster than {terra} in some cases, it is by no means intended to replace it.

requireNamespace("bench", quietly = TRUE)

bench::mark(
  terra = {
    s <- 
      raster_path |> 
        rast() |> 
        terrain("slope", unit = "radians") |> 
        focal(w = 15, "mean") |> 
        global(\(x) median(x, na.rm = TRUE))

  round(s$global, 2)

  },
  wbw = {
    raster_path |>
      wbw_read_raster() |> 
      wbw_slope("radians") |> 
      wbw_mean_filter(15, 15) |> 
      median() |> 
      round(2)
  },
  check = TRUE,
  iterations = 11L
)
#> # A tibble: 2 × 6
#>   expression      min   median `itr/sec` mem_alloc `gc/sec`
#>   <bch:expr> <bch:tm> <bch:tm>     <dbl> <bch:byt>    <dbl>
#> 1 terra       290.7ms  291.5ms      3.43   28.58MB     17.2
#> 2 wbw          37.5ms   39.1ms     25.5     3.72KB      0

Installation

You can install the development version of wbw from GitHub with:

# install.packages("pak")
pak::pak("atsyplenkov/wbw")

[!TIP]

The {wbw} package requires the whitebox-workflows Python library v1.3.3+. However, you should not worry about it, as the package designed to install all dependencies automatically on the first run.

Contributing

Contributions are welcome! Please see our contributing guidelines for details. There is an open issue for the {wbw} package here that contains a list of functions yet to be implemented. This is a good place to start.