Merge pull request #106 from adamlilith/intuitive_fasterRaster

Upgrade to **GRASS** 8.4

.Rbuildignore

@@ -19,3 +19,5 @@ CODE_OF_CONDUCT.md
 ^\vignettes\^junk
 junk
 fasterRaster_workspace.code-workspace
+^doc$
+^Meta$

.gitignore

@@ -7,3 +7,5 @@ docs
 inst/doc
 junk
 /vignettes/junk
+/doc/
+/Meta/

DESCRIPTION

@@ -1,8 +1,8 @@
 Package: fasterRaster
 Type: Package
 Title: Faster Raster and Spatial Vector Processing Using 'GRASS GIS'
-Version: 8.3.0.7026
-Date: 2024-09-22
+Version: 8.3.0.7027
+Date: 2024-10-15
 Authors@R: 
 	c(
 		person(
@@ -41,10 +41,10 @@ Suggests:
 Roxygen: list(markdown = TRUE)
 License: GPL (>=3) + file LICENSE
 SystemRequirements: GRASS (>= 8)
-URL: http://www.earthSkySea.org, https://adamlilith.github.io/fasterRaster/
+URL: https://github.com/adamlilith/fasterRaster, https://adamlilith.github.io/fasterRaster/
 BugReports: https://github.com/adamlilith/fasterRaster/issues
 VignetteBuilder: knitr
 Encoding: UTF-8
 LazyData: true
 LazyLoad: yes
-RoxygenNote: 7.3.1
+RoxygenNote: 7.3.2

NAMESPACE

@@ -3,6 +3,7 @@
 export(appFuns)
 export(fastData)
 export(faster)
+export(grassHelp)
 export(grassInfo)
 export(grassStarted)
 export(is.polygons)
@@ -32,6 +33,7 @@ exportMethods("addCats<-")
 exportMethods("addTable<-")
 exportMethods("levels<-")
 exportMethods("names<-")
+exportMethods(.workDir)
 exportMethods(Arith)
 exportMethods(Compare)
 exportMethods(E)
@@ -45,6 +47,8 @@ exportMethods(activeCat)
 exportMethods(activeCats)
 exportMethods(addCats)
 exportMethods(aggregate)
+exportMethods(allNA)
+exportMethods(anyNA)
 exportMethods(app)
 exportMethods(appCheck)
 exportMethods(as.contour)
@@ -73,11 +77,11 @@ exportMethods(classify)
 exportMethods(clump)
 exportMethods(clusterPoints)
 exportMethods(colbind)
-exportMethods(combineCats)
 exportMethods(combineLevels)
 exportMethods(compareGeom)
 exportMethods(complete.cases)
 exportMethods(compositeRGB)
+exportMethods(concats)
 exportMethods(connectors)
 exportMethods(convHull)
 exportMethods(cos)
@@ -117,13 +121,14 @@ exportMethods(freq)
 exportMethods(geomorphons)
 exportMethods(geomtype)
 exportMethods(global)
+exportMethods(grassGUI)
 exportMethods(grid)
 exportMethods(head)
 exportMethods(hexagons)
 exportMethods(hillshade)
 exportMethods(hist)
 exportMethods(horizonHeight)
-exportMethods(intercept)
+exportMethods(init)
 exportMethods(interpIDW)
 exportMethods(interpSplines)
 exportMethods(intersect)
@@ -178,18 +183,18 @@ exportMethods(nrow)
 exportMethods(nsubgeom)
 exportMethods(nunique)
 exportMethods(pairs)
-exportMethods(pca)
 exportMethods(plot)
 exportMethods(plotRGB)
 exportMethods(predict)
+exportMethods(princomp)
 exportMethods(project)
 exportMethods(quantile)
-exportMethods(r2)
 exportMethods(rSpatialDepRast)
 exportMethods(range)
 exportMethods(rast)
 exportMethods(rasterize)
 exportMethods(rbind)
+exportMethods(regress)
 exportMethods(remove0)
 exportMethods(removeAngles)
 exportMethods(removeBridges)
@@ -211,13 +216,13 @@ exportMethods(sampleRast)
 exportMethods(scale)
 exportMethods(scalepop)
 exportMethods(sdpop)
+exportMethods(segregate)
 exportMethods(selectRange)
 exportMethods(show)
 exportMethods(simplifyGeom)
 exportMethods(sin)
 exportMethods(sineRast)
 exportMethods(skewness)
-exportMethods(slope)
 exportMethods(smoothGeom)
 exportMethods(snap)
 exportMethods(sources)
@@ -229,6 +234,7 @@ exportMethods(st_crs)
 exportMethods(stdev)
 exportMethods(streams)
 exportMethods(stretch)
+exportMethods(subset)
 exportMethods(subst)
 exportMethods(sum)
 exportMethods(summary)
@@ -242,7 +248,6 @@ exportMethods(top)
 exportMethods(topology)
 exportMethods(trim)
 exportMethods(trunc)
-exportMethods(tvalue)
 exportMethods(union)
 exportMethods(unscale)
 exportMethods(update)
@@ -254,7 +259,6 @@ exportMethods(voronoi)
 exportMethods(wetness)
 exportMethods(which.max)
 exportMethods(which.min)
-exportMethods(workDir)
 exportMethods(writeRaster)
 exportMethods(writeVector)
 exportMethods(xor)

NEWS.md

@@ -1,3 +1,42 @@
+# fasterRaster 8.4.0.7027 (2024-10-15)
+
+### Main task for this version
+o Test examples with **GRASS 8.4** and update functions as needed. Upgrade to **fasterRaster** 8.4.X.X.  
+
+### Updates for **GRASS 8.4**
+o `addLocationProject()` adds either a `project` or `location` argument to a `list` to be passed to `rgrass::execGRASS()`.  
+o `project()` work with **GRASS** 8.4.  
+o `.vAttachDatabase()` no longer has the `"o"` flag when calling `v.db.connect` when running **GRASS** >=8.4.  
+
+### Potentially code-breaking changes
+o `aggregate()` no longer has the `dissolve` argument for `GVector`s (polygons will always be dissolved).  
+o `combineCats()` has been renamed `concats()` to align with **terra**.  
+o `intercept()`, `slope()`, `r2()`, and `tvalue()` have been replaced by the single function `regress()` to align with **terra**.  
+o `pca()` has been renamed `princomp()`.  
+
+### Enhanced functionality and new functions
+o `extract()` now automatically projects a `GVector` to match the CRS of a `GRaster` from which extraction is being made.  
+o `grassGUI()` allows users to start the **GRASS** GUI.  
+o `grassHelp()` shows the manual page for a **GRASS** module.  
+o `layerIndex()` allows a `negate` argument to get the "opposite" indices of a `GRaster`.  
+o `init()` assigns to `GRaster` cells the value of their coordinates, rows, columns, or values in a regular or chessboard-like pattern.  
+o `regress()` replaces individual functions `intercept()`, `slope()`, `r2()`, and `tvalue()`.  
+o `subset()` subsets layers of a `GRaster` or rows/geometries of a `GVector`.  
+o `segregate()` creates one layer per unique value in an input `GRaster`, with values in the output coded 1 or 0 depending on whether cells in the input had the unique value or not.  
+
+### Bug and issue fixes
+o `appFuns()` succeeds in opening a **shiny** table with `app()` functions.  
+o `categories()` correctly assigns active category column.  
+o `crds()` correctly returns coordinates from a "points" `GVector`.  
+o `distance()` correctly parses distance matrix.  
+o `simplifyGeom()` works for 2-dimensional `GVector`s.  
+o `flow()` creates a scratch folder when none is provided.  
+o `global()` does not fail when multiple values of `fun` and `probs` are used and `fun` includes `quantile`.  
+o `rasterize()` works when `by` is not `NULL`.  
+o `.layerIndex()` (called by `categories()` and other functions related to categorical `GRaster`s) does not fail.  
+o `.vHasDatabase()` correctly detects if a vector has a database attached to it.  
+o Removed all instances of `sQuote()`.  
+
 # fasterRaster 8.3.0.7026 (2024-09-22)
 
 o Recompile `pkgdown`  

R/00b_GSpatial_class.r

@@ -29,9 +29,9 @@ methods::setValidity("GSpatial",
 		} else if (length(object@crs) != 1L) {
 			"@crs can only be a single character string."
 		} else if (!all(object@topology %in% c(NA_character_, "2D", "3D"))) {
-			paste0("@topology can only be a NA, ", sQuote("2D"), ", or ", sQuite("3D"), ".")
+			paste0("@topology can only be a NA, `2D` or `3D`.")
 		} else if (object@topology == "3D" && any(is.na(object@zextent))) {
-			paste0("@topology is ", sQuote("3D"), " but @zextent has at least one NA value.")
+			paste0("@topology is `3D` but @zextent has at least one NA value.")
 		} else if (!anyNA(object@zextent[1L]) & is.na(object@zextent[2L]) | (is.na(object@zextent[1L]) & !is.na(object@zextent[2L]))) {
 			"Both values of @zextent must be NA or must be numeric values."
 		} else if (!anyNA(object@zextent) && object@zextent[2L] < object@zextent[1L]) {

R/00c_GRegion_class.r

@@ -1,4 +1,4 @@
-#' @title Classes for "fasterRaster" locations, rasters, and vectors#'
+#' @title Classes for "fasterRaster" locations, rasters, and vectors
 #'
 #' @aliases GRegion
 #' @rdname GLocation

R/00d_GRaster_class.r

@@ -113,7 +113,7 @@ GRaster <- methods::setClass(
 methods::setValidity("GRaster",
 	function(object) {
 		if (!all(object@datatypeGRASS %in% c("CELL", "FCELL", "DCELL"))) {
-			paste0("@datatypeGRASS can only be NA, ", sQuote("CELL"), ", ", sQuote("FCELL"), ", or ", sQuote("DCELL"), ".")
+			paste0("@datatypeGRASS can only be NA, ``CELL`, `FCELL`, or `DCELL`.")
 		} else if (!is.na(object@dimensions[3L]) && object@dimensions[3L] <= 0L) {
 			"Third value in @dimensions must be NA or a positive integer."
 		} else if (!is.na(object@resolution[3L]) && object@resolution[3L] <= 0) {

R/00e_GVector_class.r

@@ -31,9 +31,9 @@ methods::setValidity("GVector",
 		if (!info$catsValid) {
 			"Vector has invalid topology. See the *Details* section in `fast()` on how to correct topology."
 		} else if (!all(object@geometry %in% c(NA_character_, "points", "lines", "polygons"))) {
-			paste0("@geometry can only be NA, ", sQuote("points"), ", ", sQuote("lines"), ", or ", sQuote("polygons"), ".")
+			paste0("@geometry can only be NA, `points`, `lines`, or `polygons`.")
 		# } else if (length(unique(.vCats(object)) != object@nGeometries)) {
-			# "The number of @nGeometries is not the same as the number of unique ", sQuote("cat"), " values in the vector attribute table in GRASS."
+			# "The number of @nGeometries is not the same as the number of unique `cat` values in the vector attribute table in GRASS."
 		# } else if (object@nGeometries > object@nSubgeometries) {
 			# "The number of sub-geometries in @nSubgeometries must be <= the number of geometries in @nGeometries."
 		} else if (object@nGeometries == 0L) {

R/01_generics.r

@@ -64,6 +64,8 @@ methods::setGeneric(name = "addCats", package = "terra")
 methods::setGeneric(name = "addCats<-", def = function(x, ..., value) standardGeneric("addCats<-"))
 methods::setGeneric(name = "addTable<-", def = function(x, ..., value) standardGeneric("addTable<-"))
 # methods::setGeneric(name = "andAndAnd", def = function(e1, e2) standardGeneric("andAndAnd"))
+methods::setGeneric(name = "allNA", package = "terra")
+# anyNA: generic is implicit
 methods::setGeneric(name = "app", package = "terra")
 # methods::setGeneric(name = "appFuns", def = function(x, ...) standardGeneric("appFuns"))
 methods::setGeneric(name = "appCheck", def = function(x, fun, ...) standardGeneric("appCheck"))
@@ -102,8 +104,8 @@ methods::setGeneric(name = "clusterPoints", def = function(x, ...) standardGener
 methods::setGeneric(name = "compareGeom", package = "terra")
 methods::setGeneric("complete.cases", function(...) standardGeneric("complete.cases"), package = "stats")
 methods::setGeneric(name = "compositeRGB", def = function(r, ...) standardGeneric("compositeRGB"))
-methods::setGeneric(name = "combineCats", def = function(x, ...) standardGeneric("combineCats"))
 methods::setGeneric(name = "combineLevels", def = function(x, ...) standardGeneric("combineLevels"))
+methods::setGeneric(name = "concats", def = function(x, ...) standardGeneric("concats"))
 methods::setGeneric(name = "connectors", def = function(x, y, ...) standardGeneric("connectors"))
 methods::setGeneric(name = "convHull", package = "terra")
 methods::setGeneric(name = "count", def = function(x, ...) standardGeneric("count"))
@@ -147,6 +149,7 @@ methods::setGeneric(name = "fragmentation", def = function(x, ...) standardGener
 methods::setGeneric(name = "geomtype", package = "terra")
 methods::setGeneric(name = "geomorphons", def = function(x, ...) standardGeneric("geomorphons"))
 methods::setGeneric(name = "global", package = "terra")
+methods::setGeneric(name = "grassGUI", def = function(x, ...) standardGeneric("grassGUI"))
 methods::setGeneric(name = "grid", def = function(x, ...) standardGeneric("grid"))
 
 methods::setGeneric(name = "head", package = "utils")
@@ -155,8 +158,8 @@ methods::setGeneric(name = "hillshade", def = function(x, ...) standardGeneric("
 methods::setGeneric(name = "hist", package = "terra")
 methods::setGeneric(name = "horizonHeight", def = function(x, ...) standardGeneric("horizonHeight"))
 
+methods::setGeneric(name = "init", package = "terra")
 methods::setGeneric(name = "intersect", package = "terra")
-methods::setGeneric(name = "intercept", def = function(x, ...) standardGeneric("intercept"))
 methods::setGeneric(name = "interpIDW", package = "terra")
 methods::setGeneric(name = "interpSplines", def = function(x, y, ...) standardGeneric("interpSplines"))
 methods::setGeneric(name = "is.2d", def = function(x) standardGeneric("is.2d"))
@@ -218,17 +221,15 @@ methods::setGeneric(name = "nunique", def = function(x, ...) standardGeneric("nu
 methods::setGeneric(name = "reorient", def = function(x, ...) standardGeneric("reorient"))
 
 methods::setGeneric(name = "pairs", package = "terra")
-methods::setGeneric(name = "pca", def = function(x, ...) standardGeneric("pca"))
 methods::setGeneric(name = "plot", package = "terra")
 methods::setGeneric(name = "plotRGB", package = "terra")
 methods::setGeneric(name = "predict", package = "terra")
-# methods::setGeneric(name = "print", def = function(x, ...) standardGeneric("print")) # base
+methods::setGeneric(name = "princomp", package = "terra")
 methods::setGeneric(name = "print") # base
 methods::setGeneric(name = "project", package = "terra")
 
 methods::setGeneric(name = "quantile", package = "terra")
 
-methods::setGeneric(name = "r2", def = function(x, ...) standardGeneric("r2"))
 methods::setGeneric(name = "rast", package = "terra")
 methods::setGeneric(name = "rasterize", package = "terra")
 # methods::setGeneric(name = "rbind")
@@ -237,6 +238,7 @@ methods::setGeneric(name = "rasterize", package = "terra")
 methods::getGeneric("rbind")
 methods::setGeneric(name = "rbind", signature = "...")
 
+methods::setGeneric(name = "regress", package = "terra")
 methods::setGeneric(name = "remove0", def = function(x, ...) standardGeneric("remove0"))
 methods::setGeneric(name = "removeAngles", def = function(x, ...) standardGeneric("removeAngles"))
 methods::setGeneric(name = "removeBridges", def = function(x, ...) standardGeneric("removeBridges"))
@@ -259,12 +261,12 @@ methods::setGeneric(name = "scale", package = "terra")
 methods::setGeneric(name = "scalepop", def = function(x, ...) standardGeneric("scalepop"))
 methods::setGeneric(name = "sdpop", def = function(x, ...) standardGeneric("sdpop"))
 methods::setGeneric(name = "selectRange", def = function(x, ...) standardGeneric("selectRange"))
+methods::setGeneric(name = "segregate", def = function(x, ...) standardGeneric("segregate"))
 methods::setGeneric(name = "show", package = "methods")
 methods::setGeneric(name = "simplifyGeom", package = "terra")
 methods::setGeneric(name = "sineRast", def = function(x, ...) standardGeneric("sineRast"))
 methods::setGeneric(name = "smoothGeom", def = function(x, ...) standardGeneric("smoothGeom"))
 methods::setGeneric(name = "skewness", def = function(x, ...) standardGeneric("skewness"))
-methods::setGeneric(name = "slope", def = function(x, ...) standardGeneric("slope"))
 methods::setGeneric(name = "snap", package = "terra")
 methods::setGeneric(name = "sources", package = "terra")
 methods::setGeneric(name = "spatSample", package = "terra")
@@ -278,6 +280,7 @@ methods::setGeneric(name = "st_buffer", package = "sf")
 methods::setGeneric(name = "st_crs", package = "sf")
 # methods::setGeneric(name = "st_distance", package = "sf")
 methods::setGeneric(name = "stdev", package = "terra")
+methods::setGeneric(name = "subset", package = "terra")
 methods::setGeneric(name = "subst", package = "terra")
 methods::setGeneric(name = "summary", def = function(object, ...) standardGeneric("summary"))
 
@@ -288,7 +291,6 @@ methods::setGeneric(name = "tiles", def = function(x, ...) standardGeneric("tile
 methods::setGeneric(name = "top", def = function(x, ...) standardGeneric("top"))
 methods::setGeneric(name = "topology", def = function(x, ...) standardGeneric("topology"))
 methods::setGeneric(name = "trim", package = "terra")
-methods::setGeneric(name = "tvalue", def = function(x, ...) standardGeneric("tvalue"))
 
 methods::setGeneric(name = "update", package = "terra")
 methods::setGeneric(name = "union", package = "terra")
@@ -299,9 +301,9 @@ methods::setGeneric(name = "vegIndex", def = function(x, ...) standardGeneric("v
 methods::setGeneric(name = "vect", package = "terra")
 methods::setGeneric(name = "voronoi", package = "terra")
 
+methods::setGeneric(name = ".workDir", def = function(x, ...) standardGeneric(".workDir"))
 methods::setGeneric(name = "W", def = function(x, ...) standardGeneric("W"))
 methods::setGeneric(name = "wetness", def = function(x, ...) standardGeneric("wetness"))
-methods::setGeneric(name = "workDir", def = function(x, ...) standardGeneric("workDir"))
 methods::setGeneric(name = "writeRaster", package = "terra")
 methods::setGeneric(name = "writeVector", package = "terra")
 

R/02_defaults.r

@@ -3,7 +3,8 @@
 # global PUBLIC options
 .grassDirDefault <- function() NA_character_
 .addonsDirDefault <- function() NA_character_
-.workDirDefault <- function() file.path(omnibus::forwardSlash(tempdir()))
+# .workDirDefault <- function() file.path(omnibus::forwardSlash(tempdir()), omnibus::rstring(1))
+.workDirDefault <- function() omnibus::forwardSlash(tempdir())
 
 .locationDefault <- function() "default"
 # .mapsetDefault <- function() "PERMANENT"

R/03_options.r

@@ -18,8 +18,8 @@
 #' Options include:
 #'
 #' * `grassDir` (character): The folder in which **GRASS** is installed on your computer. Typically, this option is set when you run [faster()]. Depending on your operating system, your install directory will look something like this:
-#'     * Windows: `"C:/Program Files/GRASS GIS 8.3"`
-#'     * Mac OS: `"/Applications/GRASS-8.3.app/Contents/Resources"`
+#'     * Windows: `"C:/Program Files/GRASS GIS 8.4"`
+#'     * Mac OS: `"/Applications/GRASS-8.4.app/Contents/Resources"`
 #'     * Linux: `"/usr/local/grass"`
 #'
 #' *  `addonsDir` (character): Folder in which **GRASS** addons are stored. If `NA` and `grassDir` is not `NA`, this will be assumed to be `file.path(grassDir, "addons")`. The default values is `NA`.
@@ -28,13 +28,13 @@
 #'
 #' * `memory` (integer/numeric): The amount of memory to allocate to a task, in GB, for **GRASS**. The default is 2048 MB (i.e., 2 GB). Some **GRASS** modules can take advantage of more memory.
 #'
-#' * `clean` (logical): If `TRUE` (default), remove temporary files created internally by functions. If not deleted, they can eventually fill up hard drive space, but deleting them takes a little bit of time (usually <1 second for each function).
+#' * `clean` (logical): If `TRUE` (default), remove temporary files created internally by functions. If not deleted, they can eventually fill up hard drive space, but deleting them takes a little bit of time (usually <1 second for each function). See also [mow()].
 #'
 #' * `useDataTable` (logical): If `FALSE` (default), functions that return tabular output produce `data.frame`s. If `TRUE`, output will be `data.table`s from the **data.table** package. This can be much faster, but it might require you to know how to use `data.table`s if you want to manipulate them in **R**. You can always convert them to `data.frame`s using [base::as.data.frame()].
 #' 
 #' * `verbose` (logical): If `TRUE`, show **GRASS** messages and otherwise hidden slots in classes. This is mainly used for debugging, so most users will want to keep this at its default, `FALSE`.
 #'
-#'  * `workDir` (character): The folder in which **GRASS** rasters, vectors, and other objects are created and manipulated. By default, this is given by [tempdir()].
+#'  * `workDir` (character): The folder in which **GRASS** rasters, vectors, and other objects are created and manipulated. By default, this is given by [tempdir()]. Note that on some systems, changing the default folder to somewhere else can cause problems with **fasterRaster** being able to find rasters in **GRASS** that have been created.
 #'
 #' @param restore Logical: If `TRUE`, the all options will be reset to their default values. The default is `FALSE`.
 #'

R/04_arithmetic.r

@@ -12,7 +12,7 @@
 #'
 #' @return A `GRaster`.
 #'
-#' @example man/examples/ex_GRaster_arithmetic.r
+#' @example man/examples/ex_GRaster_arithmetic_by_layer.r
 #'
 #' @aliases Arith
 #' @rdname Arithmetic

R/05_GRaster_functions_byLayer.r → R/05_GRaster_functions_by_layer.r

@@ -41,7 +41,7 @@
 #'
 #' @returns A `GRaster`.
 #'
-#' @example man/examples/ex_GRaster_arithmetic.r
+#' @example man/examples/ex_GRaster_arithmetic_by_layer.r
 #'
 #' @aliases is.na
 #' @rdname math