Merge pull request #107 from adamlilith/intuitive_fasterRaster

8.4.0.7028

.gitignore

@@ -4,6 +4,7 @@
 .Ruserdata
 docs
 \pkgdown
+\articles
 inst/doc
 junk
 /vignettes/junk

DESCRIPTION

@@ -1,8 +1,8 @@
 Package: fasterRaster
 Type: Package
 Title: Faster Raster and Spatial Vector Processing Using 'GRASS GIS'
-Version: 8.3.0.7027
-Date: 2024-10-15
+Version: 8.4.0.7028
+Date: 2024-10-24
 Authors@R: 
 	c(
 		person(

NEWS.md

@@ -1,3 +1,16 @@
+# fasterRaster 8.4.0.7028 (2024-10-24)
+
+### Main task
+o Clear for CRAN submission
+
+### Enhanced functionality and new functions
+o `grassHelp()` can show the **GRASS** manual "table of contents" (argument `"toc"`).  
+o `longlat()` can now return rasters with cell values equal to their coordinates in map units (previously, only coordinates in degrees were returned).  
+o For functions that are complicated or have extended references, added a note to the `@seealso` tag to see the respective **GRASS** manual page using `grassHelp()`.  
+
+### Bug and issue fixes
+o `project()` correctly restores the user's "location" to that of the newly projected `GRaster`.  
+
 # fasterRaster 8.4.0.7027 (2024-10-15)
 
 ### Main task for this version

R/01_generics.r

@@ -185,7 +185,7 @@ methods::setGeneric(name = "kurtosis", def = function(x, ...) standardGeneric("k
 # levels<- (in base) is primitive
 methods::setGeneric(name = "layerCor", package = "terra")
 methods::setGeneric(name = "ln", def = function(x, ...) standardGeneric("ln"))
-methods::setGeneric(name = "longlat", def = function(x) standardGeneric("longlat"))
+methods::setGeneric(name = "longlat", def = function(x, ...) standardGeneric("longlat"))
 methods::setGeneric(name = "log10p", def = function(x) standardGeneric("log10p"))
 
 methods::setGeneric(name = "mask", package = "terra")

R/07_comparison.r

@@ -42,7 +42,7 @@ methods::setMethod(
 			name <- paste0(names(e1)[i], "_", names(e2)[i])
 			src <- .makeSourceName("comparison", "raster")
 
-			ex <- paste0(src, "= int(if(", sources(e1)[i], " ", oper, " ", sources(e2)[i], "))")
+			ex <- paste0(src, "= int(if(", sources(e1)[i], oper, sources(e2)[i], "))")
 			this <- .genericArithRast(name = name, src = src, ex = ex)
 
 			if (i == 1L) {

R/addCats.r

@@ -16,7 +16,7 @@
 #'
 #' @returns A `GRaster`. The "levels" table of the raster is modified.
 #'
-#' @seealso [terra::addCats()], [combineCats()], [combineLevels()], [droplevels()], `vignette("GRasters", package = "fasterRaster"`
+#' @seealso [terra::addCats()], [concats()], [combineLevels()], [droplevels()], `vignette("GRasters", package = "fasterRaster"`
 #'
 #' @example man/examples/ex_GRaster_categorical.r
 #'

R/app.r

@@ -42,7 +42,7 @@
 #'
 #' @returns A `GRaster`.
 #'
-#' @seealso [terra::app()], [terra::lapp()], [subst()], [classify()], and modules `r.mapcalc` in **GRASS** (viewable using `grassHelp("r.mapcalc")`)
+#' @seealso [terra::app()], [terra::lapp()], [subst()], [classify()], and especially **GRASS** manual page for module `r.mapcalc` (see `grassHelp("r.mapcalc")`)
 #'
 #' @example man/examples/ex_app.r
 #'

R/as.contour.r

@@ -9,7 +9,7 @@
 #'
 #' @param levels Numeric vector: A numeric vector of values at which to calculate contour lines. Either `nlevels` or `levels` must be specified.
 #'
-#' @seealso [terra::as.contour()], module `r.contour` in **GRASS**
+#' @seealso [terra::as.contour()], **GRASS** manual page for module `r.contour` (see `grassHelp("r.contour")`)
 #'
 #' @example man/examples/ex_asContour.r
 #'

R/backdoor.r

@@ -1,6 +1,6 @@
 #' Setup fasterRaster for ABS
 #'
-#' This is a secret function to be used for faster development of **fasterRaster**. It assume development is on a Windows machine.
+#' This is a secret function to be used for faster development of **fasterRaster**. It calls [faster()] to set the install directory for **GRASS**, increases default memory, and number of cores. The function assumes development is on a Windows machine.
 #'
 #' @param ver Character: **GRASS**: e.g., "83" or "84".
 #'

R/classify.r

@@ -1,6 +1,6 @@
 #' Classify GRaster cell values
 #'
-#' @description This function classifies a raster so that cells that have values within a given range are assigned a new value. The [subst()] function is a simpler method for replacing specific values or category levels.
+#' @description This function classifies a `GRaster`` so that cells that have values within a given range are assigned a new value. The [subst()] function is a simpler method for replacing specific values or category levels.
 #'
 #' @param x A `GRaster`.
 #' @param rcl Reclassification system:

R/cleanGeom.r

@@ -19,7 +19,7 @@
 #'
 #' @param tolerance Numeric or `NULL` (default): Minimum distance in map units (degrees for unprojected, usually meters for projected) or minimum area (in meters-squared, regardless of projection).
 #'
-#' @seealso [terra::topology()], [fillHoles()], [terra::removeDupNodes()], *Details* section in [fast()], [simplifyGeom()], [smoothGeom()]
+#' @seealso [terra::topology()], [fillHoles()], [terra::removeDupNodes()], *Details* section in [fast()], [simplifyGeom()], [smoothGeom()], **GRASS** manual page for module `v.clean` (see `grassHelp("v.clean")`)
 #'
 #' @returns A `GVector`.
 #'

R/clusterPoints.r

@@ -19,6 +19,8 @@
 #'
 #' @returns A vector of integers indicating the cluster to which each point belongs.
 #'
+#' @seealso **GRASS** manual page for module `v.cluster` (see `grassHelp("v.cluster")`)
+#'
 #' @aliases clusterPoints
 #' @rdname clusterPoints
 #' @exportMethod clusterPoints

R/compositeRGB.r

@@ -14,7 +14,7 @@
 #'
 #' @example man/examples/ex_plot.r
 #'
-#' @seealso [plotRGB()], [terra::plotRGB()]
+#' @seealso [plotRGB()], [terra::plotRGB()], **GRASS** manual page for module `r.composite` (see `grassHelp("r.composite")`)
 #'
 #' @aliases compositeRGB
 #' @rdname compositeRGB

R/concats.r

@@ -25,7 +25,7 @@
 #'
 #' @example man/examples/ex_GRaster_categorical.r
 #'
-#' @seealso [combineLevels()], [terra::concats()], `vignette("GRasters", package = "fasterRaster")`
+#' @seealso [combineLevels()], [terra::concats()], `vignette("GRasters", package = "fasterRaster")`, **GRASS** manual page for module `r.cross` (see `grassHelp("r.cross")`)
 #'
 #' @aliases concats
 #' @rdname concats

R/connectors.r

@@ -7,7 +7,7 @@
 #'
 #' @returns A `GVector` with a data table that has the length of each connecting line in meters.
 #' 
-#' @seealso **GRASS** module `v.distance` (see `grassHelp("v.distance")`).
+#' @seealso **GRASS** manual for module `v.distance` (see `grassHelp("v.distance")`).
 #'
 #' @example man/examples/ex_connectors.r
 #'

R/denoise_noise.r

@@ -12,7 +12,7 @@
 #' 
 #' @returns A multi-layer `GRaster` with one layer per input.
 #' 
-#' @seealso [pca()]; [stats::prcomp()]; module `i.pca` in **GRASS**
+#' @seealso [princomp()], [stats::prcomp()], **GRASS** manual page for module `i.pca` (see `grassHelp("i.pca")`)
 #' 
 #' @example man/examples/ex_denoise_noise.r
 #' 

R/fasterRaster.r

@@ -288,7 +288,6 @@
 #' * [reorient()]: Convert degrees between 'north-orientation' and 'east orientation'
 #' * [replaceNAs()]: Replace `NA`s in columns of a `data.table` or `data.frame`, or in a vector
 #' * [seqToSQL()]: Format a numeric series into an SQL value call
-#' * [workDir()]: 
 #' * [update()]: Refresh metadata in a `GRaster` or `GVector` object
 #'
 #' ## Data objects

R/fillHoles.r

@@ -10,6 +10,8 @@
 #'
 #' @example man/examples/ex_GVector.r
 #'
+#' @seealso [terra::fillHoles()], **GRASS** manual page for module `v.fill.holes` (see `grassHelp("v.fill.holes")`)
+#'
 #' @aliases fillHoles
 #' @rdname fillHoles
 #' @exportMethod fillHoles

R/focal.r

@@ -33,7 +33,7 @@
 #'
 #' @returns A `GRaster`.
 #' 
-#' @seealso [terra::focal()], **GRASS** module `r.neighbors`
+#' @seealso [terra::focal()], **GRASS** manual page for module `r.neighbors` (see `grassHelp("r.neighbors")`)
 #' 
 #' @example man/examples/ex_focal.r
 #' 

R/fractalRast.r

@@ -14,7 +14,7 @@
 #'
 #' @example man/examples/ex_randRast.r
 #' 
-#' @seealso [rSpatialDepRast()], [rnormRast()], [runifRast()], and module `r.surf.fractal` in **GRASS**
+#' @seealso [rSpatialDepRast()], [rnormRast()], [runifRast()], **GRASS** manual page for module `r.surf.fractal` (see `grassHelp("r.surf.fractal")`)
 #'
 #' @aliases fractalRast
 #' @rdname fractalRast

R/geomorphons.r

@@ -29,7 +29,7 @@
 #'
 #' @returns A categorical `GRaster` where each geomorphon is a category (see `vignette("GRasters", package = "fasterRaster")`).
 #'
-#' @seealso **GRASS** module `r.geomorphon` (see `grassHelp("r.geomorphon")`)
+#' @seealso **GRASS** manual for module `r.geomorphon` (see `grassHelp("r.geomorphon")`)
 #'
 #' @example man/examples/ex_geomorphons.r
 #'

R/grassHelp.r

@@ -4,8 +4,8 @@
 #'
 #' @param x Character: Any of:
 #' * The name of a **GRASS** module (e.g., `"r.mapcalc"`).
-#' * `"type"`: Display a page wherein modules are classified by types.
-#' * `"topics"`: Display an index of topics.
+#' * `"toc"`: **GRASS** manual table of contents.
+#' * `"index"`: Display an index of topics.
 #'
 #' @param online Logical: If `FALSE` (default), show the manual page that was included with your installation of **GRASS** on your computer.  If `FALSE`, show the manual page online (requires an Internet connection). In either case, the manual page will display for the version of **GRASS** you have installed.
 #'
@@ -34,10 +34,10 @@ grassHelp <- function(x, online = FALSE) {
 			flags = .quiet()
 		)
 
-		if (x == "type") {
-			args$flags <- c(args$flags, "i")
-		} else if (x == "index") {
+		if (x == "index") {
 			args$flags <- c(args$flags, "t")
+		} else if (x == "toc") {
+			args$flags <- c(args$flags, "i")
 		}
 
 		do.call(rgrass::execGRASS, args = args)

R/hillshade.r

@@ -12,7 +12,7 @@
 #'
 #' @returns A `GRaster`.
 #'
-#' @seealso [terra::shade()], module `r.relief` in **GRASS**
+#' @seealso [terra::shade()]
 #' 
 #' @example man/examples/ex_terrain.r
 #' 

R/horizonHeight.r

@@ -18,7 +18,7 @@
 #'
 #' @returns A `GRaster` with one or more layers. The layers will be named `height_`*xyz*, where *xyz* is degrees from north or from east, depending on whether north or east orientation is used.
 #'
-#' @seealso The **GRASS** module `r.horizon`.
+#' @seealso **GRASS** manual page for module `r.horizon` (see `grassHelp("r.horizon")`)
 #'
 #' @example man/examples/ex_horizonHeight.r
 #' 

R/init.r

@@ -12,8 +12,6 @@
 #'
 #' @param odd Logical: If `TRUE` (default), and `fun` is `"chess"`, then the top left cell in the raster will be a "negative" cell. If `FALSE`, then the top left cell with be "positive".
 #'
-#' @param every Numeric or integer: If `fun` is `"regular"`, then make every `every` cell a "positive" cell, and interstitial cells "negative." The default is 2 (every other cell).
-#'
 #' @param vals Vector of two numeric values: If `fun` is `"chess"` or `"regular"`, then assign the first value to "positive" cells and the second value to "negative" cells. The default is `c(1, 0)`
 #'
 #' @returns A `GRaster` with as many layers as `x`.
@@ -69,7 +67,7 @@ methods::setMethod(
 		rgrass::execGRASS("r.mapcalc", expression = ex, flags = c(.quiet(), "overwrite"))
 
 	}
-	.makeGRaster(srcs, "layer")
+	.makeGRaster(srcs, fun)
 
 	} # EOF
 )

R/interpIDW.r

@@ -14,7 +14,7 @@
 #'
 #' @returns A `GRaster`.
 #'
-#' @seealso [terra::interpIDW()], [interpSplines()], [fillNAs()], **GRASS** module `v.surf.idw` (se `grasshelp("v.surf.idw")`)
+#' @seealso [terra::interpIDW()], [interpSplines()], [fillNAs()], **GRASS** module `v.surf.idw` (se `grassHelp("v.surf.idw")`)
 #'
 #' @aliases interpIDW
 #' @rdname interpIDW

R/kernel.r

@@ -28,6 +28,8 @@
 #'
 #' Otherwise, if `h` is `NULL`, then the value will be arbitrarily set at 1/5th of the shorter of the distance of the x- and y-extent of the points.
 #'
+#' @seealso **GRASS** manual page for module `v.kernel` (see `grassHelp("v.kernel")`)
+#'
 #' @returns A `GRaster`.
 #'
 #' @example man/examples/ex_kernel.r

R/longlat.r

@@ -1,8 +1,10 @@
 #' Create longitude/latitude rasters
 #' 
-#' @description `longlat()` creates two rasters, one with cell values equal to the longitude of the cell centers, and one with cell values equal to the latitude of the cell centers. Values will be in decimal degrees, regardless of the projection of the raster. If you want projected coordinates, use [init()].
+#' @description `longlat()` creates two rasters, one with cell values equal to the longitude of the cell centers, and one with cell values equal to the latitude of the cell centers.
 #' 
 #' @param x A `GRaster`.
+#'
+#' @param degrees Logical: If `TRUE` (default), coordinate values of cells will be in degrees. If `FALSE`, and `x` is in a projected coordinate reference system, values will represent coordinates in map units (usually meters). Values will always be in degrees when the coordinate reference system is unprojected (e.g., WGS84, NAD83, etc.).
 #' 
 #' @returns A `GRaster` stack.
 #'
@@ -16,18 +18,18 @@
 methods::setMethod(
     f = "longlat",
     signature(x = "GRaster"),
-    function(x) {
+    function(x, degrees = TRUE) {
 
     .locationRestore(x)
     .region(x)
-    srcs <- .longlat(x)
+    srcs <- .longlat(x, degrees = degrees)
    .makeGRaster(srcs, c("longitude", "latitude"))
 
     } # EOF
 )
 
 #' @noRd
-.longlat <- function(x) {
+.longlat <- function(x, degrees) {
 
     if (inherits(x, "GRaster")) {
         src <- sources(x)
@@ -36,19 +38,33 @@ methods::setMethod(
     }
 
     srcs <- .makeSourceName(c("longlat_long", "longlat_lat"), "raster")
-    rgrass::execGRASS(
-        cmd = "r.latlong",
-        input = src,
-        output = srcs[1L],
-        flags = c("l", .quiet(), "overwrite")
-    )
-
-    rgrass::execGRASS(
-        cmd = "r.latlong",
-        input = src,
-        output = srcs[2L],
-        flags = c(.quiet(), "overwrite")
-    )
+    if (degrees) {
+
+        rgrass::execGRASS(
+            cmd = "r.latlong",
+            input = src,
+            output = srcs[1L],
+            flags = c("l", .quiet(), "overwrite")
+        )
+
+        rgrass::execGRASS(
+            cmd = "r.latlong",
+            input = src,
+            output = srcs[2L],
+            flags = c(.quiet(), "overwrite")
+        )
+
+    } else {
+
+        # longitude
+        ex <- paste0(srcs[1L], " = col(", src, ")")
+        rgrass::execGRASS("r.mapcalc", expression = ex, flags = c(.quiet(), "overwrite"))
+
+        # latitude
+        ex <- paste0(srcs[2L], " = row(", src, ")")
+        rgrass::execGRASS("r.mapcalc", expression = ex, flags = c(.quiet(), "overwrite"))
+
+    }
     srcs
 
 }

R/mow.r

@@ -16,7 +16,7 @@
 #'
 #' @returns Invisibly returns a list with the number of rasters and vectors deleted.
 #'
-#' @seealso Option `clean` in [faster()]; [grass()]
+#' @seealso Option `clean` in [faster()]
 #'
 #' @example man/examples/ex_mow.r
 #'

R/predict.r

@@ -2,13 +2,13 @@
 #'
 #' @description This version of the `predict()` function make predictions to a set of `GRaster`s from a model object.
 #'
-#' The model must be either a linear model, which is of class `lm` and typically created using the [stats::lm()] function or a generalized linear model (GLM), which is class `glm` and typically created using [stats::glm()]. Other packages can also create `lm` or `glm` objects, but they may not work in this function. For example, generalized additive models, which can be created using the `gam()` function in the **mgcv** package, inherit the `glm` class, but cannot be used in this function, but ones created with the **speedglm** package can.
+#' The model must be either a linear model, which is of class `lm` and typically created using the [stats::lm()] function or a generalized linear model (GLM), which is class `glm` and typically created using [stats::glm()]. Other packages can also create `lm` or `glm` objects, but they may not work in this function. For example, generalized additive models, which can be created using the `gam()` function in the **mgcv** package, inherit the `glm` class, but cannot be used in this function. However, `glm` objects created with the **speedglm** package should work with this function.
 #'
 #' This `predict()` function can handle:
-#' * Linear predictors and intercepts like `y ~ 1 + x`;
-#' * Quadratic terms like `y ~ x^2` (or, in **R** formula notation, `y ~ I(x^2)`);
-#' * Two-way interaction terms between scalars like `y ~ x1:x2` and `y ~ x1 * x2`;
-#' * Categorical predictors (i.e., categorical `GRaster`s; see `vignette("GRasters", package = "fasterRaster")`));
+#' * Linear predictors and intercepts like `1 + x`;
+#' * Quadratic terms like `x^2` (or, in **R** formula notation, `I(x^2)`);
+#' * Two-way interaction terms between scalars like `x1:x2` and `x1 * x2`;
+#' * Categorical predictors (i.e., categorical `GRaster`s; see `vignette("GRasters", package = "fasterRaster")`);
 #' * Two-way interactions between a categorical predictor and a scalar predictor; and
 #' * Two-way interactions between categorical predictors.
 #'