From 46d1ce228a12e89ba333f734146f0fa523f4e63b Mon Sep 17 00:00:00 2001 From: JsLth Date: Sat, 17 Aug 2024 03:52:34 +0200 Subject: [PATCH] update docs --- man/ORSJar.Rd | 22 ++++++- man/get_instance.Rd | 51 +++++++++++++--- man/ors_pairwise.Rd | 138 ++++++++++++++++++++++---------------------- 3 files changed, 130 insertions(+), 81 deletions(-) diff --git a/man/ORSJar.Rd b/man/ORSJar.Rd index 4e5fbf2..5e600e0 100644 --- a/man/ORSJar.Rd +++ b/man/ORSJar.Rd @@ -13,7 +13,7 @@ requirement cannot be met, consider using \code{\link{ORSDocker}} or For technical details on the setup of local ORS instances, refer to the \href{https://giscience.github.io/openrouteservice/run-instance/running-jar}{Running JAR documentation}. -For details on how to use \code{ORSDocker} objects, refer to the installation +For details on how to use \code{ORSJar} objects, refer to the installation vignette: \preformatted{ @@ -64,6 +64,7 @@ process running the OpenRouteService instance. Refer to \subsection{Public methods}{ \itemize{ \item \href{#method-ORSJar-new}{\code{ORSJar$new()}} +\item \href{#method-ORSJar-purge}{\code{ORSJar$purge()}} \item \href{#method-ORSJar-set_port}{\code{ORSJar$set_port()}} \item \href{#method-ORSJar-show_logs}{\code{ORSJar$show_logs()}} \item \href{#method-ORSJar-run}{\code{ORSJar$run()}} @@ -127,6 +128,20 @@ spinners, progress bars and system notifications.} } \if{html}{\out{}} } +} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-ORSJar-purge}{}}} +\subsection{Method \code{purge()}}{ +Purge ORS instance, i.e. take down container, (optionally) delete +image, delete ORS directory, and clean up R6 class. + +This method can be useful for testing and writing reproducible +examples and can easily be used together with \code{\link{on.exit}}. +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{ORSJar$purge()}\if{html}{\out{
}} +} + } \if{html}{\out{
}} \if{html}{\out{}} @@ -154,7 +169,7 @@ Port to use. If \code{NULL}, assigns a random port using \subsection{Method \code{show_logs()}}{ Show logs of OpenRouteService. Useful for debugging docker setups. \subsection{Usage}{ -\if{html}{\out{
}}\preformatted{ORSJar$show_logs(source = c("process", "logfile"))}\if{html}{\out{
}} +\if{html}{\out{
}}\preformatted{ORSJar$show_logs(source = c("logfile", "process"))}\if{html}{\out{
}} } \subsection{Arguments}{ @@ -166,7 +181,8 @@ Where to retrieve logs from. If \code{"process"}, reads the standard output from the external process running OpenRouteService. If \code{"logfile"}, reads the log file in the top directory. Generally, the log file provides less information, but stores the logs from -previous runs. The process logs are reset with every run.} +previous runs. The process logs are reset with every run. Process logs +are also much more error-prone.} } \if{html}{\out{}} } diff --git a/man/get_instance.Rd b/man/get_instance.Rd index bd6e13d..0e44ce4 100644 --- a/man/get_instance.Rd +++ b/man/get_instance.Rd @@ -5,27 +5,33 @@ \alias{get_status} \alias{get_profiles} \alias{ors_ready} +\alias{any_mounted} \title{Utility functions} \usage{ get_instance() -get_status(id = NULL) +get_status(url = NULL) -get_profiles(id = NULL, force = TRUE) +get_profiles(url = NULL, force = TRUE) -ors_ready(id = NULL, force = TRUE, error = FALSE) +ors_ready(url = NULL, force = TRUE, error = FALSE) + +any_mounted() } \arguments{ -\item{id}{\code{[character]} +\item{url}{\code{[character]} -ID or name of a container or URL of a server that is to be checked. If -\code{NULL}, retrieves the ID from the current instance set by -\code{\link{ors_instance}}} +URL of an ORS server. Defaults to the the URL of the currently mounted +ORS instance. This argument exists as a way to explicitly specify the URL +to query in case the instance cannot easily be determined. For normal use, +this argument should not need to be specfied.} \item{force}{\code{[logical]} If \code{TRUE}, function must query server. If \code{FALSE}, the information -will be read from the cache if possible.} +will be read from the cache if possible. This argument is specially useful +automated workflows where it is inconvenient to query the server +unnecessarily often.} \item{error}{\code{[logical]} @@ -36,7 +42,7 @@ If \code{TRUE}, gives out an error if the service is not ready.} \code{get_status} returns a list of information on the running service. \code{ors_ready} returns a length-1 logical vector specifying if the service is running. \code{get_profiles} returns a vector containing the active -profiles. +profiles. \code{any_mounted} returns a length-1 logical. } \description{ Utility functions to aid the setup of local instances. @@ -47,6 +53,33 @@ the current session and returns it. \item \code{ors_ready} checks if the mounted service is ready to use. \item \code{get_profiles} is a wrapper around \code{get_status} that returns the active profiles of the mounted service. +\item \code{any_mounted} checks if an instance is mounted to the current +session. +} +} +\examples{ +# initialize an ORS instance +ors <- ors_instance() + +# confirm that instance was mounted +any_mounted() # TRUE + +# retrieve the instance object +get_instance() + +# check if the service is ready +ors_ready() + +# assert the ready status +try(ors_ready(error = TRUE)) + +\dontrun{ +# the following functions require a running service +# retrieve a list of service options from the server +get_status() + +# retrieve a list of active profiles that can be used +get_profiles() } } \seealso{ diff --git a/man/ors_pairwise.Rd b/man/ors_pairwise.Rd index f85a300..86007b5 100644 --- a/man/ors_pairwise.Rd +++ b/man/ors_pairwise.Rd @@ -99,19 +99,26 @@ and if \code{duration}, the shortest temporal distance will be calculated.} } \value{ \code{ors_pairwise} returns a dataframe with distances and -travel durations between source and destination. +travel durations between source and destination. Distances are specified +in the unit given by the \code{units} arguments and durations are specified +in seconds. + \code{ors_shortest_distances} returns a dataframe containing distances, travel durations and the index number of the point of interest with the shortest routing distance to the respective place of the source dataset. -Depending on the \code{geometry} argument, these outputs can either be -simple dataframes or objects of class \code{sf} containing the linestring -geometries of the respective routes. + +Depending on the \code{geometry} argument, the output of both functions can +either be simple dataframes or objects of class \code{sf} containing the +linestring geometries of the respective routes. } \description{ -\code{ors_pairwise} calculates the routing distance between two -datasets using the Directions service from ORS. \code{ors_shortest_distances} -is a wrapper around \code{ors_pairwise} that matches each point of the -source dataset to a dataset of points of interest from the destination dataset +\code{ors_pairwise} calculates the pairwise routing distance between two +datasets using the Directions service from ORS. In other words, routes +are computed between the \emph{i}th row of \code{src} and \code{dst}, +respectively. + +\code{ors_shortest_distances} is a wrapper around \code{ors_pairwise} that +matches each point of the source dataset to a destination dataset and then extracts the route with the shortest distance. } \details{ @@ -133,66 +140,59 @@ can be examined by inspecting its route attributes using } \examples{ -\dontrun{ -data("pharma") - -set.seed(123) -dest <- ors_sample(10) - -car <- "driving-car" -bike <- "cycling-regular" - -# Running with sf objects -route_lengths_sf <- ors_pairwise(pharma, dest, profile = car) -route_lengths_sf - -# Running with coordinate pairs -route_lengths_df <- ors_pairwise(pharma, dest, profile = bike) -route_lengths_df - -# Returns route geometries -route_lengths_geom <- ors_pairwise( - pharma, - dest, - profile = car, - geometry = TRUE -) - -# Returns routes in kilometers -route_lengths_km <- ors_pairwise( - pharma, - dest, - profile = bike, - units = "km" -) - -# Running with additional arguments -route_lengths_opts <- ors_pairwise( - pharma, - dest, - profile = car, - continue_straight = TRUE, - preference = "fastest" -) - -# Finding shortest routes from each point in sample_a to sample_b -shortest_routes <- ors_shortest_distances(pharma, dest, units = "km") -shortest_routes - -# Pre-filter the nearest 5 destination points by Euclidian distance -pois <- get_closest_pois(pharma, dest, n = 5) - -# Only route from each pharmacy to one of the closest 5 destination points -# respectively. For larger datasets, this can increase performance. -nearest_hospitals <- ors_shortest_distances( - pharma, - pois, - group = ".group", - geometry = TRUE -) -nearest_hospitals -} -\dontrun{ - +if (any_mounted() && ors_ready()) { + data("pharma") + + set.seed(123) + dest <- ors_sample(10) + + car <- "driving-car" + bike <- "cycling-regular" + + # Running with sf objects + ors_pairwise(pharma, dest, profile = car) + + # Running with coordinate pairs + ors_pairwise(pharma, dest, profile = bike) + + # Returns route geometries + ors_pairwise( + pharma, + dest, + profile = car, + geometry = TRUE + ) + + # Returns routes in kilometers + ors_pairwise( + pharma, + dest, + profile = bike, + units = "km" + ) + + # Running with additional arguments + ors_pairwise( + pharma, + dest, + profile = car, + continue_straight = TRUE, + preference = "fastest" + ) + + # Finding shortest routes from each point in sample_a to sample_b + ors_shortest_distances(pharma, dest, units = "km") + + # Pre-filter the nearest 5 destination points by Euclidian distance + pois <- get_closest_pois(pharma, dest, n = 5) + + # Only route from each pharmacy to one of the closest 5 destination points + # respectively. For larger datasets, this can increase performance. + ors_shortest_distances( + pharma, + pois, + group = ".group", + geometry = TRUE + ) } }