From b40317b4e95538f48f8bb045d6ebd39da5a80a86 Mon Sep 17 00:00:00 2001 From: mpadge Date: Mon, 30 Sep 2024 10:24:11 +0200 Subject: [PATCH] update all parameter inheritance structures for #254 So that almost all fns just inherit param descriptions directly from dodgr_dists --- DESCRIPTION | 2 +- R/dists-nearest.R | 14 +---- R/dists.R | 103 ++++++++++++++++++--------------- R/times.R | 10 +--- codemeta.json | 2 +- man/dodgr_distances.Rd | 97 +++++++++++++++---------------- man/dodgr_dists.Rd | 97 +++++++++++++++---------------- man/dodgr_dists_categorical.Rd | 17 +++++- man/dodgr_dists_nearest.Rd | 45 ++++++++++++-- man/dodgr_flows_aggregate.Rd | 17 +++++- man/dodgr_flows_si.Rd | 17 +++++- man/dodgr_times.Rd | 90 +++++++++++++--------------- 12 files changed, 279 insertions(+), 232 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 54db070c..83805a3c 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: dodgr Title: Distances on Directed Graphs -Version: 0.4.1.035 +Version: 0.4.1.036 Authors@R: c( person("Mark", "Padgham", , "mark.padgham@email.com", role = c("aut", "cre")), person("Andreas", "Petutschnig", role = "aut"), diff --git a/R/dists-nearest.R b/R/dists-nearest.R index ec2ee95c..ff733226 100644 --- a/R/dists-nearest.R +++ b/R/dists-nearest.R @@ -1,19 +1,7 @@ #' Calculate vector of shortest distances from a series of 'from' points to #' nearest one of series of 'to' points. #' -#' @param graph `data.frame` or equivalent object representing the network -#' graph (see Notes) -#' @param from Vector or matrix of points **from** which route distances are to -#' be calculated (see Notes) -#' @param to Vector or matrix of points **to** which shortest route distances -#' are to be calculated to nearest 'to' point only. -#' @param shortest If `FALSE`, calculate distances along the \emph{fastest} -#' rather than shortest routes (see Notes). -#' @param heap Type of heap to use in priority queue. Options include -#' Fibonacci Heap (default; `FHeap`), Binary Heap (`BHeap`), -#' `Trinomial Heap (`TriHeap`), Extended Trinomial Heap -#' (`TriHeapExt`, and 2-3 Heap (`Heap23`). -#' @param quiet If `FALSE`, display progress messages on screen. +#' @inheritParams dodgr_dists #' @return Vector of distances, one element for each 'from' point giving the #' distance to the nearest 'to' point. #' diff --git a/R/dists.R b/R/dists.R index 57de420b..fd9bee4b 100644 --- a/R/dists.R +++ b/R/dists.R @@ -4,24 +4,73 @@ #' graph (see Notes). For `dodgr` street networks, this may be a network derived #' from either \pkg{sf} or \pkg{silicate} ("sc") data, generated with #' \link{weight_streetnet}. +#' +#' The `from` and `to` columns of `graph` may be either single +#' columns of numeric or character values specifying the numbers or names of +#' graph vertices, or combinations to two columns specifying geographical +#' (longitude and latitude,) coordinates. In the latter case, almost any sensible +#' combination of names will be accepted (for example, `fromx, fromy`, +#' `from_x, from_y`, or `fr_lat, fr_lon`.) +#' +#' Note that longitude and latitude values are always interpreted in 'dodgr' to +#' be in EPSG:4326 / WSG84 coordinates. Any other kinds of coordinates should +#' first be reprojected to EPSG:4326 before submitting to any 'dodgr' routines. +#' +#' See further information in Details. +#' #' @param from Vector or matrix of points **from** which route distances are to -#' be calculated (see Notes) +#' be calculated, specified as one of the following: +#' \itemize{ +#' \item Single character vector precisely matching node numbers or names +#' given in `graph$from` or `graph$to`. +#' \item Single vector of integer-ish values, in which case these will be +#' presumed to specify indices into \link{dodgr_vertices}, and NOT to +#' correspond to values in the 'from' or 'to' columns of the graph. See the +#' example below for a demonstration. +#' \item Matrix or equivalent of longitude and latitude coordinates, in which +#' case these will be matched on to the nearest coordinates of 'from' and 'to' +#' points in the graph. +#' } +#' #' @param to Vector or matrix of points **to** which route distances are to be -#' calculated (see Notes) +#' calculated. If `to` is `NULL`, pairwise distances will be calculated from +#' all `from` points to all other nodes in `graph`. If both `from` and `to` are +#' `NULL`, pairwise distances are calculated between all nodes in `graph`. +#' #' @param shortest If `FALSE`, calculate distances along the \emph{fastest} -#' rather than shortest routes (see Notes). +#' rather than shortest routes. For street networks produced with +#' \link{weight_streetnet}, distances may also be calculated along the +#' \emph{fastest} routes with the `shortest = FALSE` option. Graphs must in +#' this case have columns of `time` and `time_weighted`. Note that the fastest +#' routes will only be approximate when derived from \pkg{sf}-format data +#' generated with the \pkg{osmdata} function `osmdata_sf()`, and will be much +#' more accurate when derived from `sc`-format data generated with +#' `osmdata_sc()`. See \link{weight_streetnet} for details. +#' #' @param pairwise If `TRUE`, calculate distances only between the ordered #' pairs of `from` and `to`. +#' #' @param heap Type of heap to use in priority queue. Options include #' Fibonacci Heap (default; `FHeap`), Binary Heap (`BHeap`), #' `Trinomial Heap (`TriHeap`), Extended Trinomial Heap #' (`TriHeapExt`, and 2-3 Heap (`Heap23`). -#' @param parallel If `TRUE`, perform routing calculation in parallel (see -#' details) +#' +#' @param parallel If `TRUE`, perform routing calculation in parallel. +#' Calculations in parallel ought very generally be advantageous. For small +#' graphs, calculating distances in parallel is likely to offer relatively +#' little gain in speed, but increases from parallel computation will generally +#' markedly increase with increasing graph sizes. By default, parallel +#' computation uses the maximal number of available cores or threads. This +#' number can be reduced by specifying a value via +#' `RcppParallel::setThreadOptions (numThreads = )`. Parallel +#' calculations are, however, not able to be interrupted (for example, by +#' `Ctrl-C`), and can only be stopped by killing the R process. +#' #' @param quiet If `FALSE`, display progress messages on screen. +#' #' @return square matrix of distances between nodes #' -#' @note `graph` must minimally contain three columns of `from`, +#' @details `graph` must minimally contain three columns of `from`, #' `to`, `dist`. If an additional column named `weight` or #' `wt` is present, shortest paths are calculated according to values #' specified in that column; otherwise according to `dist` values. Either @@ -31,48 +80,6 @@ #' values (if present), while reported distances will be total sums of `dist` #' values. #' -#' For street networks produced with \link{weight_streetnet}, distances may also -#' be calculated along the \emph{fastest} routes with the `shortest = FALSE` -#' option. Graphs must in this case have columns of `time` and `time_weighted`. -#' Note that the fastest routes will only be approximate when derived from -#' \pkg{sf}-format data generated with the \pkg{osmdata} function -#' `osmdata_sf()`, and will be much more accurate when derived from `sc`-format -#' data generated with `osmdata_sc()`. See \link{weight_streetnet} for details. -#' -#' The `from` and `to` columns of `graph` may be either single -#' columns of numeric or character values specifying the numbers or names of -#' graph vertices, or combinations to two columns specifying geographical -#' (longitude and latitude) coordinates. In the latter case, almost any sensible -#' combination of names will be accepted (for example, `fromx, fromy`, -#' `from_x, from_y`, or `fr_lat, fr_lon`.) -#' -#' The `from` and `to` parameters passed to this function can be either: -#' \itemize{ -#' \item Single character vectors precisely matching node numbers or names -#' given in `graph$from` or `graph$to`. -#' \item Single vectors of integer-ish values, in which case these will be -#' presumed to specify indices into \link{dodgr_vertices}, and NOT to -#' correspond to values in the "from" or "to" columns of the graph. See the -#' example below for a demonstration. -#' \item matrices or equivalent of longitude and latitude coordinates, in which -#' case these will be matched on to the nearest coordinates of "from" and "to" -#' points in the graph. -#' } -#' -#' If `to` is `NULL`, pairwise distances will be calculated from all `from` -#' points to all other nodes in `graph`. If both `from` and `to` are `NULL`, -#' pairwise distances are calculated between all nodes in `graph`. -#' -#' Calculations in parallel (`parallel = TRUE`) ought very generally be -#' advantageous. For small graphs, calculating distances in parallel is likely -#' to offer relatively little gain in speed, but increases from parallel -#' computation will generally markedly increase with increasing graph sizes. -#' By default, parallel computation uses the maximal number of available cores -#' or threads. This number can be reduced by specifying a value via -#' `RcppParallel::setThreadOptions (numThreads = )`. Parallel -#' calculations are, however, not able to be interrupted (for example, by -#' `Ctrl-C`), and can only be stopped by killing the R process. -#' #' @family distances #' @export #' @examples diff --git a/R/times.R b/R/times.R index b8fd42d0..ddf1a90b 100644 --- a/R/times.R +++ b/R/times.R @@ -1,15 +1,7 @@ #' Calculate matrix of pair-wise travel times between points. #' #' @inherit dodgr_dists -#' @param graph `data.frame` or equivalent object representing the network -#' graph (see Notes). For `dodgr` street networks, this may be a network derived -#' from either \pkg{sf} or \pkg{silicate} ("sc") data, generated with -#' \link{weight_streetnet}. Note, however, that networks derived from \pkg{sf} -#' data will generally not produce reliable estimates of times. Accurate -#' estimates can only be guaranteed by using networks derived from -#' \pkg{silicate} ("sc") data. -#' @param shortest If `TRUE`, calculate times along the \emph{shortest} rather -#' than fastest paths. +#' @inheritParams dodgr_dists #' #' @family distances #' @export diff --git a/codemeta.json b/codemeta.json index ef1558a6..0de7877c 100644 --- a/codemeta.json +++ b/codemeta.json @@ -11,7 +11,7 @@ "codeRepository": "https://github.com/UrbanAnalyst/dodgr", "issueTracker": "https://github.com/UrbanAnalyst/dodgr/issues", "license": "https://spdx.org/licenses/GPL-3.0", - "version": "0.4.1.035", + "version": "0.4.1.036", "programmingLanguage": { "@type": "ComputerLanguage", "name": "R", diff --git a/man/dodgr_distances.Rd b/man/dodgr_distances.Rd index 56eef555..1b1ce045 100644 --- a/man/dodgr_distances.Rd +++ b/man/dodgr_distances.Rd @@ -19,16 +19,49 @@ dodgr_distances( \item{graph}{\code{data.frame} or equivalent object representing the network graph (see Notes). For \code{dodgr} street networks, this may be a network derived from either \pkg{sf} or \pkg{silicate} ("sc") data, generated with -\link{weight_streetnet}.} +\link{weight_streetnet}. + +The \code{from} and \code{to} columns of \code{graph} may be either single +columns of numeric or character values specifying the numbers or names of +graph vertices, or combinations to two columns specifying geographical +(longitude and latitude,) coordinates. In the latter case, almost any sensible +combination of names will be accepted (for example, \verb{fromx, fromy}, +\verb{from_x, from_y}, or \verb{fr_lat, fr_lon}.) + +Note that longitude and latitude values are always interpreted in 'dodgr' to +be in EPSG:4326 / WSG84 coordinates. Any other kinds of coordinates should +first be reprojected to EPSG:4326 before submitting to any 'dodgr' routines. + +See further information in Details.} \item{from}{Vector or matrix of points \strong{from} which route distances are to -be calculated (see Notes)} +be calculated, specified as one of the following: +\itemize{ +\item Single character vector precisely matching node numbers or names +given in \code{graph$from} or \code{graph$to}. +\item Single vector of integer-ish values, in which case these will be +presumed to specify indices into \link{dodgr_vertices}, and NOT to +correspond to values in the 'from' or 'to' columns of the graph. See the +example below for a demonstration. +\item Matrix or equivalent of longitude and latitude coordinates, in which +case these will be matched on to the nearest coordinates of 'from' and 'to' +points in the graph. +}} \item{to}{Vector or matrix of points \strong{to} which route distances are to be -calculated (see Notes)} +calculated. If \code{to} is \code{NULL}, pairwise distances will be calculated from +all \code{from} points to all other nodes in \code{graph}. If both \code{from} and \code{to} are +\code{NULL}, pairwise distances are calculated between all nodes in \code{graph}.} \item{shortest}{If \code{FALSE}, calculate distances along the \emph{fastest} -rather than shortest routes (see Notes).} +rather than shortest routes. For street networks produced with +\link{weight_streetnet}, distances may also be calculated along the +\emph{fastest} routes with the \code{shortest = FALSE} option. Graphs must in +this case have columns of \code{time} and \code{time_weighted}. Note that the fastest +routes will only be approximate when derived from \pkg{sf}-format data +generated with the \pkg{osmdata} function \code{osmdata_sf()}, and will be much +more accurate when derived from \code{sc}-format data generated with +\code{osmdata_sc()}. See \link{weight_streetnet} for details.} \item{pairwise}{If \code{TRUE}, calculate distances only between the ordered pairs of \code{from} and \code{to}.} @@ -37,8 +70,16 @@ pairs of \code{from} and \code{to}.} Fibonacci Heap (default; \code{FHeap}), Binary Heap (\code{BHeap}), \verb{Trinomial Heap (}TriHeap\verb{), Extended Trinomial Heap (}TriHeapExt\verb{, and 2-3 Heap (}Heap23`).} -\item{parallel}{If \code{TRUE}, perform routing calculation in parallel (see -details)} +\item{parallel}{If \code{TRUE}, perform routing calculation in parallel. +Calculations in parallel ought very generally be advantageous. For small +graphs, calculating distances in parallel is likely to offer relatively +little gain in speed, but increases from parallel computation will generally +markedly increase with increasing graph sizes. By default, parallel +computation uses the maximal number of available cores or threads. This +number can be reduced by specifying a value via +\verb{RcppParallel::setThreadOptions (numThreads = )}. Parallel +calculations are, however, not able to be interrupted (for example, by +\code{Ctrl-C}), and can only be stopped by killing the R process.} \item{quiet}{If \code{FALSE}, display progress messages on screen.} } @@ -48,7 +89,7 @@ square matrix of distances between nodes \description{ Alias for \link{dodgr_dists} } -\note{ +\details{ \code{graph} must minimally contain three columns of \code{from}, \code{to}, \code{dist}. If an additional column named \code{weight} or \code{wt} is present, shortest paths are calculated according to values @@ -58,48 +99,6 @@ by default according to values of \code{dist}. That is, paths between any pair o points will be calculated according to the minimal total sum of \code{weight} values (if present), while reported distances will be total sums of \code{dist} values. - -For street networks produced with \link{weight_streetnet}, distances may also -be calculated along the \emph{fastest} routes with the \code{shortest = FALSE} -option. Graphs must in this case have columns of \code{time} and \code{time_weighted}. -Note that the fastest routes will only be approximate when derived from -\pkg{sf}-format data generated with the \pkg{osmdata} function -\code{osmdata_sf()}, and will be much more accurate when derived from \code{sc}-format -data generated with \code{osmdata_sc()}. See \link{weight_streetnet} for details. - -The \code{from} and \code{to} columns of \code{graph} may be either single -columns of numeric or character values specifying the numbers or names of -graph vertices, or combinations to two columns specifying geographical -(longitude and latitude) coordinates. In the latter case, almost any sensible -combination of names will be accepted (for example, \verb{fromx, fromy}, -\verb{from_x, from_y}, or \verb{fr_lat, fr_lon}.) - -The \code{from} and \code{to} parameters passed to this function can be either: -\itemize{ -\item Single character vectors precisely matching node numbers or names -given in \code{graph$from} or \code{graph$to}. -\item Single vectors of integer-ish values, in which case these will be -presumed to specify indices into \link{dodgr_vertices}, and NOT to -correspond to values in the "from" or "to" columns of the graph. See the -example below for a demonstration. -\item matrices or equivalent of longitude and latitude coordinates, in which -case these will be matched on to the nearest coordinates of "from" and "to" -points in the graph. -} - -If \code{to} is \code{NULL}, pairwise distances will be calculated from all \code{from} -points to all other nodes in \code{graph}. If both \code{from} and \code{to} are \code{NULL}, -pairwise distances are calculated between all nodes in \code{graph}. - -Calculations in parallel (\code{parallel = TRUE}) ought very generally be -advantageous. For small graphs, calculating distances in parallel is likely -to offer relatively little gain in speed, but increases from parallel -computation will generally markedly increase with increasing graph sizes. -By default, parallel computation uses the maximal number of available cores -or threads. This number can be reduced by specifying a value via -\verb{RcppParallel::setThreadOptions (numThreads = )}. Parallel -calculations are, however, not able to be interrupted (for example, by -\code{Ctrl-C}), and can only be stopped by killing the R process. } \examples{ # A simple graph diff --git a/man/dodgr_dists.Rd b/man/dodgr_dists.Rd index 66841b08..e9dd4c20 100644 --- a/man/dodgr_dists.Rd +++ b/man/dodgr_dists.Rd @@ -19,16 +19,49 @@ dodgr_dists( \item{graph}{\code{data.frame} or equivalent object representing the network graph (see Notes). For \code{dodgr} street networks, this may be a network derived from either \pkg{sf} or \pkg{silicate} ("sc") data, generated with -\link{weight_streetnet}.} +\link{weight_streetnet}. + +The \code{from} and \code{to} columns of \code{graph} may be either single +columns of numeric or character values specifying the numbers or names of +graph vertices, or combinations to two columns specifying geographical +(longitude and latitude,) coordinates. In the latter case, almost any sensible +combination of names will be accepted (for example, \verb{fromx, fromy}, +\verb{from_x, from_y}, or \verb{fr_lat, fr_lon}.) + +Note that longitude and latitude values are always interpreted in 'dodgr' to +be in EPSG:4326 / WSG84 coordinates. Any other kinds of coordinates should +first be reprojected to EPSG:4326 before submitting to any 'dodgr' routines. + +See further information in Details.} \item{from}{Vector or matrix of points \strong{from} which route distances are to -be calculated (see Notes)} +be calculated, specified as one of the following: +\itemize{ +\item Single character vector precisely matching node numbers or names +given in \code{graph$from} or \code{graph$to}. +\item Single vector of integer-ish values, in which case these will be +presumed to specify indices into \link{dodgr_vertices}, and NOT to +correspond to values in the 'from' or 'to' columns of the graph. See the +example below for a demonstration. +\item Matrix or equivalent of longitude and latitude coordinates, in which +case these will be matched on to the nearest coordinates of 'from' and 'to' +points in the graph. +}} \item{to}{Vector or matrix of points \strong{to} which route distances are to be -calculated (see Notes)} +calculated. If \code{to} is \code{NULL}, pairwise distances will be calculated from +all \code{from} points to all other nodes in \code{graph}. If both \code{from} and \code{to} are +\code{NULL}, pairwise distances are calculated between all nodes in \code{graph}.} \item{shortest}{If \code{FALSE}, calculate distances along the \emph{fastest} -rather than shortest routes (see Notes).} +rather than shortest routes. For street networks produced with +\link{weight_streetnet}, distances may also be calculated along the +\emph{fastest} routes with the \code{shortest = FALSE} option. Graphs must in +this case have columns of \code{time} and \code{time_weighted}. Note that the fastest +routes will only be approximate when derived from \pkg{sf}-format data +generated with the \pkg{osmdata} function \code{osmdata_sf()}, and will be much +more accurate when derived from \code{sc}-format data generated with +\code{osmdata_sc()}. See \link{weight_streetnet} for details.} \item{pairwise}{If \code{TRUE}, calculate distances only between the ordered pairs of \code{from} and \code{to}.} @@ -37,8 +70,16 @@ pairs of \code{from} and \code{to}.} Fibonacci Heap (default; \code{FHeap}), Binary Heap (\code{BHeap}), \verb{Trinomial Heap (}TriHeap\verb{), Extended Trinomial Heap (}TriHeapExt\verb{, and 2-3 Heap (}Heap23`).} -\item{parallel}{If \code{TRUE}, perform routing calculation in parallel (see -details)} +\item{parallel}{If \code{TRUE}, perform routing calculation in parallel. +Calculations in parallel ought very generally be advantageous. For small +graphs, calculating distances in parallel is likely to offer relatively +little gain in speed, but increases from parallel computation will generally +markedly increase with increasing graph sizes. By default, parallel +computation uses the maximal number of available cores or threads. This +number can be reduced by specifying a value via +\verb{RcppParallel::setThreadOptions (numThreads = )}. Parallel +calculations are, however, not able to be interrupted (for example, by +\code{Ctrl-C}), and can only be stopped by killing the R process.} \item{quiet}{If \code{FALSE}, display progress messages on screen.} } @@ -48,7 +89,7 @@ square matrix of distances between nodes \description{ Calculate matrix of pair-wise distances between points. } -\note{ +\details{ \code{graph} must minimally contain three columns of \code{from}, \code{to}, \code{dist}. If an additional column named \code{weight} or \code{wt} is present, shortest paths are calculated according to values @@ -58,48 +99,6 @@ by default according to values of \code{dist}. That is, paths between any pair o points will be calculated according to the minimal total sum of \code{weight} values (if present), while reported distances will be total sums of \code{dist} values. - -For street networks produced with \link{weight_streetnet}, distances may also -be calculated along the \emph{fastest} routes with the \code{shortest = FALSE} -option. Graphs must in this case have columns of \code{time} and \code{time_weighted}. -Note that the fastest routes will only be approximate when derived from -\pkg{sf}-format data generated with the \pkg{osmdata} function -\code{osmdata_sf()}, and will be much more accurate when derived from \code{sc}-format -data generated with \code{osmdata_sc()}. See \link{weight_streetnet} for details. - -The \code{from} and \code{to} columns of \code{graph} may be either single -columns of numeric or character values specifying the numbers or names of -graph vertices, or combinations to two columns specifying geographical -(longitude and latitude) coordinates. In the latter case, almost any sensible -combination of names will be accepted (for example, \verb{fromx, fromy}, -\verb{from_x, from_y}, or \verb{fr_lat, fr_lon}.) - -The \code{from} and \code{to} parameters passed to this function can be either: -\itemize{ -\item Single character vectors precisely matching node numbers or names -given in \code{graph$from} or \code{graph$to}. -\item Single vectors of integer-ish values, in which case these will be -presumed to specify indices into \link{dodgr_vertices}, and NOT to -correspond to values in the "from" or "to" columns of the graph. See the -example below for a demonstration. -\item matrices or equivalent of longitude and latitude coordinates, in which -case these will be matched on to the nearest coordinates of "from" and "to" -points in the graph. -} - -If \code{to} is \code{NULL}, pairwise distances will be calculated from all \code{from} -points to all other nodes in \code{graph}. If both \code{from} and \code{to} are \code{NULL}, -pairwise distances are calculated between all nodes in \code{graph}. - -Calculations in parallel (\code{parallel = TRUE}) ought very generally be -advantageous. For small graphs, calculating distances in parallel is likely -to offer relatively little gain in speed, but increases from parallel -computation will generally markedly increase with increasing graph sizes. -By default, parallel computation uses the maximal number of available cores -or threads. This number can be reduced by specifying a value via -\verb{RcppParallel::setThreadOptions (numThreads = )}. Parallel -calculations are, however, not able to be interrupted (for example, by -\code{Ctrl-C}), and can only be stopped by killing the R process. } \examples{ # A simple graph diff --git a/man/dodgr_dists_categorical.Rd b/man/dodgr_dists_categorical.Rd index c845a660..6c068b05 100644 --- a/man/dodgr_dists_categorical.Rd +++ b/man/dodgr_dists_categorical.Rd @@ -22,10 +22,23 @@ edge types along which categorical distances are to be aggregated (see Note).} \item{from}{Vector or matrix of points \strong{from} which route distances are to -be calculated (see Notes)} +be calculated, specified as one of the following: +\itemize{ +\item Single character vector precisely matching node numbers or names +given in \code{graph$from} or \code{graph$to}. +\item Single vector of integer-ish values, in which case these will be +presumed to specify indices into \link{dodgr_vertices}, and NOT to +correspond to values in the 'from' or 'to' columns of the graph. See the +example below for a demonstration. +\item Matrix or equivalent of longitude and latitude coordinates, in which +case these will be matched on to the nearest coordinates of 'from' and 'to' +points in the graph. +}} \item{to}{Vector or matrix of points \strong{to} which route distances are to be -calculated (see Notes)} +calculated. If \code{to} is \code{NULL}, pairwise distances will be calculated from +all \code{from} points to all other nodes in \code{graph}. If both \code{from} and \code{to} are +\code{NULL}, pairwise distances are calculated between all nodes in \code{graph}.} \item{proportions_only}{If \code{FALSE}, return distance matrices for full distances and for each edge category; if \code{TRUE}, return single vector of diff --git a/man/dodgr_dists_nearest.Rd b/man/dodgr_dists_nearest.Rd index cefef98d..b974ce7b 100644 --- a/man/dodgr_dists_nearest.Rd +++ b/man/dodgr_dists_nearest.Rd @@ -16,16 +16,51 @@ dodgr_dists_nearest( } \arguments{ \item{graph}{\code{data.frame} or equivalent object representing the network -graph (see Notes)} +graph (see Notes). For \code{dodgr} street networks, this may be a network derived +from either \pkg{sf} or \pkg{silicate} ("sc") data, generated with +\link{weight_streetnet}. + +The \code{from} and \code{to} columns of \code{graph} may be either single +columns of numeric or character values specifying the numbers or names of +graph vertices, or combinations to two columns specifying geographical +(longitude and latitude,) coordinates. In the latter case, almost any sensible +combination of names will be accepted (for example, \verb{fromx, fromy}, +\verb{from_x, from_y}, or \verb{fr_lat, fr_lon}.) + +Note that longitude and latitude values are always interpreted in 'dodgr' to +be in EPSG:4326 / WSG84 coordinates. Any other kinds of coordinates should +first be reprojected to EPSG:4326 before submitting to any 'dodgr' routines. + +See further information in Details.} \item{from}{Vector or matrix of points \strong{from} which route distances are to -be calculated (see Notes)} +be calculated, specified as one of the following: +\itemize{ +\item Single character vector precisely matching node numbers or names +given in \code{graph$from} or \code{graph$to}. +\item Single vector of integer-ish values, in which case these will be +presumed to specify indices into \link{dodgr_vertices}, and NOT to +correspond to values in the 'from' or 'to' columns of the graph. See the +example below for a demonstration. +\item Matrix or equivalent of longitude and latitude coordinates, in which +case these will be matched on to the nearest coordinates of 'from' and 'to' +points in the graph. +}} -\item{to}{Vector or matrix of points \strong{to} which shortest route distances -are to be calculated to nearest 'to' point only.} +\item{to}{Vector or matrix of points \strong{to} which route distances are to be +calculated. If \code{to} is \code{NULL}, pairwise distances will be calculated from +all \code{from} points to all other nodes in \code{graph}. If both \code{from} and \code{to} are +\code{NULL}, pairwise distances are calculated between all nodes in \code{graph}.} \item{shortest}{If \code{FALSE}, calculate distances along the \emph{fastest} -rather than shortest routes (see Notes).} +rather than shortest routes. For street networks produced with +\link{weight_streetnet}, distances may also be calculated along the +\emph{fastest} routes with the \code{shortest = FALSE} option. Graphs must in +this case have columns of \code{time} and \code{time_weighted}. Note that the fastest +routes will only be approximate when derived from \pkg{sf}-format data +generated with the \pkg{osmdata} function \code{osmdata_sf()}, and will be much +more accurate when derived from \code{sc}-format data generated with +\code{osmdata_sc()}. See \link{weight_streetnet} for details.} \item{heap}{Type of heap to use in priority queue. Options include Fibonacci Heap (default; \code{FHeap}), Binary Heap (\code{BHeap}), diff --git a/man/dodgr_flows_aggregate.Rd b/man/dodgr_flows_aggregate.Rd index c75a97fb..c4d28346 100644 --- a/man/dodgr_flows_aggregate.Rd +++ b/man/dodgr_flows_aggregate.Rd @@ -22,10 +22,23 @@ dodgr_flows_aggregate( graph (see Details)} \item{from}{Vector or matrix of points \strong{from} which route distances are to -be calculated (see Notes)} +be calculated, specified as one of the following: +\itemize{ +\item Single character vector precisely matching node numbers or names +given in \code{graph$from} or \code{graph$to}. +\item Single vector of integer-ish values, in which case these will be +presumed to specify indices into \link{dodgr_vertices}, and NOT to +correspond to values in the 'from' or 'to' columns of the graph. See the +example below for a demonstration. +\item Matrix or equivalent of longitude and latitude coordinates, in which +case these will be matched on to the nearest coordinates of 'from' and 'to' +points in the graph. +}} \item{to}{Vector or matrix of points \strong{to} which route distances are to be -calculated (see Notes)} +calculated. If \code{to} is \code{NULL}, pairwise distances will be calculated from +all \code{from} points to all other nodes in \code{graph}. If both \code{from} and \code{to} are +\code{NULL}, pairwise distances are calculated between all nodes in \code{graph}.} \item{flows}{Matrix of flows with \code{nrow(flows)==length(from)} and \code{ncol(flows)==length(to)}.} diff --git a/man/dodgr_flows_si.Rd b/man/dodgr_flows_si.Rd index cc7275c5..cd13761e 100644 --- a/man/dodgr_flows_si.Rd +++ b/man/dodgr_flows_si.Rd @@ -23,10 +23,23 @@ dodgr_flows_si( graph (see Details)} \item{from}{Vector or matrix of points \strong{from} which route distances are to -be calculated (see Notes)} +be calculated, specified as one of the following: +\itemize{ +\item Single character vector precisely matching node numbers or names +given in \code{graph$from} or \code{graph$to}. +\item Single vector of integer-ish values, in which case these will be +presumed to specify indices into \link{dodgr_vertices}, and NOT to +correspond to values in the 'from' or 'to' columns of the graph. See the +example below for a demonstration. +\item Matrix or equivalent of longitude and latitude coordinates, in which +case these will be matched on to the nearest coordinates of 'from' and 'to' +points in the graph. +}} \item{to}{Vector or matrix of points \strong{to} which route distances are to be -calculated (see Notes)} +calculated. If \code{to} is \code{NULL}, pairwise distances will be calculated from +all \code{from} points to all other nodes in \code{graph}. If both \code{from} and \code{to} are +\code{NULL}, pairwise distances are calculated between all nodes in \code{graph}.} \item{k}{Width of exponential spatial interaction function (exp (-d / k)), in units of 'd', specified in one of 3 forms: (i) a single value; (ii) a diff --git a/man/dodgr_times.Rd b/man/dodgr_times.Rd index 35130caa..4a151aaa 100644 --- a/man/dodgr_times.Rd +++ b/man/dodgr_times.Rd @@ -10,19 +10,49 @@ dodgr_times(graph, from = NULL, to = NULL, shortest = FALSE, heap = "BHeap") \item{graph}{\code{data.frame} or equivalent object representing the network graph (see Notes). For \code{dodgr} street networks, this may be a network derived from either \pkg{sf} or \pkg{silicate} ("sc") data, generated with -\link{weight_streetnet}. Note, however, that networks derived from \pkg{sf} -data will generally not produce reliable estimates of times. Accurate -estimates can only be guaranteed by using networks derived from -\pkg{silicate} ("sc") data.} +\link{weight_streetnet}. + +The \code{from} and \code{to} columns of \code{graph} may be either single +columns of numeric or character values specifying the numbers or names of +graph vertices, or combinations to two columns specifying geographical +(longitude and latitude,) coordinates. In the latter case, almost any sensible +combination of names will be accepted (for example, \verb{fromx, fromy}, +\verb{from_x, from_y}, or \verb{fr_lat, fr_lon}.) + +Note that longitude and latitude values are always interpreted in 'dodgr' to +be in EPSG:4326 / WSG84 coordinates. Any other kinds of coordinates should +first be reprojected to EPSG:4326 before submitting to any 'dodgr' routines. + +See further information in Details.} \item{from}{Vector or matrix of points \strong{from} which route distances are to -be calculated (see Notes)} +be calculated, specified as one of the following: +\itemize{ +\item Single character vector precisely matching node numbers or names +given in \code{graph$from} or \code{graph$to}. +\item Single vector of integer-ish values, in which case these will be +presumed to specify indices into \link{dodgr_vertices}, and NOT to +correspond to values in the 'from' or 'to' columns of the graph. See the +example below for a demonstration. +\item Matrix or equivalent of longitude and latitude coordinates, in which +case these will be matched on to the nearest coordinates of 'from' and 'to' +points in the graph. +}} \item{to}{Vector or matrix of points \strong{to} which route distances are to be -calculated (see Notes)} +calculated. If \code{to} is \code{NULL}, pairwise distances will be calculated from +all \code{from} points to all other nodes in \code{graph}. If both \code{from} and \code{to} are +\code{NULL}, pairwise distances are calculated between all nodes in \code{graph}.} -\item{shortest}{If \code{TRUE}, calculate times along the \emph{shortest} rather -than fastest paths.} +\item{shortest}{If \code{FALSE}, calculate distances along the \emph{fastest} +rather than shortest routes. For street networks produced with +\link{weight_streetnet}, distances may also be calculated along the +\emph{fastest} routes with the \code{shortest = FALSE} option. Graphs must in +this case have columns of \code{time} and \code{time_weighted}. Note that the fastest +routes will only be approximate when derived from \pkg{sf}-format data +generated with the \pkg{osmdata} function \code{osmdata_sf()}, and will be much +more accurate when derived from \code{sc}-format data generated with +\code{osmdata_sc()}. See \link{weight_streetnet} for details.} \item{heap}{Type of heap to use in priority queue. Options include Fibonacci Heap (default; \code{FHeap}), Binary Heap (\code{BHeap}), @@ -34,7 +64,7 @@ square matrix of distances between nodes \description{ Calculate matrix of pair-wise travel times between points. } -\note{ +\details{ \code{graph} must minimally contain three columns of \code{from}, \code{to}, \code{dist}. If an additional column named \code{weight} or \code{wt} is present, shortest paths are calculated according to values @@ -44,48 +74,6 @@ by default according to values of \code{dist}. That is, paths between any pair o points will be calculated according to the minimal total sum of \code{weight} values (if present), while reported distances will be total sums of \code{dist} values. - -For street networks produced with \link{weight_streetnet}, distances may also -be calculated along the \emph{fastest} routes with the \code{shortest = FALSE} -option. Graphs must in this case have columns of \code{time} and \code{time_weighted}. -Note that the fastest routes will only be approximate when derived from -\pkg{sf}-format data generated with the \pkg{osmdata} function -\code{osmdata_sf()}, and will be much more accurate when derived from \code{sc}-format -data generated with \code{osmdata_sc()}. See \link{weight_streetnet} for details. - -The \code{from} and \code{to} columns of \code{graph} may be either single -columns of numeric or character values specifying the numbers or names of -graph vertices, or combinations to two columns specifying geographical -(longitude and latitude) coordinates. In the latter case, almost any sensible -combination of names will be accepted (for example, \verb{fromx, fromy}, -\verb{from_x, from_y}, or \verb{fr_lat, fr_lon}.) - -The \code{from} and \code{to} parameters passed to this function can be either: -\itemize{ -\item Single character vectors precisely matching node numbers or names -given in \code{graph$from} or \code{graph$to}. -\item Single vectors of integer-ish values, in which case these will be -presumed to specify indices into \link{dodgr_vertices}, and NOT to -correspond to values in the "from" or "to" columns of the graph. See the -example below for a demonstration. -\item matrices or equivalent of longitude and latitude coordinates, in which -case these will be matched on to the nearest coordinates of "from" and "to" -points in the graph. -} - -If \code{to} is \code{NULL}, pairwise distances will be calculated from all \code{from} -points to all other nodes in \code{graph}. If both \code{from} and \code{to} are \code{NULL}, -pairwise distances are calculated between all nodes in \code{graph}. - -Calculations in parallel (\code{parallel = TRUE}) ought very generally be -advantageous. For small graphs, calculating distances in parallel is likely -to offer relatively little gain in speed, but increases from parallel -computation will generally markedly increase with increasing graph sizes. -By default, parallel computation uses the maximal number of available cores -or threads. This number can be reduced by specifying a value via -\verb{RcppParallel::setThreadOptions (numThreads = )}. Parallel -calculations are, however, not able to be interrupted (for example, by -\code{Ctrl-C}), and can only be stopped by killing the R process. } \examples{ # A simple graph