Merge pull request #115 from adamlilith/intuitive_fasterRaster

Add vignette on 3D objects

DESCRIPTION

@@ -1,8 +1,8 @@
 Package: fasterRaster
 Type: Package
 Title: Faster Raster and Spatial Vector Processing Using 'GRASS GIS'
-Version: 8.4.0.2
-Date: 2024-12-09
+Version: 8.4.0.4
+Date: 2024-12-16
 Authors@R: 
 	c(
 		person(
@@ -15,12 +15,12 @@ Authors@R:
 	)
 Maintainer: Adam B. Smith <[email protected]>
 Description: Processing of large-in-memory/large-on disk rasters and spatial
-	vectors using 'GRASS GIS'. Most functions in the 'terra' package are
-	recreated. Processing of medium-sized and smaller spatial objects will
-	nearly always be faster using 'terra' or 'sf', but for large-in-memory/
-	large-on-disk objects, 'fasterRaster' may be faster. To use most of the
-	functions, you must have the stand-alone version (not the 'OSGeoW4'
-	installer version) of 'GRASS GIS' 8.0 or higher.
+	vectors using 'GRASS GIS' <https://grass.osgeo.org/>. Most functions in
+	the 'terra' package are	recreated. Processing of medium-sized and smaller
+	spatial objects will nearly always be faster using 'terra' or 'sf', but
+	for large-in-memory/large-on-disk objects, 'fasterRaster' may be faster.
+	To use most of the functions, you must have the stand-alone version (not
+	the 'OSGeoW4' installer version) of 'GRASS GIS' 8.0 or higher.
 Depends:
 	R (>= 4.0.0)
 Imports:
@@ -40,7 +40,7 @@ Suggests:
     knitr,
     rmarkdown
 Roxygen: list(markdown = TRUE)
-License: GPL (>=3) + file LICENSE
+License: GPL (>=3)
 SystemRequirements: GRASS (>= 8)
 URL: https://github.com/adamlilith/fasterRaster, https://adamlilith.github.io/fasterRaster/
 BugReports: https://github.com/adamlilith/fasterRaster/issues

NEWS.md

@@ -1,5 +1,22 @@
+# fasterRaster 8.4.0.4 (2024-12-XX)
+o Added vignette "3-dimensional objects".  
+
+# fasterRaster 8.4.0.3 (2024-12-15)
+
+### Bug and issue fixes
+o Many minor fixes for CRAN submission!  
+o Comparison between a string and a categorical `GRaster` using logical operators like `<` or `==` returns a categorical raster.  
+o `as.factor()` is now properly exported.  
+o `centroids()` has the option to exit gracefully if the `addons` check fails.  
+o `crds()` now works for `GVector`s that lacked an internal **GRASS** database. Hidden function `.crds()` accepts a `cats` argument, making it potentially faster.   
+o `fast()` correctly defines region on import of raster.  
+o `mow()` example works.  
+o `spatSample()` works when sampling by `stratum`.  
+o `.rbind()` is a hidden function which accepts a `cats` argument that concatenates vectors faster than `rbind()`.   
+o Issues with some examples were fixed.  
+
 # fasterRaster 8.4.0.2 (2024-12-09)
-o Fixed issues from CRAN precheck.  
+o Fixed issues from CRAN R CMD precheck.  
 
 # fasterRaster 8.4.0.0 (2024-11-20)
 

R/00a_GLocation_class.r

@@ -1,6 +1,6 @@
 #' Classes for fasterRaster sessions, regions, rasters, and vectors
 #'
-#' @description The `G` suite of S4 classes contain pointers to **GRASS** objects or metadata about the current **GRASS** session. Most users will manipulate objects using these classes, but do not need to know the details.
+#' @description The `G`-suite of S4 classes contain pointers to **GRASS** objects or metadata about the current **GRASS** session. Most users will manipulate objects using these classes, but do not need to know the details.
 #'
 #' * The `GLocation` class stores information about the **GRASS** "project"/"location"(see `vignette("projects_mapsets", package = "fasterRaster")`), and coordinate reference system. Contained by all the rest.
 #'

R/00d_GRaster_class.r

@@ -151,15 +151,13 @@ methods::setValidity("GRaster",
 #' @param src Character (name of the raster in **GRASS) or a `rastInfo` object.
 #' @param names Character: Name of the raster.
 #' @param levels `NULL` (default), a `data.frame`, `data.table`, an empty string (`""`), or a list of `data.frame`s, `data.table`s, and/or empty strings: These become the raster's [levels()]. If `""`, then no levels are defined.
-#' @param ac vector of numeric or integer values >=1, or `NULL` (default): Active category column (offset by 1, so 1 really means the second column, 2 means the third, etc.). A value of `NULL` uses an automated procedure to figure it out.
+#' @param ac Vector of numeric/integer values >=1, or `NULL` (default): Active category column (offset by 1, so 1 really means the second column, 2 means the third, etc.). A value of `NULL` uses an automated procedure to figure it out.
 #' @param fail Logical: If `TRUE` (default), and the raster either has a 0 east-west or north-south extent, then exit the function with an error. If `fail` is `FALSE`, then display a warning and return `NULL`.
 #'
 #' @returns A `GRaster`.
 #'
 #' @seealso [.makeGVector()]
 #'
-#' @example man/examples/ex_GRaster_GVector.r
-#'
 #' @keywords internal
 .makeGRaster <- function(src, names = "raster", levels = "", ac = NULL, fail = TRUE) {
 
@@ -173,7 +171,7 @@ methods::setValidity("GRaster",
 	if (!all(.exists(src))) stop("No raster was created in GRASS. The error is likely in the calling function.")
 
 	# test for zero extent
-	if (any((info$west - info$east) == 0) | any((info$north - info$south) == 0)) {
+	if (any(abs(info$west - info$east) < omnibus::eps()) | any(abs(info$north - info$south) < omnibus::eps())) {
 		msg <- "Raster has 0 east-west extent and/or north-south extent."
 		if (fail) {
 			stop(msg)

R/00e_GVector_class.r

@@ -66,8 +66,6 @@ methods::setValidity("GVector",
 #'
 #' @seealso [.makeGRaster()]
 #'
-#' @example man/examples/ex_GRaster_GVector.r
-#'
 #' @keywords internal
 .makeGVector <- function(src, table = NULL, build = TRUE, extensive = FALSE, cats = NULL, fail = TRUE) {
 

R/01_generics.r

@@ -165,7 +165,7 @@ 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"))
 methods::setGeneric(name = "is.3d", def = function(x) standardGeneric("is.3d"))
-if (!isGeneric("is.factor")) { methods::setGeneric(name = "is.factor", def = function(x) standardGeneric("is.factor")) }
+methods::setGeneric(name = "is.factor", def = function(x) standardGeneric("is.factor"))
 # is.double() is primitive and cannot be made generic
 methods::setGeneric(name = "is.cell", def = function(x) standardGeneric("is.cell"))
 methods::setGeneric(name = "is.doub", def = function(x) standardGeneric("is.doub"))

R/02_defaults.r

@@ -11,6 +11,7 @@
 
 .coresDefault <- function() 2
 .verboseDefault <- function() FALSE
+.debugDefault <- function() FALSE
 # .cleanDefault <- function() TRUE
 .memoryDefault <- function() 2048 # in MB
 # .nAtATimeDefault <- function() 1000000 # number of indices to select at a time
@@ -28,6 +29,7 @@
 			"addonsDir",
 			# "clean",
 			"verbose",
+			"debug",
 			"cores",
 			"memory",
 			"location",
@@ -40,6 +42,7 @@
 			"character",
 			# "logical",
 			"logical",
+			"logical",
 			"numeric",
 			"numeric",
 			"character",

R/03_options.r

@@ -24,17 +24,19 @@
 #'     * 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`.
+#' * `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`.
 #'
 #' * `cores` (integer/numeric integer): Number of processor cores to use on a task. The default is 2. Some **GRASS** modules are parallelized.
 #'
 #' * `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.
 #'
 #' * `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`.
+#' * `verbose` (logical): If `TRUE`, show progress during function operations and other messages. Default is `FALSE`. This overrides the value of any `verbose` argument in a function.
 #'
-#'  * `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.
+#' * `debug` (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()]. 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`.
 #'
@@ -143,6 +145,10 @@ faster <- function(
   	# 	if (is.na(opts$clean) || !is.logical(opts$clean)) stop("Option `clean` must be a logical. The default is ", .cleanDefault(), ".")
 	# }
 
+	if (any(names(opts) %in% "debug")) {
+  		if (is.na(opts$debug) || !is.logical(opts$debug)) stop("Option `debug` must be a logical. The default is ", .debugDefault(), ".")
+	}
+
 	if (any(names(opts) %in% "verbose")) {
   		if (is.na(opts$verbose) || !is.logical(opts$verbose)) stop("Option `verbose` must be a logical. The default is ", .verboseDefault(), ".")
 	}
@@ -177,8 +183,8 @@ faster <- function(
 
 	}
 
-	if (any(names(opts) %in% "verbose")) {
-		info <- rgrass::set.echoCmdOption(.fasterRaster$options$verbose)
+	if (any(names(opts) %in% "debug")) {
+		info <- rgrass::set.echoCmdOption(.fasterRaster$options$debug)
 	}
 
 	invisible(out)

R/07_comparison.r

@@ -300,7 +300,7 @@ methods::setMethod(
 
 
 		if (length(thisVal) == 0L) {
-			this <- 0L * not.na(e1)
+			return(0L * not.na(e1))
 		} else {
 
 			if (oper == "<") {
@@ -354,7 +354,8 @@ methods::setMethod(
 		}
 
 	} # next layer
-	.makeGRaster(srcs, "logical")
+	out <- .makeGRaster(srcs, "logical", levels = cats(e1), ac = activeCats(e1))
+	out
 
 	} # EOF
 )
@@ -445,7 +446,8 @@ methods::setMethod(
 		}
 
 	} # next layer
-	.makeGRaster(srcs, "logical")
+	out <- .makeGRaster(srcs, "logical", levels = cats(e2), ac = activeCats(e2))
+	out
 
 	} # EOF
 )

R/addons.r

@@ -2,11 +2,9 @@
 #'
 #' @description This function tests to see if the "addons" directory specified using [faster()] actually exists, and if a particular **GRASS** `addons module is available. The `addons` folder and module must exists for methods that rely on particular **GRASS** `addons` to work. See `vignette("addons", package = "fasterRaster")`.
 #'
-#' @param x Either `NULL` or a character specifying the name of a **GRASS** addons module. If `NULL`, the existence of the `addonsDir` (see [faster()]) will be tested. If the module name is provided, the existence of the folder and module will be tested.
+#' @param x Either `NULL` or a character specifying the name of a **GRASS** addons module. If `NULL`, the existence of the `addonsDir` (see [faster()]) will be tested. If the module name is provided, the existence of the folder and module will be tested. The "`/bin`" subfolder should not be included.
 #'
-#' @param onFail Character: What to do if the addons folder is not found:
-#' * `"fail"` (default): Fail with a message.
-#' * `"warning"`: Warn with a message.
+#' @param fail Logical: If `TRUE` (default), and the addons folder is not correctly specified, the exit the function with an error. If `FALSE`, then `NULL` will be returned with a warning.
 #'
 #' @param verbose Logical: If `TRUE` (default), display a message on success or warning (the `fail` option always displays a message).
 #'
@@ -19,9 +17,7 @@
 #' @aliases addons
 #' @rdname addons
 #' @export
-addons <- function(x = NULL, onFail = "fail", verbose = TRUE) {
-
-	onFail <- omnibus::pmatchSafe(onFail, c("fail", "warning"), nmax = 1L)
+addons <- function(x = NULL, fail = TRUE, verbose = TRUE) {
 
 	out <- TRUE
 
@@ -30,9 +26,9 @@ addons <- function(x = NULL, onFail = "fail", verbose = TRUE) {
 
 		msg <- paste0("The `addons` folder is incorrect. See `faster()` and `vignette(", dQuote("addons", q = FALSE), ", package = ", dQuote("fasterRaster", q = FALSE), ").")
 
-		if (onFail == "fail") {
+		if (fail) {
 			stop(msg)
-		} else if (onFail == "warning" & verbose) {
+		} else if (!fail & verbose) {
 			warning(msg)
 		}
 
@@ -49,9 +45,9 @@ addons <- function(x = NULL, onFail = "fail", verbose = TRUE) {
 		if (!(x %in% extensions)) {
 
 			msg <- paste0("The addon extension `", x, "` cannot be found. See `vignette(", dQuote("addons", q = FALSE), ", package = ", dQuote("fasterRaster", q = FALSE), ").")
-			if (onFail == "fail") {
+			if (fail) {
 				stop(msg)
-			} else if (onFail == "warning" & verbose) {
+			} else if (!fail & verbose) {
 				warning(msg)
 			}
 
@@ -67,7 +63,7 @@ addons <- function(x = NULL, onFail = "fail", verbose = TRUE) {
 			if (out) {
 				omnibus::say("Addon `", x, "` is installed.")
 			} else {
-				omnibus::say("Addon `", x, "` is *not* installed.")
+				omnibus::say("Addon `", x, "` cannot be found.")
 			}
 		}
 	}

R/aggDisaggVect.r

@@ -37,7 +37,7 @@
 
 	} else if (resolve == "aggregate") {
 
-		if (verbose) omnibus::say("Fixing invalid vector by aggregating polygons. This will remove any data table.")
+		if (verbose | faster("verbose")) omnibus::say("Fixing invalid vector by aggregating polygons. This will remove any data table.")
 
 		srcIn <- src
 		src <- .makeSourceName("fast_v_extract")

R/as.contour.r

@@ -11,6 +11,8 @@
 #'
 #' @seealso [terra::as.contour()], **GRASS** manual page for module `r.contour` (see `grassHelp("r.contour")`)
 #'
+#' @returns A `GVector` representing contour lines.
+#'
 #' @example man/examples/ex_asContour.r
 #'
 #' @aliases as.contour

R/backdoor.r

@@ -13,8 +13,10 @@
 
 	faster(
 		grassDir = paste0("C:/Program Files/GRASS GIS ", verNice),
+		addonsDir = 'C:/Users/adame/AppData/Roaming/GRASS8/addons',
 		memory = 1024 * 8,
 		cores = 2,
+		useDataTable = TRUE,
 		verbose = TRUE
 	)
 	invisible(TRUE)

R/buffer.r

@@ -33,7 +33,9 @@
 #'
 #' @param dissolve Logical (`GVector`s): If `TRUE` (default), dissolve all buffers after creation. If `FALSE`, construct a buffer for each geometry. Note that overlapping buffers can cause this function to fail because it creates a topologically ambiguous polygon. Thus, using `dissolve = TRUE` is recommended.
 #'
-#' @seealso [terra::buffer()], [sf::st_buffer()], and modules `r.buffer`, `r.grow`, and `v.buffer` in **GRASS**
+#' @seealso [terra::buffer()], [sf::st_buffer()]
+#'
+#' @returns A `GRaster` or a `GVector`.
 #'
 #' @example man/examples/ex_buffer.R
 #'

R/centroids.r

@@ -21,6 +21,8 @@
 #' 
 #' Partial matching is used and case is ignored.
 #'
+#' @param fail Logical: If `TRUE` (default), and the addons folder is not correctly specified, the exit the function with an error. If `FALSE`, then `NULL` will be returned with a warning.
+#'
 #' @returns A points `GVector`.
 #'
 #' @example man/examples/ex_centroids.r
@@ -33,9 +35,10 @@
 methods::setMethod(
 	f = "centroids",
 	signature = c(x = "GVector"),
-	function(x, method = NULL) {
+	function(x, method = NULL, fail = TRUE) {
 
-	addons("v.centerpoint", verbose = FALSE)
+	ok <- addons("v.centerpoint", verbose = TRUE, fail = fail)
+	if (!ok) return(NULL)
 
 	gtype <- geomtype(x)