read_RAST: Read and write GRASS raster files

In rsbivand/rgrass7: Interface Between 'GRASS' Geographical Information System and 'R'

Read and write GRASS raster files

Description

Read GRASS raster files from GRASS into R terra::SpatRaster or sp::SpatialGridDataFrame objects, and write single columns of terra::SpatRaster or sp::SpatialGridDataFrame objects to GRASS. When return_format="terra", temporary binary files and r.out.bin and r.in.bin are used for speed reasons. read_RAST() and write_RAST() by default use "RRASTER" files written and read by GDAL.

Usage

read_RAST(
  vname,
  cat = NULL,
  NODATA = NULL,
  return_format = "terra",
  close_OK = return_format == "SGDF",
  flags = NULL,
  Sys_ignore.stdout = FALSE,
  ignore.stderr = get.ignore.stderrOption()
)

write_RAST(
  x,
  vname,
  zcol = 1,
  NODATA = NULL,
  flags = NULL,
  ignore.stderr = get.ignore.stderrOption(),
  overwrite = FALSE,
  verbose = TRUE
)

Arguments

vname	A vector of GRASS raster file names in mapsets in the current search path, as set by "g.mapsets"; the file names may be given as fully-qualified map names using "name@mapset", in which case only the mapset given in the full path will be searched for the existence of the raster; if more than one raster with the same name is found in mapsets in the current search path, an error will occur, in which case the user should give the fully-qualified map name. If the fully-qualified name is used, @ will be replaced by underscore in the output object.
cat	default NULL; if not NULL, must be a logical vector matching vname, stating which (CELL) rasters to return as factor.
NODATA	by default NULL, in which case it is set to one less than floor() of the data values for FCELL rasters or the range maximum for CELL Byte, UInt16 and Uint32 rasters (with no negative values), and an attempt is made to set NODATA to the upper Int16 and Int32 range if the lower range is occupied; otherwise an integer NODATA value (required to be integer by GRASS r.out.bin).
return_format	default terra, optionally SGDF.
close_OK	default TRUE - clean up possible open connections used for reading metadata; may be set to FALSE to avoid the side-effect of other user-opened connections being broken.
flags	default NULL, character vector, for example overwrite.
Sys_ignore.stdout	Passed to system.
ignore.stderr	default taking the value set by set.ignore.stderrOption; can be set to TRUE to silence system() output to standard error; does not apply on Windows platforms.
x	A terra terra::SpatRaster or sp sp::SpatialGridDataFrame object,
zcol	Attribute column number or name,
overwrite	default FALSE, if TRUE inserts "overwrite" into the value of the flags argument if not already there to allow existing GRASS rasters to be overwritten,
verbose	default TRUE, report how writing to GRASS is specified,

Value

by default returns a SpatRaster object, but may return a legacy SpatialGridDataFrame object if return_format="SGDF". write_RAST silently returns the object being written to GRASS.

Author(s)

Roger S. Bivand, e-mail: [e-mail]

Examples

# Run example only if GRASS settings file indicates that the
# nc_basic_spm_grass7 location is active
run <- FALSE
GISRC <- Sys.getenv("GISRC")

if (nchar(GISRC) > 0) {
  location_name <- read.dcf(GISRC)[1, "LOCATION_NAME"]
  if (location_name == "nc_basic_spm_grass7") {
    run <- TRUE
  }
}

# store original environment variables before modifying
GV <- Sys.getenv("GRASS_VERBOSE")
Sys.setenv("GRASS_VERBOSE" = 0)
original_ignore_stderr <- get.ignore.stderrOption()
set.ignore.stderrOption(TRUE)

if (run) {
  # Retrieve GRASS metadata and creata a new mapset
  meta <- gmeta()
  location_path <- file.path(meta$GISDBASE, meta$LOCATION_NAME)
  previous_mapset <- meta$MAPSET
  example_mapset <- "RGRASS_EXAMPLES"
  execGRASS("g.mapset", flags = "c", mapset = example_mapset)

  # List available mapsets and raster maps
  mapsets <- unlist(
    strsplit(execGRASS("g.mapsets", flags = "p", intern = TRUE), " ")
  )
  print(mapsets)

  execGRASS("g.list", type = "raster", pattern = "soils", flags = "m",
            intern = TRUE)
  execGRASS("g.list", type = "raster", pattern = "soils@PERMANENT",
            mapset = ".", flags = "m", intern = TRUE)
  execGRASS("g.list", type = "raster", pattern = "soils",
            mapset = "PERMANENT", flags = "m", intern = TRUE)

  # Read/write the GRASS "landuse" dataset as a SpatRaster
  if (require("terra", quietly = TRUE)) {
    v1 <- read_RAST("landuse", cat = TRUE, return_format = "terra")
    print(v1)
    print(inMemory(v1))

    write_RAST(v1, "landuse1", flags = c("o", "overwrite"))
    execGRASS("r.stats", flags = "c", input = "landuse1")
    execGRASS("g.remove", flags = "f", name = "landuse1", type = "raster")
  }

  Sys.setenv("_SP_EVOLUTION_STATUS_" = "2")

  # read the geology and elevation GRASS datasets as SpatialGridDataFrames
  if (require("sp", quietly = TRUE)) {
    nc_basic <- read_RAST(c("geology", "elevation"), cat = c(TRUE, FALSE),
                          return_format = "SGDF")
    print(table(nc_basic$geology))

    execGRASS("r.stats", flags = c("c", "l", "quiet"), input = "geology")
    boxplot(nc_basic$elevation ~ nc_basic$geology)

    # Compute square root of elevation and write back to GRASS
    nc_basic$sqdem <- sqrt(nc_basic$elevation)
    write_RAST(nc_basic, "sqdemSP", zcol = "sqdem",
               flags = c("quiet", "overwrite"))
    execGRASS("r.info", map = "sqdemSP")

    # Read the new raster data and measure read times
    print(system.time(
      sqdemSP <- read_RAST(c("sqdemSP", "elevation"), return_format = "SGDF")
    ))
    print(system.time(
      sqdem <- read_RAST(c("sqdemSP", "elevation"), return_format = "terra"))
    )
    print(names(sqdem))

    sqdem1 <- read_RAST(c("sqdemSP@RGRASS_EXAMPLES", "elevation@PERMANENT"))
    print(names(sqdem1))

    execGRASS("g.remove", flags = "f", name = "sqdemSP", type = "raster")

    # GRASS r.mapcalc example
    execGRASS("r.mapcalc", expression = "basins0 = basins - 1",
              flags = "overwrite")
    execGRASS("r.stats", flags = "c", input = "basins0")

    basins0 <- read_RAST("basins0", return_format = "SGDF")
    print(table(basins0$basins0))
    execGRASS("g.remove", flags = "f", name = "basins0", type = "raster")

    # Create and read a test raster
    execGRASS("r.mapcalc", expression = "test_t = 66000",
              flags = "overwrite")
    execGRASS("r.info", flags = "r", map = "test_t", intern = TRUE)
    tt <- read_RAST("test_t")
    execGRASS("g.remove", flags = "f", name = "test_t", type = "raster")
  }

  # Restore the previous mapset and clean up
  execGRASS("g.mapset", mapset = previous_mapset)
  if (example_mapset != previous_mapset) {
    unlink(file.path(location_path, example_mapset), recursive = TRUE)
  }
}

# Restore original GRASS settings
Sys.setenv("GRASS_VERBOSE" = GV)
set.ignore.stderrOption(original_ignore_stderr)

rsbivand/rgrass7 documentation built on Nov. 3, 2024, 6:06 a.m.