From 1966c305bc6c1d6fba31f4df22954ef19c010459 Mon Sep 17 00:00:00 2001 From: noerw Date: Fri, 25 May 2018 01:35:57 +0200 Subject: [PATCH] add more examples, fix missing parameter check --- R/box.R | 35 +++++++++++++++++++++++++++-- R/measurement.R | 59 ++++++++++++++++++++++++++++++++++++++++++------- 2 files changed, 84 insertions(+), 10 deletions(-) diff --git a/R/box.R b/R/box.R index b40e45e..2e73a2f 100644 --- a/R/box.R +++ b/R/box.R @@ -40,8 +40,31 @@ #' # get all boxes with grouptag 'ifgi' that are placed outdoors #' b = osem_boxes(grouptag = 'ifgi', exposure = 'outdoor') #' +#' # get all boxes with model 'luftdaten_sds011_dht22' +#' b = osem_boxes(grouptag = 'ifgi') +#' #' # get all boxes that have measured PM2.5 in the last 4 hours #' b = osem_boxes(date = Sys.time(), phenomenon = 'PM2.5') +#' +#' # get all boxes that have measured PM2.5 between Jan & Feb 2018 +#' library(lubridate) +#' b = osem_boxes( +#' from = date('2018-01-01'), +#' to = date('2018-02-01'), +#' phenomenon = 'PM2.5' +#' ) +#' +#' # get all boxes from a custom (selfhosted) openSenseMap API +#' b = osem_box(endpoint = 'http://api.my-custom-osem.com') +#' +#' # get all boxes and cache the response, in order to provide +#' # reproducible results in the future. Also useful for development +#' # to avoid repeated loading times! +#' b = osem_boxes(cache = getwd()) +#' b = osem_boxes(cache = getwd()) +#' +#' # get *all* boxes available on the API, without showing download progress +#' b = osem_boxes(progress = FALSE) #' } osem_boxes = function (exposure = NA, model = NA, grouptag = NA, date = NA, from = NA, to = NA, phenomenon = NA, @@ -95,9 +118,17 @@ osem_boxes = function (exposure = NA, model = NA, grouptag = NA, #' @seealso \code{\link{osem_clear_cache}} #' @export #' @examples -#' # get a specific box by ID -#' b = osem_box('57000b8745fd40c8196ad04c') +#' \donttest{ +#' # get a specific box by ID +#' b = osem_box('57000b8745fd40c8196ad04c') #' +#' # get a specific box by ID from a custom (selfhosted) openSenseMap API +#' b = osem_box('51030b8725fd30c2196277da', 'http://api.my-custom-osem.com') +#' +#' # get a specific box by ID and cache the response, in order to provide +#' # reproducible results in the future. +#' b = osem_box('51030b8725fd30c2196277da', cache = tempdir()) +#' } osem_box = function (boxId, endpoint = osem_endpoint(), cache = NA) { get_box_(boxId, endpoint = endpoint, cache = cache) } diff --git a/R/measurement.R b/R/measurement.R index 0fe1cce..103c9fd 100644 --- a/R/measurement.R +++ b/R/measurement.R @@ -40,8 +40,27 @@ osem_measurements = function (x, ...) UseMethod('osem_measurements') #' @export #' @examples #' \donttest{ -#' # get measurements from all boxes -#' m1 = osem_measurements('Windrichtung') +#' # get measurements from all boxes on the phenomenon 'PM10' from the last 48h +#' m = osem_measurements('PM10') +#' +#' # get measurements from all mobile boxes on the phenomenon 'PM10' from the last 48h +#' m = osem_measurements('PM10', exposure = 'mobile') +#' +#' # get measurements and cache them locally in the working directory. +#' # subsequent identical requests will load from the cache instead, ensuring +#' # reproducibility and saving time and bandwidth! +#' m = osem_measurements('PM10', exposure = 'mobile', cache = getwd()) +#' m = osem_measurements('PM10', exposure = 'mobile', cache = getwd()) +#' +#' # get measurements returning a custom selection of columns +#' m = osem_measurements('PM10', exposure = 'mobile', columns = c( +#' 'value', +#' 'boxId', +#' 'sensorType', +#' 'lat', +#' 'lon', +#' 'height' +#' )) #' } osem_measurements.default = function (x, ...) { bbox = structure(c(-180, -90, 180, 90), class = 'bbox') @@ -54,13 +73,26 @@ osem_measurements.default = function (x, ...) { #' @export #' @examples #' \donttest{ -#' # get measurements from sensors within a bounding box +#' # get measurements from sensors within a custom WGS84 bounding box #' bbox = structure(c(7, 51, 8, 52), class = 'bbox') -#' m2 = osem_measurements(bbox, 'Temperatur') +#' m = osem_measurements(bbox, 'Temperatur') #' -#' points = sf::st_multipoint(matrix(c(7.5, 7.8, 51.7, 52), 2, 2)) -#' bbox2 = sf::st_bbox(points) -#' m3 = osem_measurements(bbox2, 'Temperatur', exposure = 'outdoor') +#' # construct a bounding box 12km around berlin using the sf package, +#' # and get measurements from stations within that box +#' library(sf) +#' bbox2 = st_point(c(13.4034, 52.5120)) %>% +#' st_sfc(crs = 4326) %>% +#' st_transform(3857) %>% # allow setting a buffer in meters +#' st_buffer(set_units(12, km)) %>% +#' st_transform(4326) %>% # the opensensemap expects WGS 84 +#' st_bbox() +#' m = osem_measurements(bbox2, 'Temperatur', exposure = 'outdoor') +#' +#' # construct a bounding box from two points, +#' # and get measurements from stations within that box +#' points = st_multipoint(matrix(c(7.5, 7.8, 51.7, 52), 2, 2)) +#' bbox3 = st_bbox(points) +#' m = osem_measurements(bbox2, 'Temperatur', exposure = 'outdoor') #' } osem_measurements.bbox = function (x, phenomenon, exposure = NA, from = NA, to = NA, columns = NA, @@ -88,6 +120,17 @@ osem_measurements.bbox = function (x, phenomenon, exposure = NA, #' # ...or a single box #' b = osem_box('57000b8745fd40c8196ad04c') #' m5 = osem_measurements(b, phenomenon = 'Temperatur') +#' +#' # get measurements from a single box on the from the last 40 days. +#' # requests are paged for long time frames, so the APIs limitation +#' # does not apply! +#' library(lubridate) +#' m1 = osem_measurements( +#' b, +#' 'Temperatur', +#' to = now(), +#' from = now() - days(40) +#' ) #' } osem_measurements.sensebox = function (x, phenomenon, exposure = NA, from = NA, to = NA, columns = NA, @@ -112,7 +155,7 @@ osem_measurements.sensebox = function (x, phenomenon, exposure = NA, #' @return A named \code{list} of parsed parameters. #' @noRd parse_get_measurements_params = function (params) { - if (is.null(params$phenomenon) | is.na(params$phenomenon)) + if (is.symbol(params$phenomenon) || is.null(params$phenomenon) || is.na(params$phenomenon)) stop('Parameter "phenomenon" is required') if (