From 4d33fa90291912bf8f1a545ed4b859f318acbfb6 Mon Sep 17 00:00:00 2001 From: Norwin Roosen Date: Sat, 20 Oct 2018 01:25:45 +0200 Subject: [PATCH] document osem_measurements_archive --- NAMESPACE | 1 - R/archive.R | 54 ++++++++++++++++++++++++++---------------------- R/opensensmapr.R | 29 ++++++++++++++++++-------- 3 files changed, 49 insertions(+), 35 deletions(-) diff --git a/NAMESPACE b/NAMESPACE index fb3ae8f..6e26815 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -13,7 +13,6 @@ S3method(plot,sensebox) S3method(print,osem_measurements) S3method(print,sensebox) S3method(summary,sensebox) -export(osem_archive_endpoint) export(osem_as_measurements) export(osem_as_sensebox) export(osem_box) diff --git a/R/archive.R b/R/archive.R index 9768674..8bfd17b 100644 --- a/R/archive.R +++ b/R/archive.R @@ -1,22 +1,37 @@ # client for archive.opensensemap.org -# in this archive, a zip bundle for measurements of each box per day is provided. +# in this archive, CSV files for measurements of each sensor per day is provided. -#' Default endpoint for the archive download -#' front end domain is archive.opensensemap.org, but file download -#' is provided via sciebo -#' @export +#' Returns the default endpoint for the archive *download* +#' While the front end domain is archive.opensensemap.org, file downloads +#' are provided via sciebo. osem_archive_endpoint = function () { 'https://uni-muenster.sciebo.de/index.php/s/HyTbguBP4EkqBcp/download?path=/data' } -#' Get day-wise measurements for a single box from the openSenseMap archive. +#' Fetch day-wise measurements for a single box from the openSenseMap archive. #' -#' This function is significantly faster than `osem_measurements()` for large -#' time-frames, as dayly CSV dumps for each sensor from -#' are used. +#' This function is significantly faster than \code{\link{osem_measurements}} for large +#' time-frames, as daily CSV dumps for each sensor from +#' \href{http://archive.opensensemap.org}{archive.opensensemap.org} are used. #' Note that the latest data available is from the previous day. +#' #' By default, data for all sensors of a box is fetched, but you can select a -#' subset with a `dplyr`-style NSE filter expression. +#' subset with a \code{\link[dplyr]{dplyr}}-style NSE filter expression. +#' +#' The function will warn when no data is available in the selected period, +#' but continue the remaining download. +#' +#' @param x A `sensebox data.frame` of a single box, as retrieved via \code{\link{osem_box}}, +#' to download measurements for. +#' @param fromDate Start date for measurement download. +#' @param toDate End date for measurement download (inclusive). +#' @param sensorFilter A NSE formula matching to \code{x$sensors}, selecting a subset of sensors. +#' @param progress Whether to print download progress information, defaults to \code{TRUE}. +#' @return A \code{tbl_df} Containing observations of all selected sensors for each time stamp. +#' +#' @seealso \href{https://archive.opensensemap.org}{openSenseMap archive} +#' @seealso \code{\link{osem_measurements}} +#' @seealso \code{\link{osem_box}} #' #' @export osem_measurements_archive = function (x, ...) UseMethod('osem_measurements_archive') @@ -33,12 +48,11 @@ osem_measurements_archive.default = function (x, ...) { #' more sensors of a single box #' @export #' @examples -#' -#' \donttest{ -#' # fetch measurements for a single day -#' box = osem_box('593bcd656ccf3b0011791f5a') -#' m = osem_measurements_archive(box, as.POSIXlt('2018-09-13')) +#' # fetch measurements for a single day +#' box = osem_box('593bcd656ccf3b0011791f5a') +#' m = osem_measurements_archive(box, as.POSIXlt('2018-09-13')) #' +#' \donttest{ #' # fetch measurements for a date range and selected sensors #' sensors = ~ phenomenon %in% c('Temperatur', 'Beleuchtungsstärke') #' m = osem_measurements_archive(box, as.POSIXlt('2018-09-01'), as.POSIXlt('2018-09-30'), sensorFilter = sensors) @@ -64,16 +78,6 @@ osem_measurements_archive.sensebox = function (x, fromDate, toDate = fromDate, s } #' fetch measurements from archive from a single box, and a single sensor -#' -#' @param box -#' @param sensor -#' @param fromDate -#' @param toDate -#' @param progress -#' -#' @return -#' -#' @examples archive_fetch_measurements = function (box, sensor, fromDate, toDate, progress) { dates = list() from = fromDate diff --git a/R/opensensmapr.R b/R/opensensmapr.R index fe2bcd3..0273df2 100644 --- a/R/opensensmapr.R +++ b/R/opensensmapr.R @@ -37,16 +37,27 @@ #' } #' #' @section Retrieving measurements: -#' Measurements can be retrieved through \code{\link{osem_measurements}} for a -#' given phenomenon only. A subset of measurements may be selected by -#' +#' There are two ways to retrieve measurements: #' \itemize{ -#' \item a list of senseBoxes, previously retrieved through -#' \code{\link{osem_box}} or \code{\link{osem_boxes}}. -#' \item a geographic bounding box, which can be generated with the -#' \code{\link[sf]{sf}} package. -#' \item a time frame -#' \item a exposure type of the given box +#' \item \code{\link{osem_measurements_archive}}: +#' Downloads measurements for a \emph{single box} from the openSenseMap archive. +#' This function does not provide realtime data, but is suitable for long time frames. +#' +#' \item \code{\link{osem_measurements}}: +#' This function retrieves (realtime) measurements from the API. It works for a +#' \emph{single phenomenon} only, but provides various filters to select sensors by +#' +#' \itemize{ +#' \item a list of senseBoxes, previously retrieved through +#' \code{\link{osem_box}} or \code{\link{osem_boxes}}. +#' \item a geographic bounding box, which can be generated with the +#' \code{\link[sf]{sf}} package. +#' \item a time frame +#' \item a exposure type of the given box +#' } +#' +#' Use this function with caution for long time frames, as the API becomes +#' quite slow is limited to 10.000 measurements per 30 day interval. #' } #' #' Data is returned as \code{tibble} with the class \code{osem_measurements}.