From 7a8cdc519828aae10ca7d4d4bf3e20a2ca11683f Mon Sep 17 00:00:00 2001
From: Robin Lovelace <rob00x@gmail.com>
Date: Mon, 30 Aug 2021 21:39:19 +0100
Subject: [PATCH] Add @return values for #32

---
 NAMESPACE                |  1 +
 R/plot_slope.R           |  1 +
 R/slope_get.R            |  2 ++
 R/slopes.R               | 55 +++++++++++++++++++++++++++++++++++-----
 R/z.R                    |  3 ++-
 man/elevation_add.Rd     |  5 ++++
 man/elevation_extract.Rd |  3 +++
 man/elevation_get.Rd     |  4 +++
 man/plot_dz.Rd           |  3 +++
 man/plot_slope.Rd        |  3 +++
 man/sequential_dist.Rd   | 10 +++++++-
 man/slope_matrix.Rd      | 16 ++++++++++++
 man/slope_raster.Rd      |  4 +++
 man/slope_vector.Rd      | 11 ++++++++
 man/slope_xyz.Rd         |  4 +++
 man/z_value.Rd           |  4 +++
 16 files changed, 120 insertions(+), 9 deletions(-)

diff --git a/NAMESPACE b/NAMESPACE
index dc9ceb2..eece4ff 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -9,6 +9,7 @@ export(slope_distance)
 export(slope_distance_mean)
 export(slope_distance_weighted)
 export(slope_matrix)
+export(slope_matrix_mean)
 export(slope_matrix_weighted)
 export(slope_raster)
 export(slope_vector)
diff --git a/R/plot_slope.R b/R/plot_slope.R
index c6b76b8..ce449bf 100644
--- a/R/plot_slope.R
+++ b/R/plot_slope.R
@@ -22,6 +22,7 @@
 #' @inheritParams sequential_dist
 #'
 #' @export
+#' @return A plot showing the elevation profile associated with a linestring.
 #' @examples
 #' plot_slope(lisbon_route_3d)
 #' route_xyz = lisbon_road_segment_3d
diff --git a/R/slope_get.R b/R/slope_get.R
index c91015d..1fb4d70 100644
--- a/R/slope_get.R
+++ b/R/slope_get.R
@@ -12,6 +12,8 @@
 #'
 #' @param ... Options passed to `cc_elevation()`
 #' @inheritParams slope_raster
+#' @return A raster object with cell values representing elevations in the
+#'   bounding box of the input `routes` object.
 #' @export
 #' @examples
 #' # Time-consuming examples that require an internet connection and API key:
diff --git a/R/slopes.R b/R/slopes.R
index 4d044ff..36d19b1 100644
--- a/R/slopes.R
+++ b/R/slopes.R
@@ -21,6 +21,15 @@
 #' @param x Vector of locations
 #' @param d Vector of distances between points
 #' @param elevations Elevations in same units as x (assumed to be metres)
+#' @return A vector of slope gradients associated with each linear element
+#'   (each line between consecutive vertices) associated with linear features.
+#'   Returned values for `slope_distance_mean()` and
+#'   `slope_distance_mean_weighted()` are summary statistics for all
+#'   linear elements in the linestring.
+#'   The output value is a proportion representing the change in elevation
+#'   for a given change in horizontal movement along the linestring.
+#'   0.02, for example, represents a low gradient of 2% while 0.08 represents
+#'   a steep gradient of 8%.
 #' @export
 #' @examples
 #' x = c(0, 2, 3, 4, 5, 9)
@@ -63,12 +72,23 @@ slope_distance_weighted = function(d, elevations) {
 #' @param m Matrix containing coordinates and elevations
 #' @inheritParams slope_vector
 #' @inheritParams sequential_dist
+#' @return A vector of slope gradients associated with each linear element
+#'   (each line between consecutive vertices) associated with linear features.
+#'   Returned values for `slope_matrix_mean()` and
+#'   `slope_matrix_weighted()` are summary statistics for all
+#'   linear elements in the linestring.
+#'   The output value is a proportion representing the change in elevation
+#'   for a given change in horizontal movement along the linestring.
+#'   0.02, for example, represents a low gradient of 2% while 0.08 represents
+#'   a steep gradient of 8%.
 #' @export
 #' @examples
 #' x = c(0, 2, 3, 4, 5, 9)
 #' y = c(0, 0, 0, 0, 0, 9)
 #' z = c(1, 2, 2, 4, 3, 1) / 10
 #' m = cbind(x, y, z)
+#' slope_matrix_weighted(m, lonlat = FALSE)
+#' slope_matrix_mean(m, lonlat = FALSE)
 #' plot(x, z, ylim = c(-0.5, 0.5), type = "l")
 #' (gx = slope_vector(x, z))
 #' (gxy = slope_matrix(m, lonlat = FALSE))
@@ -85,6 +105,13 @@ slope_matrix = function(m, elevations = m[, 3], lonlat = TRUE) {
 }
 #' @rdname slope_matrix
 #' @export
+slope_matrix_mean = function(m, elevations = m[, 3], lonlat = TRUE) {
+  g1 = slope_matrix(m, elevations = elevations, lonlat = lonlat)
+  d = sequential_dist(m = m, lonlat = lonlat)
+  mean(abs(g1), na.rm = TRUE)
+}
+#' @rdname slope_matrix
+#' @export
 slope_matrix_weighted = function(m, elevations = m[, 3], lonlat = TRUE) {
   g1 = slope_matrix(m, elevations = elevations, lonlat = lonlat)
   d = sequential_dist(m = m, lonlat = lonlat)
@@ -99,12 +126,18 @@ slope_matrix_weighted = function(m, elevations = m[, 3], lonlat = TRUE) {
 #'
 #' @param lonlat Are the coordinates in lon/lat (geographic) coordinates? TRUE by default.
 #' @inheritParams slope_matrix
+#' @return A vector of distance values in meters if `lonlat = TRUE`
+#'   or the map units of the input data if `lonlat = FALSE` between
+#'   consecutive vertices.
 #' @export
 #' @examples
 #' x = c(0, 2, 3, 4, 5, 9)
 #' y = c(0, 0, 0, 0, 0, 1)
 #' m = cbind(x, y)
-#' sequential_dist(m)
+#' d = sequential_dist(m, lonlat = FALSE)
+#' d
+#' nrow(m)
+#' length(d)
 sequential_dist = function(m, lonlat = TRUE) {
   if(lonlat) {
     geodist::geodist(m[, 1:2], sequential = TRUE) # lon lat
@@ -146,6 +179,8 @@ slope_matrices = function(m_xyz_split, fun = slope_matrix_weighted, ...) {
 #' @param fun The slope function to calculate per route,
 #'   `slope_matrix_weighted` by default.
 #' @importFrom methods is
+#' @return A vector of slopes equal in length to the number simple features
+#'   (rows representing linestrings) in the input object.
 #' @export
 #' @examples
 #' routes = lisbon_road_network[1:3, ]
@@ -182,7 +217,8 @@ slope_raster = function(
 #' @param route_xyz An sf object with x, y, z dimensions
 #' @param lonlat Are the coordinates in lon/lat order? TRUE by default
 #' @inheritParams slope_raster
-#'
+#' @return A vector of slopes equal in length to the number simple features
+#'   (rows representing linestrings) in the input object.
 #' @export
 #' @examples
 #' route_xyz = lisbon_road_segment_3d
@@ -207,6 +243,7 @@ slope_xyz = function(route_xyz, fun = slope_matrix_weighted, lonlat = TRUE) {
 #'
 #' @inheritParams slope_raster
 #' @inheritParams slope_matrix
+#' @return A vector of elevation values.
 #' @export
 #' @examples
 #' m = sf::st_coordinates(lisbon_road_network[1, ])
@@ -225,11 +262,12 @@ slope_xyz = function(route_xyz, fun = slope_matrix_weighted, lonlat = TRUE) {
 #' file.remove("dem_lisbon.tif")
 #' }
 #' }
-elevation_extract = function(m,
-                             dem,
-                             method = "bilinear",
-                             terra = has_terra() && methods::is(dem, "SpatRaster")
-                             ) {
+elevation_extract = function(
+  m,
+  dem,
+  method = "bilinear",
+  terra = has_terra() && methods::is(dem, "SpatRaster")
+  ) {
   if(terra) {
     res = terra::extract(dem, m[, 1:2], method = method)[[1]]
   } else {
@@ -242,6 +280,9 @@ elevation_extract = function(m,
 #' Take a linestring and add a third (z) dimension to its coordinates
 #' @inheritParams slope_raster
 #' @inheritParams elevation_extract
+#' @return An sf object that is identical to the input `routes`, except that
+#'   the coordinate values in the ouput has a third `z` dimension representing
+#'   the elevation of each vertex that defines a linear feature such as a road.
 #' @export
 #' @examples
 #' library(sf)
diff --git a/R/z.R b/R/z.R
index 5223b22..95bc99f 100644
--- a/R/z.R
+++ b/R/z.R
@@ -4,7 +4,8 @@
 #' in `sfc` objects with `XYZ` geometries.
 #'
 #' @param x An `sfc` object with 'XYZ' coordinates
-#'
+#' @return A vector of values representing elevations associated with
+#'   simple feature geometries that have elevations (XYZ coordinates).
 #' @export
 #' @examples
 #' x = slopes::lisbon_route_3d
diff --git a/man/elevation_add.Rd b/man/elevation_add.Rd
index 353843e..699847e 100644
--- a/man/elevation_add.Rd
+++ b/man/elevation_add.Rd
@@ -25,6 +25,11 @@ datasets. Default: \code{"bilinear"}.}
 \code{TRUE} by default if the package is installed \emph{and}
 if \code{dem} is of class \code{SpatRast}}
 }
+\value{
+An sf object that is identical to the input \code{routes}, except that
+the coordinate values in the ouput has a third \code{z} dimension representing
+the elevation of each vertex that defines a linear feature such as a road.
+}
 \description{
 Take a linestring and add a third (z) dimension to its coordinates
 }
diff --git a/man/elevation_extract.Rd b/man/elevation_extract.Rd
index aceed83..54a3fca 100644
--- a/man/elevation_extract.Rd
+++ b/man/elevation_extract.Rd
@@ -24,6 +24,9 @@ datasets. Default: \code{"bilinear"}.}
 \code{TRUE} by default if the package is installed \emph{and}
 if \code{dem} is of class \code{SpatRast}}
 }
+\value{
+A vector of elevation values.
+}
 \description{
 Extract elevations from coordinates
 }
diff --git a/man/elevation_get.Rd b/man/elevation_get.Rd
index 833fca2..af9b495 100644
--- a/man/elevation_get.Rd
+++ b/man/elevation_get.Rd
@@ -12,6 +12,10 @@ The object must be of class \code{sf} with \code{LINESTRING} geometries.}
 
 \item{...}{Options passed to \code{cc_elevation()}}
 }
+\value{
+A raster object with cell values representing elevations in the
+bounding box of the input \code{routes} object.
+}
 \description{
 \code{elevation_get()} uses the \verb{[ceramic::cc_elevation()]} function to get
 DEM data in raster format anywhere worldwide.
diff --git a/man/plot_dz.Rd b/man/plot_dz.Rd
index 2840aca..0ad51b7 100644
--- a/man/plot_dz.Rd
+++ b/man/plot_dz.Rd
@@ -54,6 +54,9 @@ Includes negative numbers and omits zero by default}
 
 \item{ncol}{Number of columns in legend, 4 by default.}
 }
+\value{
+A plot showing the elevation profile associated with a linestring.
+}
 \description{
 Plot a digital elevation profile based on xyz data
 }
diff --git a/man/plot_slope.Rd b/man/plot_slope.Rd
index 1f67080..252a493 100644
--- a/man/plot_slope.Rd
+++ b/man/plot_slope.Rd
@@ -56,6 +56,9 @@ Includes negative numbers and omits zero by default}
 
 \item{...}{Additional parameters to pass to legend}
 }
+\value{
+A plot showing the elevation profile associated with a linestring.
+}
 \description{
 Plot slope data for a 3d linestring with base R graphics
 }
diff --git a/man/sequential_dist.Rd b/man/sequential_dist.Rd
index bf83704..134ead3 100644
--- a/man/sequential_dist.Rd
+++ b/man/sequential_dist.Rd
@@ -11,6 +11,11 @@ sequential_dist(m, lonlat = TRUE)
 
 \item{lonlat}{Are the coordinates in lon/lat (geographic) coordinates? TRUE by default.}
 }
+\value{
+A vector of distance values in meters if \code{lonlat = TRUE}
+or the map units of the input data if \code{lonlat = FALSE} between
+consecutive vertices.
+}
 \description{
 Set \code{lonlat} to \code{FALSE} if you have projected data, e.g. with coordinates
 representing distance in meters, not degrees. Lonlat coodinates are assumed
@@ -20,5 +25,8 @@ representing distance in meters, not degrees. Lonlat coodinates are assumed
 x = c(0, 2, 3, 4, 5, 9)
 y = c(0, 0, 0, 0, 0, 1)
 m = cbind(x, y)
-sequential_dist(m)
+d = sequential_dist(m, lonlat = FALSE)
+d
+nrow(m)
+length(d)
 }
diff --git a/man/slope_matrix.Rd b/man/slope_matrix.Rd
index eaa2541..49cca6e 100644
--- a/man/slope_matrix.Rd
+++ b/man/slope_matrix.Rd
@@ -2,11 +2,14 @@
 % Please edit documentation in R/slopes.R
 \name{slope_matrix}
 \alias{slope_matrix}
+\alias{slope_matrix_mean}
 \alias{slope_matrix_weighted}
 \title{Calculate the gradient of line segments from a 3D matrix of coordinates}
 \usage{
 slope_matrix(m, elevations = m[, 3], lonlat = TRUE)
 
+slope_matrix_mean(m, elevations = m[, 3], lonlat = TRUE)
+
 slope_matrix_weighted(m, elevations = m[, 3], lonlat = TRUE)
 }
 \arguments{
@@ -18,6 +21,17 @@ coordinates.}
 
 \item{lonlat}{Are the coordinates in lon/lat (geographic) coordinates? TRUE by default.}
 }
+\value{
+A vector of slope gradients associated with each linear element
+(each line between consecutive vertices) associated with linear features.
+Returned values for \code{slope_matrix_mean()} and
+\code{slope_matrix_weighted()} are summary statistics for all
+linear elements in the linestring.
+The output value is a proportion representing the change in elevation
+for a given change in horizontal movement along the linestring.
+0.02, for example, represents a low gradient of 2\% while 0.08 represents
+a steep gradient of 8\%.
+}
 \description{
 Calculate the gradient of line segments from a 3D matrix of coordinates
 }
@@ -26,6 +40,8 @@ x = c(0, 2, 3, 4, 5, 9)
 y = c(0, 0, 0, 0, 0, 9)
 z = c(1, 2, 2, 4, 3, 1) / 10
 m = cbind(x, y, z)
+slope_matrix_weighted(m, lonlat = FALSE)
+slope_matrix_mean(m, lonlat = FALSE)
 plot(x, z, ylim = c(-0.5, 0.5), type = "l")
 (gx = slope_vector(x, z))
 (gxy = slope_matrix(m, lonlat = FALSE))
diff --git a/man/slope_raster.Rd b/man/slope_raster.Rd
index f8563e3..ecf277f 100644
--- a/man/slope_raster.Rd
+++ b/man/slope_raster.Rd
@@ -33,6 +33,10 @@ datasets. Default: \code{"bilinear"}.}
 \code{TRUE} by default if the package is installed \emph{and}
 if \code{dem} is of class \code{SpatRast}}
 }
+\value{
+A vector of slopes equal in length to the number simple features
+(rows representing linestrings) in the input object.
+}
 \description{
 This function takes an \code{sf} representing routes over geographical space
 and a raster dataset representing the terrain as inputs.
diff --git a/man/slope_vector.Rd b/man/slope_vector.Rd
index 819caea..e87ab94 100644
--- a/man/slope_vector.Rd
+++ b/man/slope_vector.Rd
@@ -22,6 +22,17 @@ slope_distance_weighted(d, elevations)
 
 \item{d}{Vector of distances between points}
 }
+\value{
+A vector of slope gradients associated with each linear element
+(each line between consecutive vertices) associated with linear features.
+Returned values for \code{slope_distance_mean()} and
+\code{slope_distance_mean_weighted()} are summary statistics for all
+linear elements in the linestring.
+The output value is a proportion representing the change in elevation
+for a given change in horizontal movement along the linestring.
+0.02, for example, represents a low gradient of 2\% while 0.08 represents
+a steep gradient of 8\%.
+}
 \description{
 \code{\link[=slope_vector]{slope_vector()}} calculates the slopes associated with consecutive elements
 in one dimensional distance and associated elevations (see examples).
diff --git a/man/slope_xyz.Rd b/man/slope_xyz.Rd
index e084f9b..ce5f10b 100644
--- a/man/slope_xyz.Rd
+++ b/man/slope_xyz.Rd
@@ -14,6 +14,10 @@ slope_xyz(route_xyz, fun = slope_matrix_weighted, lonlat = TRUE)
 
 \item{lonlat}{Are the coordinates in lon/lat order? TRUE by default}
 }
+\value{
+A vector of slopes equal in length to the number simple features
+(rows representing linestrings) in the input object.
+}
 \description{
 Extract slopes from xyz data frame or sf objects
 }
diff --git a/man/z_value.Rd b/man/z_value.Rd
index 1aaaca4..7fbbc52 100644
--- a/man/z_value.Rd
+++ b/man/z_value.Rd
@@ -24,6 +24,10 @@ z_min(x)
 \arguments{
 \item{x}{An \code{sfc} object with 'XYZ' coordinates}
 }
+\value{
+A vector of values representing elevations associated with
+simple feature geometries that have elevations (XYZ coordinates).
+}
 \description{
 The \verb{slope_z*()} functions calculate summary values for the Z axis
 in \code{sfc} objects with \code{XYZ} geometries.