Read one or more variables from raster files

read_vars(vardef, expect.nvars = NULL, expect.vars = NULL,
  expect.dims = NULL, expect.extent = NULL, expect.ids = NULL,
  offset = NULL, count = NULL, as.data.frame = FALSE,
  extra_dims = NULL)

Arguments

vardef

A variable definition, constructed using the following syntax: <filename>::<variables_or_bands> where <variables_or_bands> is a comma-separated list of band numbers or variable names.

A limited amount of transformation can be specified by adding extra characters to the band number or variable name:

  • Variables can be renamed by appending ->new_var_name

  • Data can be transformed by appending transformations such as @negate@fill0

A complete example is: PETmE_freq_trgt201701.img::1@fill0@negate->Neg_PETmE

In this example, band 1 is read from the file. NODATA values are replaced with zero, and all values are negated. The values are read into a variable called Neg_PETmE.

expect.nvars

If specified, read_vars will throw an error unless exactly expect.nvars variables are read from the file.

expect.vars

If specified, read_vars will throw an error if the list of variables read from the file (after renaming transformations) does not match expect.vars, irrespective of order.

expect.dims

If specified, read_vars will throw an error if dimensions of read data are not equal to expect.dims.

expect.extent

If specified, read_vars will throw an error if extent of read data is not exactly expect.extent.

expect.ids

If specified, read_vars will throw an error if ids of read data are not exactly and in the same order as expect.ids.

offset

Specifies dimension-wise (X, Y, ...) offsets from the upper-left corner of the raster (xmin, ymax) from which reading should begin. A value of c(1,1) refers to the corner cell itself (i.e., there is no offset). This follows the convention of the ncdf4 package. If offset is specified, then count must also be specified.

count

Specifies dimension-wise (X, Y, ...) numbers of cells to read, beginning at the origin cell specified by offset. A value of -1 signifies that all values after the origin cell should be read. If count is specified, then origin must also be specified.

as.data.frame

If TRUE, read_vars will return a data frame

extra_dims

list containing names and values of extra dimensions along which a values at a single point should be extracted, e.g. extra_dims=list(crop='maize', quantile=0.50). It provides a higher-abstraction alternative to the use of offset and count.

Value

A list having the following structure:

attrs

a list of global attributes in the file

data

a list of matrices containing data for each variable in the file. Matrices are consistent with the "raster" package, with rows representing decreasing latitude and columns representing increasing longitude. Any netCDF attributes defined for the variables will be attached as attributes of the matrix.

extent

the extent of the lat/lon coordinates for the data, in the order xmin, xmax, ymin, ymax. Will be null if the data is not gridded

ids

a vector of integer ids for the data. Will be null if the data is gridded