R: Read/write ASCII, SAGA and Rd Grid Files

read.ascii.grid {RSAGA}

R Documentation

Read/write ASCII, SAGA and Rd Grid Files

Description

These functions provide simple interfaces for reading and writing grids from/to ASCII grids and Rd files. Grids are stored as matrices, their headers in lists.

Usage

read.ascii.grid(
  file,
  return.header = TRUE,
  print = 0,
  nodata.values = c(),
  at.once = TRUE,
  na.strings = "NA"
)

read.ascii.grid.header(file, ...)

read.sgrd(
  fname,
  return.header = TRUE,
  print = 0,
  nodata.values = c(),
  at.once = TRUE,
  prec = 7,
  ...
)

read.Rd.grid(fname, return.header = TRUE)

write.ascii.grid(
  data,
  file,
  header = NULL,
  write.header = TRUE,
  digits,
  hdr.digits = 10,
  dec = ".",
  georef = "corner"
)

write.ascii.grid.header(file, header, georef, dec = ".", hdr.digits = 10)

write.sgrd(
  data,
  file,
  header = NULL,
  prec = 7,
  hdr.prec = 10,
  georef = "corner",
  ...
)

write.Rd.grid(data, file, header = NULL, write.header = TRUE, compress = TRUE)

Arguments

`file`	file name of an ASCII grid (extension defaults to `.asc` if not specified), or a connection open for reading or writing, as required
`return.header`	logical: should the grid header be returned (default), or just the grid data matrix? In the former case, `read.ascii.grid` returns a list with two components named `data` and `header`.
`print`	numeric, specifying how detailed the output reporting the progress should be (currently 0 to 2, 0 being minimum output).
`nodata.values`	optional numeric vector specifying nodata values to be used in addition to the nodata value specified in the grid header; nodata values are converted to `NA`.
`at.once`	logical: if `TRUE`, read the whole grid with one `scan` command; if `FALSE`, read it row by row using `scan` with option `nlines=1`.
`na.strings`	passed on to `scan()`.
`...`	`read.sgrd`, `write.sgrd`: additional arguments to be passed to `rsaga.geoprocessor`
`fname`	file name of a grid stored as an R (`.Rd`) file; extension defaults to `.Rd`
`prec`	integer: number of digits of temporary ASCII grid used for importing or exporting a SAGA grid
`data`	grid data: a data matrix, or a list with components `data` (the grid data matrix) and `header` (the grid header information).
`header`	optional list argument specifying the grid header information as returned by the `read.ascii.grid` or `read.ascii.grid.header` function; see Details
`write.header`	logical: should the header be written with the grid data? (default: `TRUE`)
`digits`	numeric: if not missing, write data rounded to this many decimal places
`hdr.digits`	numeric: see `hdr.prec`
`dec`	character (default: `"."`): decimal mark used in input or output file
`georef`	character: specifies whether the output grid should be georeferenced by the `"center"` or `"corner"` of its lower left grid cell; defaults to `"corner"`.
`hdr.prec`	numeric: write (non-integer) header data with this many decimal places; a value of 9 or higher is recommended for compatibility with SAGA GIS (default: 10)
`compress`	logical: should the `.Rd` file written by `write.Rd.file` be compressed? (default: `TRUE`)

Value

The ⁠read.*⁠ functions return either a list with components data (the grid data matrix) and header (the grid header information, see below), if return.header=TRUE, or otherwise just the grid data matrix return.header=FALSE.

The grid data matrix is a numeric matrix whose first column corrensponds to the first (i.e. northernmost) row of the grid. Columns run from left = West to right = East.

The header information returned by the read.ascii.grid[.header] functions (if return.header=TRUE) is a list with the following components:

`ncols`	Number of grid columns.
`nrows`	Number of grid rows.
`xllcorner`	x coordinate of the corner of the lower left grid cell.
`yllcorner`	y coordinate of the corner of the lower left grid cell.
`cellsize`	Single numeric value specifying the size of a grid cell or pixel in both x and y direction.
`nodata_value`	Single numeric value being interpreted as `NA` (typically `-9999`.
`xllcenter`	x coordinate of the center of the lower left grid cell
`yllcenter`	y coordinate of the center of the lower left grid cell

Note: The order of the components, especially of ?llcorner and ?llcenter, may change, depending on the order in which they appear in the grid header and on the georeferencing method (center or corner) used for the grid. The ?llcorner and ?llcenter attributes differ only by cellsize/2.

Note

read.sgrd and write.sgrd import/export grids indirectly by creating temporary ASCII grid files (this explains why write.sgrd has prec and hdr.prec arguments). Consider using sf::read_sf() in package sf instead, which is likely more efficient but may require coercion of your gridded data to/from an object supported by sf.

The read.Rd.grid and write.Rd.grid functions use the load and save commands to store a grid. The variable name used is data, which is either a numeric matrix or a list with components data (the grid data matrix) and header (the grid header information).

Author(s)

Alexander Brenning