read_netCDF: Read a netCDF

In DrylandEcology/rSW2st: Spatiotemporal Tools for SOILWAT2 and STEPWAT2 Simulation Experiments

Read a netCDF

Description

Read a netCDF as produced by create_netCDF

Usage

read_netCDF(
  x,
  method = c("array", "raster", "stars", "terra", "xy_subset"),
  var = NULL,
  nc_name_crs = "crs",
  nc_name_crs_wkt = "crs_wkt",
  locations = NULL,
  verbose_read = TRUE,
  ...
)

read_netCDF_as_array(
  x,
  var = NULL,
  nc_name_crs = "crs",
  nc_name_crs_wkt = "crs_wkt",
  xy_names = c("lon", "lat"),
  time_name = "time",
  time_ids = -1,
  vertical_name = "vertical",
  vertical_ids = -1,
  collapse_degen = TRUE,
  load_values = TRUE,
  ...
)

read_netCDF_as_raster(
  x,
  var = NULL,
  nc_name_crs = "crs",
  nc_name_crs_wkt = "crs_wkt",
  verbose_read = TRUE,
  ...
)

read_netCDF_as_stars(
  x,
  var = NULL,
  nc_name_crs = "crs",
  nc_name_crs_wkt = "crs_wkt",
  verbose_read = TRUE,
  ...
)

read_netCDF_as_terra(
  x,
  var = NULL,
  nc_name_crs = "crs",
  nc_name_crs_wkt = "crs_wkt",
  verbose_read = TRUE,
  ...
)

Arguments

x	An object identifying a netCDF file, i.e., a character string as file name or an object of class ncdf4 derived from ncdf4::nc_open.
method	A character string. Determines how the netCDF is read and if a spatial subset (by locations) is extracted.
var	A character string. The variable name to be read. Passed along as varname for rasters or var for stars targets.
nc_name_crs	A character string. The name of the crs variable in the netCDF. Function create_netCDF hard codes "crs".
nc_name_crs_wkt	A character string. The name of the attribute that holds the WKT2 string of the crs variable in the netCDF. Function create_netCDF hard codes "crs_wkt".
locations	An object from which x and y coordinate values can be extracted that describe the xy locations of each data row, e.g., a matrix or data.frame or a spatial points object inheriting from sf or Spatial*.
verbose_read	A logical value. If FALSE, then an attempt is made to silence communication generated from reading the netCDF.
...	Additional arguments passed on to the specific functions.
xy_names	A vector with two character strings. The names of the x and y spatial dimensions of a netCDF file.
time_name	A character string. The dimension name corresponding to the time axis.
time_ids	An integer vector. The index to read a subset of time steps; a value of -1 means to read all.
vertical_name	A character string. The dimension name corresponding to the vertical axis.
vertical_ids	An integer vector. The index to read a subset of vertical steps; a value of -1 means to read all.
collapse_degen	A logical value. If TRUE, then degenerate, i.e., length-1 vertical and time dimensions in the returned array are collapsed. A degenerate variable dimension, in the case of a "xy" data structure, is always collapsed. The dimension/s of the xy-space is/are never collapsed.
load_values	A logical value. If FALSE, then data values are not returned (i.e., element "data" of the returned object will be NULL).

Value

A named list including a data array (the list contains completed information to re-create the file with a call to create_netCDF), a raster::RasterLayer, or a stars::stars object.

Notes

Reading discrete netCDFs, i.e., cases "szt", "st", "sz", and "s", is mostly supported; see examples.

Details

read_netCDF_as_raster is a thin wrapper around raster::raster, but makes an extra attempt to correctly set the crs object.

read_netCDF_as_stars is a thin wrapper around stars::read_ncdf, but makes an extra attempt to correctly set the crs object.

read_netCDF_as_terra is a thin wrapper around terra::rast, but makes an extra attempt to correctly set the crs object.

Examples

tmp_nc <- create_example_netCDFs(tempdir(), c("xyt", "szt"), "timeseries")

## Read gridded netCDF as array
data_xyt <- read_netCDF(
  tmp_nc[["xyt"]],
  method = "array",
  xy_names = c("x", "y")
)

if (requireNamespace("graphics")) {
  graphics::persp(
    x = data_xyt[["xyspace"]][["x"]],
    y = data_xyt[["xyspace"]][["y"]],
    z = data_xyt[["data"]][, , 15],
    theta = 30,
    phi = 30,
    expand = 0.5,
    col = "lightblue"
  )
}

## Read discrete netCDF as array
data_szt <- read_netCDF(
  tmp_nc[["szt"]],
  method = "array",
  xy_names = c("x", "y")
)

if (requireNamespace("graphics")) {
  cols <- grDevices::hcl.colors(12, "YlOrRd", rev = TRUE)

  plot(
    data_szt[["xyspace"]][["x"]],
    data_szt[["xyspace"]][["y"]],
    col = cols[cut(data_szt[["data"]][, 1, 15], breaks = 12)],
    pch = 16
  )

  graphics::image(
    x = data_szt[["site"]],
    y = data_szt[["vertical_values"]],
    z = data_szt[["data"]][, , 15],
    col = cols
  )
}


## Read netCDF as raster object
if (requireNamespace("raster")) {
  # This will generate several warnings and messages
  raster_xyt <- read_netCDF(
    tmp_nc[["xyt"]],
    method = "raster",
    band = 15,
    verbose_read = FALSE
  )
  raster::plot(raster_xyt)

  raster_szt <- read_netCDF(
    tmp_nc[["szt"]],
    method = "raster",
    band = 15,
    verbose_read = FALSE
  )
  raster::plot(raster_szt)
}

## Read netCDF as stars object
stars_xyt <- read_netCDF(
  tmp_nc[["xyt"]],
  method = "stars",
  var = "sine",
  verbose_read = FALSE
)
plot(stars_xyt)

stars_szt <- read_netCDF(
  tmp_nc[["szt"]],
  method = "stars",
  var = "sine",
  verbose_read = FALSE
)
plot(stars_szt)

## Read netCDF as terra object
terra_xyt <- read_netCDF(
  tmp_nc[["xyt"]],
  method = "terra",
  var = "sine",
  verbose_read = FALSE
)
terra::plot(terra_xyt)

terra_szt <- read_netCDF(
  tmp_nc[["szt"]],
  method = "terra",
  var = "sine",
  verbose_read = FALSE
)
terra::plot(terra_szt)

## Read gridded netCDF as array and extract subset
datasubset_xyt <- read_netCDF(
  tmp_nc[["xyt"]],
  method = "xy_subset",
  locations = cbind(x = seq(-5, 5), y = 2501316 + seq(-5, 5)),
  xy_names = c("x", "y")
)

## Read CRS of netCDFs
read_crs_from_netCDF(tmp_nc[["xyt"]])
read_crs_from_netCDF(tmp_nc[["szt"]])

## Read attributes of netCDFs
read_attributes_from_netCDF(tmp_nc[["xyt"]], var = "sine")
read_attributes_from_netCDF(
  tmp_nc[["xyt"]],
  group = "all",
  var = "sine",
  xy_names = c("x", "y")
)
read_attributes_from_netCDF(tmp_nc[["szt"]], group = "global")

# Clean up
unlink(unlist(tmp_nc))

DrylandEcology/rSW2st documentation built on Jan. 10, 2024, 6:22 p.m.