update docs for dlimit param of categorical dists (#144)

Author: mpadge

Diff for: DESCRIPTION

@@ -1,6 +1,6 @@
 Package: dodgr
 Title: Distances on Directed Graphs
-Version: 0.2.15.063
+Version: 0.2.15.064
 Authors@R: c(
     person("Mark", "Padgham", , "[email protected]", role = c("aut", "cre")),
     person("Andreas", "Petutschnig", role = "aut"),

Diff for: R/dists-categorical.R

@@ -9,17 +9,19 @@
 #' distances and for each edge category; if `TRUE`, return single vector of
 #' proportional distances, like the `summary` function applied to full
 #' results. See Note.
-#' @param dlimit If `TRUE`, and no value to `to` is given, distances are
-#' aggregated from each `from` point out to the specified distance limit (in
-#' the same units as the edge distances of the input graph). The
-#' `proportions_only` argument has no effect when `dlimit = TRUE`.
-#' @return If `dlimit = FALSE`, a list of distance matrices of equal dimensions
+#' @param dlimit If no value to `to` is given, distances are aggregated from
+#' each `from` point out to the specified distance limit (in the same units as
+#' the edge distances of the input graph). `dlimit` only has any effect if `to`
+#' is not specified, in which case the `proportions_only` argument has no
+#' effect.
+#' @return If `to` is specified, a list of distance matrices of equal dimensions
 #' (length(from), length(to)), the first of which ("distance") holds the final
 #' distances, while the rest are one matrix for each unique value of
 #' "edge_type", holding the distances traversed along those types of edges only.
-#' If `dlimit = TRUE`, a single matrix of total distances along all ways from
-#' each point, along with distances along each of the different kinds of ways
-#' specified in the "edge_type" column of the input graph.
+#' Otherwise, a single matrix of total distances along all ways from each point
+#' out to the specified value of `dlimit`, along with distances along each of
+#' the different kinds of ways specified in the "edge_type" column of the input
+#' graph.
 #'
 #' @note The "edge_type" column in the graph can contain any kind of discrete or
 #' categorical values, although integer values of 0 are not permissible. `NA`
@@ -79,6 +81,14 @@ dodgr_dists_categorical <- function (graph,
     if (is.integer (graph$edge_type) && any (graph$edge_type == 0L)) {
         stop ("graphs with integer edge_type columns may not contain 0s")
     }
+    if (is.null (to)) {
+        if (is.null (dlimit)) {
+            stop ("'dlimit' must be specified if no 'to' points are given.")
+        }
+        if (!(is.numeric (dlimit) && length (dlimit) == 1L)) {
+            stop ("'dlimit' must be a single number.")
+        }
+    }
 
     graph <- tbl_to_df (graph)
 
@@ -121,7 +131,7 @@ dodgr_dists_categorical <- function (graph,
         message ("Calculating shortest paths ... ", appendLF = FALSE)
     }
 
-    if (is.null (dlimit) && !is.null (to)) {
+    if (!is.null (to)) {
 
         d <- rcpp_get_sp_dists_categorical (
             graph,

Diff for: codemeta.json

@@ -7,7 +7,7 @@
   "codeRepository": "https://github.com/ATFutures/dodgr",
   "issueTracker": "https://github.com/ATFutures/dodgr/issues",
   "license": "https://spdx.org/licenses/GPL-3.0",
-  "version": "0.2.15.063",
+  "version": "0.2.15.064",
   "programmingLanguage": {
     "@type": "ComputerLanguage",
     "name": "R",