From 46c5a613d508ec4aca68c43931475b2f16a84cd3 Mon Sep 17 00:00:00 2001 From: see24 Date: Tue, 12 Mar 2024 10:07:43 -0400 Subject: [PATCH] update docs --- DESCRIPTION | 2 +- R/projectRoads.R | 6 +++--- man/getDistFromSource.Rd | 41 ++++++++++++++++++++-------------------- man/projectRoads.Rd | 16 ++++++++-------- 4 files changed, 33 insertions(+), 32 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index f90103c..c93ee02 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -46,7 +46,7 @@ Imports: methods, tidyselect, terra -RoxygenNote: 7.2.1 +RoxygenNote: 7.2.3 Suggests: testthat (>= 2.1.0), knitr, diff --git a/R/projectRoads.R b/R/projectRoads.R index 920fa05..5b79acb 100644 --- a/R/projectRoads.R +++ b/R/projectRoads.R @@ -45,7 +45,7 @@ #' cells with a cost of 0. If existing roads do not have 0 cost set #' \code{roadsInCost = FALSE} and they will be burned in. #' @param roads sf lines, SpatialLines*, RasterLayer. Existing road network. -#' @param roadMethod Character. Options are "mst", "ilcp", "lcp", "snap". +#' @param roadMethod Character. Options are "ilcp", "mst", "lcp", "snap". #' @param plotRoads Boolean. Should the resulting road network be plotted. #' Default FALSE. #' @param mainTitle Character. A title for the plot @@ -96,14 +96,14 @@ #' #' demoScen <- prepExData(demoScen) #' -#' ### using: scenario 1 / sf landings / least-cost path ("lcp") +#' ### using: scenario 1 / sf landings / iterative least-cost path ("ilcp") #' # demo scenario 1 #' scen <- demoScen[[1]] #' #' # landing set 1 of scenario 1: #' land.pnts <- scen$landings.points[scen$landings.points$set==1,] #' -#' prRes <- projectRoads(land.pnts, scen$cost.rast, scen$road.line, "lcp", +#' prRes <- projectRoads(land.pnts, scen$cost.rast, scen$road.line, "ilcp", #' plotRoads = doPlots, mainTitle = "Scen 1: SPDF-LCP") #' #' ### using: scenario 1 / SpatRaster landings / minimum spanning tree ("mst") diff --git a/man/getDistFromSource.Rd b/man/getDistFromSource.Rd index 63683e8..e28207d 100644 --- a/man/getDistFromSource.Rd +++ b/man/getDistFromSource.Rd @@ -10,24 +10,25 @@ getDistFromSource(src, maxDist, kwidth = 3, method = "terra") \item{src}{SpatRaster or RasterLayer, where all values > 0 are treated as source locations. NA values are treated as 0s.} -\item{maxDist}{Numeric, maximum distance that should be calculated in units -of the CRS.} +\item{maxDist}{Numeric, maximum distance that should be calculated in units of +the CRS.} \item{kwidth}{Integer, for the "pfocal" and "terra" methods the width of the moving window. For the "pfocal2" method the aggregation factor.} -\item{method}{Character, the method to use, one of "terra", "pfocal" or -"pfocal2". See below for details.} +\item{method}{Character, the method to use, currently only "terra" supported +with the CRAN version, while "pfocal" or "pfocal2" are available with the +development version. See below for details.} } \value{ A SpatRaster } \description{ -This function provides three different methods for calculating the distance -of all points on a landscape from "source" locations. This is a -computationally intensive process so the function arguments can be used to -balance the tradeoffs between speed and accuracy. Note the pfocal versions -are only available in the development version of the package. +This function provides three different methods for calculating the distance of +all points on a landscape from "source" locations. This is a computationally +intensive process so the function arguments can be used to balance the +tradeoffs between speed and accuracy. Note the pfocal versions are only +available in the development version of the package. } \details{ The "terra" and "pfocal" methods use an iterative moving window approach and @@ -49,10 +50,10 @@ The third method "pfocal2" uses a global moving window to calculate the distance to the source. This means that the moving window only needs to be applied once but the window size can be very large. In this case `maxDist` determines the total size of the window. `kwidth` can be used to reduce the -number of cells included in the moving window by aggregating the source -raster by a factor of `kwidth`. This will increase the speed of computation -but will produce results with artefacts of the larger grid and which may be -less accurate since the output raster is disaggregated using bilinear +number of cells included in the moving window by aggregating the source raster +by a factor of `kwidth`. This will increase the speed of computation but will +produce results with artefacts of the larger grid and which may be less +accurate since the output raster is disaggregated using bilinear interpolation. } \examples{ @@ -65,17 +66,17 @@ getDistFromSource(CLUSexample$roads, 5, 2) library(terra) #make example roads from scratch -rds <- data.frame(x = 1:1000/100, y = cos(1:1000/100)) \%>\% - st_as_sf(coords = c("x", "y")) \%>\% - st_union() \%>\% +rds <- data.frame(x = 1:1000/100, y = cos(1:1000/100)) \%>\% + st_as_sf(coords = c("x", "y")) \%>\% + st_union() \%>\% st_cast("LINESTRING") -rds_rast <- rasterize(vect(rds), - rast(nrows = 50, ncols = 50, - xmin = 0, xmax = 10, +rds_rast <- rasterize(vect(rds), + rast(nrows = 50, ncols = 50, + xmin = 0, xmax = 10, ymin = -5, ymax = 5), touches = TRUE) - + getDistFromSource(rds_rast, 5, 2) } } diff --git a/man/projectRoads.Rd b/man/projectRoads.Rd index bde39e3..e74f3ac 100644 --- a/man/projectRoads.Rd +++ b/man/projectRoads.Rd @@ -10,7 +10,7 @@ projectRoads( landings = NULL, cost = NULL, roads = NULL, - roadMethod = "mst", + roadMethod = "ilcp", plotRoads = FALSE, mainTitle = "", neighbourhood = "octagon", @@ -24,7 +24,7 @@ projectRoads( landings = NULL, cost = NULL, roads = NULL, - roadMethod = "mst", + roadMethod = "ilcp", plotRoads = FALSE, mainTitle = "", neighbourhood = "octagon", @@ -38,7 +38,7 @@ projectRoads( landings = NULL, cost = NULL, roads = NULL, - roadMethod = "mst", + roadMethod = "ilcp", plotRoads = FALSE, mainTitle = "", neighbourhood = "octagon", @@ -60,7 +60,7 @@ cells with a cost of 0. If existing roads do not have 0 cost set \item{roads}{sf lines, SpatialLines*, RasterLayer. Existing road network.} -\item{roadMethod}{Character. Options are "mst", "dlcp", "lcp", "snap".} +\item{roadMethod}{Character. Options are "ilcp", "mst", "lcp", "snap".} \item{plotRoads}{Boolean. Should the resulting road network be plotted. Default FALSE.} @@ -88,7 +88,7 @@ is assumed to include existing roads as 0 in its cost surface. If FALSE then the roads will be "burned in" to the cost raster with a cost of 0.} \item{ordering}{character. The order in which roads should be built to -landings when `roadMethod = "dlcp"`. Options are "closest" (default) where +landings when `roadMethod = "ilcp"`. Options are "closest" (default) where landings closest to existing roads are accessed first, or "none" where landings are accessed in the order they are provided in.} } @@ -118,7 +118,7 @@ Four different methods for projecting road networks have been implemented: \item{"lcp":} {Least Cost Path connects each landing to the closest point on the road by determining the least cost path based on the cost surface provided, it does not consider other landings} - \item{"dlcp":} {Dynamic Least Cost Path, same as "lcp" but it builds each + \item{"ilcp":} {Iterative Least Cost Path, same as "lcp" but it builds each path sequentially so that later roads will use earlier roads. The sequence of landings is determined by `ordering` and is "closest" by default, the other option is "none" which will use the order that landings are supplied @@ -141,14 +141,14 @@ projectRoads(CLUSexample$landings, CLUSexample$cost, CLUSexample$roads, demoScen <- prepExData(demoScen) -### using: scenario 1 / sf landings / least-cost path ("lcp") +### using: scenario 1 / sf landings / iterative least-cost path ("ilcp") # demo scenario 1 scen <- demoScen[[1]] # landing set 1 of scenario 1: land.pnts <- scen$landings.points[scen$landings.points$set==1,] -prRes <- projectRoads(land.pnts, scen$cost.rast, scen$road.line, "lcp", +prRes <- projectRoads(land.pnts, scen$cost.rast, scen$road.line, "ilcp", plotRoads = doPlots, mainTitle = "Scen 1: SPDF-LCP") ### using: scenario 1 / SpatRaster landings / minimum spanning tree ("mst")