Skip to contents

Run GRASS commands

Source: R/xml1.R
execGRASS.Rd

The functions provide an interface to GRASS commands run through system, based on the values returned by the --interface description flag using XML parsing. If required parameters are omitted, and have declared defaults, the defaults will be used.

Usage

execGRASS(
  cmd,
  flags = NULL,
  ...,
  parameters = NULL,
  intern = NULL,
  ignore.stderr = NULL,
  Sys_ignore.stdout = FALSE,
  Sys_wait = TRUE,
  Sys_input = NULL,
  Sys_show.output.on.console = TRUE,
  Sys_minimized = FALSE,
  Sys_invisible = TRUE,
  echoCmd = NULL,
  redirect = FALSE,
  legacyExec = NULL
)

stringexecGRASS(
  string,
  intern = NULL,
  ignore.stderr = NULL,
  Sys_ignore.stdout = FALSE,
  Sys_wait = TRUE,
  Sys_input = NULL,
  Sys_show.output.on.console = TRUE,
  Sys_minimized = FALSE,
  Sys_invisible = TRUE,
  echoCmd = NULL,
  redirect = FALSE,
  legacyExec = NULL
)

doGRASS(
  cmd,
  flags = NULL,
  ...,
  parameters = NULL,
  echoCmd = NULL,
  legacyExec = NULL
)

parseGRASS(cmd, legacyExec = NULL)

# S3 method for class 'GRASS_interface_desc'
print(x, ...)

getXMLencoding()

setXMLencoding(enc)

Arguments

cmd

GRASS command name.

flags

character vector of GRASS command flags.

...

for execGRASS and doGRASS, GRASS module parameters given as R named arguments directly. For the print method, other arguments to print method. The storage modes of values passed must match thos required in GRASS, so a single GRASS string must be a character vector of length 1, a single GRASS integer must be an integer vector of length 1 (may be an integer constant such as 10L), and a single GRASS float must be a numeric vector of length 1. For multiple values, use vectors of suitable length.

parameters

list of GRASS command parameters, used if GRASS parameters are not given as R arguments directly; the two methods for passing GRASS parameters may not be mixed. The storage modes of values passed must match thos required in GRASS, so a single GRASS string must be a character vector of length 1, a single GRASS integer must be an integer vector of length 1 (may be an integer constant such as 10L), and a single GRASS float must be a numeric vector of length 1. For multiple values, use vectors of suitable length.

intern

default NULL, in which case set internally from get.useInternOption; a logical (not 'NA') which indicates whether to make the output of the command an R object. Not available unless 'popen' is supported on the platform.

ignore.stderr

default NULL, taking the value set by set.ignore.stderrOption, a logical indicating whether error messages written to 'stderr' should be ignored.

Sys_ignore.stdout, Sys_wait, Sys_input

pass extra arguments to system.

Sys_show.output.on.console, Sys_minimized, Sys_invisible

pass extra arguments to system on Windows systems only.

echoCmd

default NULL, taking the logical value set by set.echoCmdOption, print GRASS command to be executed to console.

redirect

default FALSE, if TRUE, add "2>&1" to the command string and set intern to TRUE; only used in legacy mode.

legacyExec

default NULL, taking the logical value set by set.legacyExecOption which is initialised to FALSE on "unix" platforms and TRUE otherwise. If TRUE, use system, if FALSE use system2 and divert stderr to temporary file to record error messages and warnings from GRASS modules.

string

a string representing one full GRASS statement, using shell syntax: command name, optionally followed by flags and parameters, all separated by whitespaces. Parameters follow the key=value format; if ’value’ contains spaces, then ’value’ must be quoted

x

object to be printed

enc

character string to replace UTF-8 in header of XML data generated by GRASS module –interface-description output when the internationalised messages are not in UTF-8 (known to apply to French, which is in latin1)

Value

parseGRASS returns a GRASS_interface_desc object, doGRASS returns a character string with a proposed GRASS command - the expanded command name is returned as an attribute, and execGRASS and stringexecGRASS return what system or system2 return, particularly depending on the intern argument when the character strings output by GRASS modules are returned.

If intern is FALSE, system returns the module exit code, while system2 returns the module exit code with "resOut" and "resErr" attributes.

Details

parseGRASS checks to see whether the GRASS command has been parsed already and cached in this session; if not, it reads the interface description, parses it and caches it for future use. doGRASS assembles a proposed GRASS command with flags and parameters as a string, wrapping parseGRASS, and execGRASS is a wrapper for doGRASS, running the command through system (from 0.7-4, the ... argument is not used for passing extra arguments for system). The command string is termed proposed, because not all of the particular needs of commands are provided by the interface description, and no check is made for the existence of input objects. Support for multiple parameter values added with help from Patrick Caldon. Support for defaults and for direct use of GRASS parameters instead of a parameter list suggested by Rainer Krug.

stringexecGRASS is a wrapper around execGRASS, and accepts a single shell statement as a string (following GRASS's command syntax).

Note

If any package command fails with a UTF-8 error from the XML package, try using setXMLencoding to work around the problem that GRASS modules declare –interface-description output as UTF-8 without ensuring that it is (French is of 6.4.0 RC5 latin1).

See also

base::system()

Author

Roger S. Bivand, e-mail: Roger.Bivand@nhh.no

Examples

# Run examples if in an active GRASS session in the nc_basic_spm_grass7
Sys.setenv("_SP_EVOLUTION_STATUS_" = "2")
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
  }
}

# Save and set echo command option
echoCmdOption <- get.echoCmdOption()
set.echoCmdOption(TRUE)
#> [1] FALSE

if (run) {
  # Read and print GRASS interface description for 'r.slope.aspect'
  print(parseGRASS("r.slope.aspect"))

  # Assemble the 'r.slope.aspect' command with specified parameters as a string
  doGRASS(
    "r.slope.aspect",
    flags = c("overwrite"),
    elevation = "elevation.dem",
    slope = "slope",
    aspect = "aspect"
  )

  # Alternatively, specify parameters as a list
  params <- list(elevation = "elevation",
                 slope = "slope",
                 aspect = "aspect")
  doGRASS("r.slope.aspect",
          flags = c("overwrite"),
          parameters = params)

  # Read and print GRASS interface description for 'r.buffer'
  print(parseGRASS("r.buffer"))

  # Assemble the 'r.buffer' with specified parameters as as string
  doGRASS(
    "r.buffer",
    flags = c("overwrite"),
    input = "schools",
    output = "bmap",
    distances = seq(1000, 15000, 1000)
  )

  # Alternatively, specify parameters as a list
  params <- list(
    input = "schools",
    output = "bmap",
    distances = seq(1000, 15000, 1000)
  )
  doGRASS("r.buffer", flags = c("overwrite"), parameters = params)

  # Restore original echo command option
  set.echoCmdOption(echoCmdOption)

  # Try executing 'r.stats' command which will fail because "fire_blocksgg"
  # does not exist in the mapset
  try(res <- execGRASS("r.stats", input = "fire_blocksgg", flags = c("C", "n")),
      silent = FALSE)

  # Execute 'r.stats' with legacyExec and print the result
  res <- execGRASS(
    "r.stats",
    input = "fire_blocksgg",
    flags = c("C", "n"),
    legacyExec = TRUE
  )
  print(res)

  # If the command failed, retrieve error message
  if (res != 0) {
    resERR <- execGRASS(
      "r.stats",
      input = "fire_blocksgg",
      flags = c("C", "n"),
      redirect = TRUE,
      legacyExec = TRUE
    )
    print(resERR)
  }

  # Use 'stringexecGRASS' to run a command and print the result
  res <- stringexecGRASS("r.stats -p -l input=geology", intern = TRUE)
  print(res)

  stringexecGRASS(
    "r.random.cells --overwrite --quiet output=samples distance=1000 ncells=100 seed=1"
  )

  # Alternatively, run the same command using 'execGRASS'
  execGRASS(
    "r.random.cells",
    flags  = c("overwrite", "quiet"),
    output = "samples",
    distance = 1000,
    ncells = 100L,
    seed = 1L
  )
}
#> Command: r.slope.aspect 
#> Description: Generates raster maps of slope, aspect, curvatures and partial derivatives from an elevation raster map. Aspect is calculated counterclockwise from east. 
#> Keywords: raster, terrain, aspect, slope, curvature, parallel 
#> Parameters:
#>   name: elevation, type: string, required: yes, multiple: no
#>   keydesc: name, keydesc_count: 1
#> [Name of input elevation raster map]
#>   name: slope, type: string, required: no, multiple: no
#>   keydesc: name, keydesc_count: 1
#> [Name for output slope raster map]
#>   name: aspect, type: string, required: no, multiple: no
#>   keydesc: name, keydesc_count: 1
#> [Name for output aspect raster map]
#>   name: format, type: string, required: no, multiple: no
#>   default: degrees
#> [Format for reporting the slope]
#>   name: precision, type: string, required: no, multiple: no
#>   default: FCELL
#> [Storage type for resultant raster map]
#>   name: pcurvature, type: string, required: no, multiple: no
#>   keydesc: name, keydesc_count: 1
#> [Name for output profile curvature raster map]
#>   name: tcurvature, type: string, required: no, multiple: no
#>   keydesc: name, keydesc_count: 1
#> [Name for output tangential curvature raster map]
#>   name: dx, type: string, required: no, multiple: no
#>   keydesc: name, keydesc_count: 1
#> [Name for output first order partial derivative dx (E-W slope) raster map]
#>   name: dy, type: string, required: no, multiple: no
#>   keydesc: name, keydesc_count: 1
#> [Name for output first order partial derivative dy (N-S slope) raster map]
#>   name: dxx, type: string, required: no, multiple: no
#>   keydesc: name, keydesc_count: 1
#> [Name for output second order partial derivative dxx raster map]
#>   name: dyy, type: string, required: no, multiple: no
#>   keydesc: name, keydesc_count: 1
#> [Name for output second order partial derivative dyy raster map]
#>   name: dxy, type: string, required: no, multiple: no
#>   keydesc: name, keydesc_count: 1
#> [Name for output second order partial derivative dxy raster map]
#>   name: zscale, type: float, required: no, multiple: no
#>   default: 1.0
#> [Multiplicative factor to convert elevation units to horizontal units]
#>   name: min_slope, type: float, required: no, multiple: no
#>   default: 0.0
#> [Minimum slope value (in percent) for which aspect is computed]
#>   name: nprocs, type: integer, required: no, multiple: no
#>   default: 1
#> [Number of threads for parallel computing]
#>   name: memory, type: integer, required: no, multiple: no
#>   default: 300
#>   keydesc: memory in MB, keydesc_count: 1
#> [Cache size for raster rows]
#> Flags:
#>   name: a [Do not align the current region to the raster elevation map] {FALSE}
#>   name: e [Compute output at edges and near NULL values] {FALSE}
#>   name: n [Default: degrees counter-clockwise from East, with flat = 0] {FALSE}
#>   name: overwrite [Allow output files to overwrite existing files] {FALSE}
#>   name: help [Print usage summary] {FALSE}
#>   name: verbose [Verbose module output] {FALSE}
#>   name: quiet [Quiet module output] {FALSE}
#> GRASS command: r.slope.aspect --overwrite elevation=elevation.dem slope=slope aspect=aspect 
#> GRASS command: r.slope.aspect --overwrite elevation=elevation slope=slope aspect=aspect 
#> Command: r.buffer 
#> Description: Creates a raster map showing buffer zones surrounding cells that contain non-NULL category values. 
#> Keywords: raster, buffer 
#> Parameters:
#>   name: input, type: string, required: yes, multiple: no
#>   keydesc: name, keydesc_count: 1
#> [Name of input raster map]
#>   name: output, type: string, required: yes, multiple: no
#>   keydesc: name, keydesc_count: 1
#> [Name for output raster map]
#>   name: distances, type: float, required: yes, multiple: yes
#> [Distance zone(s)]
#>   name: units, type: string, required: no, multiple: no
#>   default: meters
#> [Units of distance]
#> Flags:
#>   name: z [Ignore zero (0) data cells instead of NULL cells] {FALSE}
#>   name: overwrite [Allow output files to overwrite existing files] {FALSE}
#>   name: help [Print usage summary] {FALSE}
#>   name: verbose [Verbose module output] {FALSE}
#>   name: quiet [Quiet module output] {FALSE}
#> GRASS command: r.buffer --overwrite input=schools output=bmap distances=1000,2000,3000,4000,5000,6000,7000,8000,9000,10000,11000,12000,13000,14000,15000 
#> GRASS command: r.buffer --overwrite input=schools output=bmap distances=1000,2000,3000,4000,5000,6000,7000,8000,9000,10000,11000,12000,13000,14000,15000 
#> Error in execGRASS("r.stats", input = "fire_blocksgg", flags = c("C",  : 
#>   The command:
#> r.stats -C -n input=fire_blocksgg
#> produced an error (1) during execution:
#> ERROR: Raster map <fire_blocksgg> not found
#> [1] 1
#> Warning: running command 'r.stats -C -n input=fire_blocksgg 2>&1' had status 1
#> [1] "ERROR: Raster map <fire_blocksgg> not found"
#> attr(,"status")
#> [1] 1
#>  [1] "217 CZfg 35.83%" "262 CZlg 9.81%"  "270 CZig 34.04%" "405 CZbg 12.53%"
#>  [5] "583 CZve 1.07%"  "720 CZam 0.24%"  "766 CZg 0.35%"   "862 CZam 3.05%" 
#>  [9] "910 CZbg 2.22%"  "921 Km 0.62%"    "945 CZbg 0.00%"  "946 CZam 0.20%" 
#> [13] "948 CZam 0.04%"