diff --git a/DESCRIPTION b/DESCRIPTION index e1cf5d143..c53a6a1e5 100644 --- a/DESCRIPTION +++ b/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", , "mark.padgham@email.com", role = c("aut", "cre")), person("Andreas", "Petutschnig", role = "aut"), diff --git a/R/dists-categorical.R b/R/dists-categorical.R index 8d36d6ad9..844ffc56f 100644 --- a/R/dists-categorical.R +++ b/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 --git a/codemeta.json b/codemeta.json index 819ea85b7..e590f306a 100644 --- a/codemeta.json +++ b/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", diff --git a/man/dodgr_dists_categorical.Rd b/man/dodgr_dists_categorical.Rd index 30c8de387..92ba68dad 100644 --- a/man/dodgr_dists_categorical.Rd +++ b/man/dodgr_dists_categorical.Rd @@ -31,10 +31,11 @@ distances and for each edge category; if \code{TRUE}, return single vector of proportional distances, like the \code{summary} function applied to full results. See Note.} -\item{dlimit}{If \code{TRUE}, and no value to \code{to} is given, distances are -aggregated from each \code{from} point out to the specified distance limit (in -the same units as the edge distances of the input graph). The -\code{proportions_only} argument has no effect when \code{dlimit = TRUE}.} +\item{dlimit}{If no value to \code{to} is given, distances are aggregated from +each \code{from} point out to the specified distance limit (in the same units as +the edge distances of the input graph). \code{dlimit} only has any effect if \code{to} +is not specified, in which case the \code{proportions_only} argument has no +effect.} \item{heap}{Type of heap to use in priority queue. Options include Fibonacci Heap (default; \code{FHeap}), Binary Heap (\code{BHeap}), @@ -43,13 +44,14 @@ Fibonacci Heap (default; \code{FHeap}), Binary Heap (\code{BHeap}), \item{quiet}{If \code{FALSE}, display progress messages on screen.} } \value{ -If \code{dlimit = FALSE}, a list of distance matrices of equal dimensions +If \code{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 \code{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 \code{dlimit}, along with distances along each of +the different kinds of ways specified in the "edge_type" column of the input +graph. } \description{ Cumulative distances along different edge categories