Compute Bioclimatic Variables via the Native GDAL-Tiled Engine

High-level R interface to the BioclimEngine C++ tiled computation pipeline. Reads four sets of monthly climate rasters (mean temperature, maximum temperature, minimum temperature, and precipitation) from disk, computes the requested bioclimatic variables, and writes all 19 variables to a single multi-band GeoTIFF named bio.tif inside the output directory — one tile at a time so that peak memory is proportional to tile_size, not the full raster extent.

Usage

bioclim_engine(
  tas,
  tasmax,
  tasmin,
  pr,
  output = tempfile("bioclim_"),
  variables = 1:19,
  mask = NULL,
  threads = 1L,
  tile_size = 256L,
  overwrite = FALSE,
  device = c("auto", "cpu", "gpu"),
  dtype = c("Float64", "Float32"),
  use_pipeline = FALSE
)

Arguments

tas: Character vector of length 1 (12-band file) or 12 (one file per month), or a terra::SpatRaster with 12 layers: monthly mean temperature.
tasmax: Like tas but for monthly maximum temperature.
tasmin: Like tas but for monthly minimum temperature.
pr: Like tas but for monthly precipitation.
output: Character string: path to the output directory where the multi-band GeoTIFF bio.tif will be written. The directory is created automatically if it does not exist. Defaults to a temporary directory.
variables: Integer vector of variable numbers to compute, with values in 1:19. Default is 1:19 (all 19 variables). For example, c(1, 12) returns only BIO01 and BIO12 from the 19-band output.
mask: Optional mask: a character file path, an sf object (polygon), or a terra::SpatRaster. NULL (default) means no masking.
threads: Positive integer: number of OpenMP threads to use. Default is 1L.
tile_size: Positive integer: tile dimension (pixels) for tiled I/O. Default is 256L.
overwrite: Logical: whether to overwrite an existing bio.tif inside output. Default is FALSE.
device: Character scalar: compute device to use. One of "auto" (default), "cpu", or "gpu". "auto" selects the GPU when a CUDA device is available, otherwise falls back to the CPU. "gpu" on a system without CUDA emits a warning and falls back to the CPU. When device = "gpu" and tile_size is left at its default, the tile size is automatically scaled to match the detected GPU memory (4096 for high-memory GPUs such as the A100, 1024 otherwise).
dtype: Character scalar: output data type, one of "Float64" (default) or "Float32".
use_pipeline: Logical scalar: if TRUE, use the experimental overlapped read/compute/write pipeline with parallel 12-reader I/O. Default is FALSE, which keeps the original serial tiled loop.

Value

If terra is installed, a terra::SpatRaster with one layer per selected variable (named bio01 … bio19). Otherwise a character scalar: the path to bio.tif.

Details

GDAL requirement. This function requires the package to have been compiled with GDAL support (see has_gdal). If GDAL is not available an informative error is raised immediately.

Variable selection. By default all 19 standard bioclimatic variables (BIO01–BIO19) are returned. Pass variables as an integer vector (e.g. c(1, 12, 15)) to restrict the returned terra::SpatRaster to a subset. The engine always computes all 19 internally and writes a full 19-band bio.tif; the subsetting is applied when constructing the returned object.

Single multi-band output. The output directory contains one file, bio.tif, with 19 bands (BIO01–BIO19). This reduces GDAL I/O call overhead compared with the previous one-file-per-variable layout.

Tiled processing. The engine reads and writes rasters in square tiles of tile_size × tile_size pixels. Choosing a large tile improves I/O efficiency; a small tile reduces peak RAM. The default (256) is a good balance for most use cases.

Multi-band vs. single-band inputs. Each climate variable can be supplied either as twelve single-band files (one per calendar month) or as one multi-band file with exactly 12 bands. A terra::SpatRaster with 12 layers is also accepted; its on-disk source paths are extracted automatically via terra::sources().

Mask support. An optional raster or vector mask can be used to restrict computation to a specific region. Pixels outside the mask are written as NaN. Accepted formats:

character — path to any GDAL-readable raster or OGR vector.
sf object — written to a temporary GeoJSON and rasterized.
terra::SpatRaster — written to a temporary GeoTIFF.

Output data type. Use dtype = "Float32" to halve the output file size. Values are rounded from double-precision internal arithmetic to single precision on write; numerical differences are typically below 1e-5.

Output. If terra is installed the function returns a terra::SpatRaster whose layers correspond to the selected variables. Otherwise it returns the path to the output bio.tif file.

Examples

# \donttest{
if (has_gdal() && requireNamespace("terra", quietly = TRUE)) {
  library(terra)

  # Create tiny synthetic climate rasters (10x10 pixels, 12 layers each)
  make_rast <- function(vals, file) {
    r <- rast(nrows = 10, ncols = 10, nlyrs = 12,
              xmin = 0, xmax = 1, ymin = 0, ymax = 1, crs = "EPSG:4326")
    for (m in seq_len(12)) values(r[[m]]) <- vals[m]
    writeRaster(r, file, overwrite = TRUE)
    file
  }

  tmp <- tempdir()
  tas_file    <- make_rast(c(5,7,10,14,18,22,25,24,20,15,10,6),
                            file.path(tmp, "tas.tif"))
  tasmax_file <- make_rast(c(8,10,14,18,23,28,32,31,26,19,13,9),
                            file.path(tmp, "tasmax.tif"))
  tasmin_file <- make_rast(c(1,3,6,10,13,17,20,19,15,10,6,2),
                            file.path(tmp, "tasmin.tif"))
  pr_file     <- make_rast(c(60,55,48,35,28,22,18,20,35,55,65,68),
                            file.path(tmp, "pr.tif"))

  # Compute all 19 variables (single multi-band output file)
  out_dir <- file.path(tmp, "bioclim_out")
  result <- bioclim_engine(tas_file, tasmax_file, tasmin_file, pr_file,
                            output = out_dir, overwrite = TRUE)
  nlyr(result)   # 19
  list.files(out_dir, pattern = "[.]tif$")

  # Compute only BIO01 and BIO12
  out_dir2 <- file.path(tmp, "bioclim_subset")
  result2 <- bioclim_engine(tas_file, tasmax_file, tasmin_file, pr_file,
                             output = out_dir2, variables = c(1L, 12L),
                             overwrite = TRUE)
  nlyr(result2)  # 2
  names(result2) # "bio01" "bio12"
}
#> Warning: /tmp/RtmpRzND6Y/file31e62c5a8e7a.tif: No such file or directory (GDAL error 4)
#> terra 1.9.50
#> Warning: /tmp/RtmpRzND6Y/file31e65e540795.tif: No such file or directory (GDAL error 4)
#> Warning: /tmp/RtmpRzND6Y/file31e6285cd29a.tif: No such file or directory (GDAL error 4)
#> [1] "bio01" "bio12"
# }