Read and write GRASS raster files — readRAST • rgrass

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.

read_RAST(vname, cat=NULL, NODATA=NULL, ignore.stderr=get.ignore.stderrOption(),
 return_format="terra", close_OK=return_format=="SGDF", flags=NULL)
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
cat: default NULL; if not NULL, must be a logical vector matching vname, stating which (CELL) rasters to return as factor
return_format: default "terra", optionally "SGDF"
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
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
x: A terra "SpatRaster" or sp "SpatialGridDataFrame" object
zcol: Attribute column number or name
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)
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
flags: default NULL, character vector, for example "overwrite"
verbose: default TRUE, report how writing to GRASS is specified

Value

read_RAST 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

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

Examples

run <- FALSE
if (nchar(Sys.getenv("GISRC")) > 0 &&
  read.dcf(Sys.getenv("GISRC"))[1,"LOCATION_NAME"] == "nc_basic_spm_grass7") run <- TRUE
GV <- Sys.getenv("GRASS_VERBOSE")
Sys.setenv("GRASS_VERBOSE"=0)
ois <- get.ignore.stderrOption()
set.ignore.stderrOption(TRUE)
#> [1] FALSE
run <- run && require("terra", quietly=TRUE)
#> terra 1.7.18
if (run) {
  v1 <- read_RAST("landuse", cat=TRUE, return_format="terra")
  v1
  inMemory(v1)
}
#> [1] FALSE
if (run) {
  write_RAST(v1, "landuse1", flags=c("o", "overwrite"))
  execGRASS("r.stats", flags="c", input="landuse1")
  execGRASS("g.remove", flags="f", name="landuse1", type="raster")
}
#> SpatRaster read into GRASS using r.in.gdal from file
#> 1 592288
#> 2 17347
#> 3 206129
#> 4 135994
#> 5 1021725
#> 6 42854
#> 7 1610
#> * 7053
Sys.setenv("_SP_EVOLUTION_STATUS_"="2")
run <- run && require("sp", quietly=TRUE)
if (run) {
  nc_basic <- read_RAST(c("geology", "elevation"), cat=c(TRUE, FALSE),
    return_format="SGDF")
  print(table(nc_basic$geology))
}
#> Warning: non-unique category labels; category number appended
#> 
#> CZfg_217 CZlg_262 CZig_270 CZbg_405 CZve_583 CZam_720  CZg_766 CZam_862 
#>   725562   198684   689373   253710    21609     4824     7074    61722 
#> CZbg_910   Km_921 CZbg_945 CZam_946 CZam_948 
#>    44964    12528        9     4068      873 
if (run) {
  execGRASS("r.stats", flags=c("c", "l", "quiet"), input="geology")
}
#> 217 CZfg 725562
#> 262 CZlg 198684
#> 270 CZig 689373
#> 405 CZbg 253710
#> 583 CZve 21609
#> 720 CZam 4824
#> 766 CZg 7074
#> 862 CZam 61722
#> 910 CZbg 44964
#> 921 Km 12528
#> 945 CZbg 9
#> 946 CZam 4068
#> 948 CZam 873
if (run) {
  boxplot(nc_basic$elevation ~ nc_basic$geology)
}

if (run) {
  nc_basic$sqdem <- sqrt(nc_basic$elevation)
}
if (run) {
  write_RAST(nc_basic, "sqdemSP", zcol="sqdem", flags=c("quiet", "overwrite"))
  execGRASS("r.info", map="sqdemSP")
}
#> SpatialGridDataFrame read into GRASS using r.in.bin
#>  +----------------------------------------------------------------------------+
#>  | Map:      sqdemSP                        Date: Fri Mar 17 16:19:50 2023    |
#>  | Mapset:   rsb                            Login of Creator: rsb             |
#>  | Location: nc_basic_spm_grass7                                              |
#>  | DataBase: /home/rsb/topics/grassdata                                       |
#>  | Title:                                                                     |
#>  | Timestamp: none                                                            |
#>  |----------------------------------------------------------------------------|
#>  |                                                                            |
#>  |   Type of Map:  raster               Number of Categories: 0               |
#>  |   Data Type:    DCELL                Semantic label: (none)                |
#>  |   Rows:         1350                                                       |
#>  |   Columns:      1500                                                       |
#>  |   Total Cells:  2025000                                                    |
#>  |        Projection: Lambert Conformal Conic                                 |
#>  |            N:     228500    S:     215000   Res:    10                     |
#>  |            E:     645000    W:     630000   Res:    10                     |
#>  |   Range of data:    min = 7.45511854848878  max = 12.5031941719687         |
#>  |                                                                            |
#>  |   Data Description:                                                        |
#>  |    generated by r.in.bin                                                   |
#>  |                                                                            |
#>  |   Comments:                                                                |
#>  |    r.in.bin --overwrite --quiet -d input="/home/rsb/topics/grassdata/nc\   |
#>  |    _basic_spm_grass7/rsb/.tmp/localhost.localdomain/X335" output="sqdem\   |
#>  |    SP" bytes=8 header=0 bands=1 order="native" north=228500 south=21500\   |
#>  |    0 east=645000 west=630000 rows=1350 cols=1500 anull=6                   |
#>  |                                                                            |
#>  +----------------------------------------------------------------------------+
#> 
if (run) {
  print(system.time(sqdemSP <- read_RAST(c("sqdemSP", "elevation"),
    return_format="SGDF")))
}
#>    user  system elapsed 
#>   0.611   0.125   0.740 
if (run) {
  print(system.time(sqdem <- read_RAST(c("sqdemSP", "elevation"),
    return_format="terra")))
}
#>    user  system elapsed 
#>   0.492   0.110   0.604 
if (run) {
  execGRASS("g.remove", flags="f", name="sqdemSP", type="raster")
  execGRASS("r.mapcalc", expression="basins0 = basins - 1", flags="overwrite")
  execGRASS("r.stats", flags="c", input="basins0")
}
#> 1 116975
#> 3 75480
#> 5 1137
#> 7 80506
#> 9 7472
#> 11 348209
#> 13 51456
#> 15 81959
#> 17 29652
#> 19 267883
#> 21 89465
#> 23 63433
#> 25 91354
#> 27 190239
#> 29 59727
#> * 470053
if (run) {
  basins0 <- read_RAST("basins0", return_format="SGDF")
  print(table(basins0$basins0))
}
#> 
#>      1      3      5      7      9     11     13     15     17     19     21 
#> 116975  75480   1137  80506   7472 348209  51456  81959  29652 267883  89465 
#>     23     25     27     29 
#>  63433  91354 190239  59727 
if (run) {
  execGRASS("g.remove", flags="f", name="basins0", type="raster")
}
Sys.setenv("GRASS_VERBOSE"=GV)
set.ignore.stderrOption(ois)
#> [1] TRUE