From 4b24aa9582d5a54aa4946ed11619a3513dd9d903 Mon Sep 17 00:00:00 2001 From: jan Date: Wed, 1 Feb 2023 12:47:36 +0100 Subject: [PATCH] updated manual --- man/opensensmapr.Rd | 9 +++++-- man/osem_box.Rd | 2 +- man/osem_boxes.Rd | 23 ++++++++++++++---- man/osem_ensure_api_available.Rd | 17 ++++++++++++++ man/osem_measurements.Rd | 40 +++++++++++++++++++++++--------- man/osem_measurements_archive.Rd | 22 +++++++++++------- man/osem_phenomena.Rd | 4 ++-- 7 files changed, 89 insertions(+), 28 deletions(-) create mode 100644 man/osem_ensure_api_available.Rd diff --git a/man/opensensmapr.Rd b/man/opensensmapr.Rd index 01d582a..30203dc 100644 --- a/man/opensensmapr.Rd +++ b/man/opensensmapr.Rd @@ -112,11 +112,16 @@ openSenseMap API: \url{https://api.opensensemap.org/} official openSenseMap API documentation: \url{https://docs.opensensemap.org/} } \author{ -\strong{Maintainer}: Norwin Roosen \email{hello@nroo.de} +\strong{Maintainer}: Jan Stenkamp \email{jan.stenkamp@uni-muenster.de} [contributor] + +Authors: +\itemize{ + \item Norwin Roosen \email{hello@nroo.de} +} Other contributors: \itemize{ - \item Daniel Nuest \email{daniel.nuest@uni-muenster.de} (0000-0003-2392-6140) [contributor] + \item Daniel Nuest \email{daniel.nuest@uni-muenster.de} (\href{https://orcid.org/0000-0003-2392-6140}{ORCID}) [contributor] } } diff --git a/man/osem_box.Rd b/man/osem_box.Rd index cb6c629..3e95526 100644 --- a/man/osem_box.Rd +++ b/man/osem_box.Rd @@ -21,7 +21,7 @@ A \code{sensebox data.frame} containing a box in each row Get a single senseBox by its ID } \examples{ -\donttest{ +\dontrun{ # get a specific box by ID b = osem_box('57000b8745fd40c8196ad04c') diff --git a/man/osem_boxes.Rd b/man/osem_boxes.Rd index a7b13ad..9b4ffa5 100644 --- a/man/osem_boxes.Rd +++ b/man/osem_boxes.Rd @@ -4,9 +4,19 @@ \alias{osem_boxes} \title{Get a set of senseBoxes from the openSenseMap} \usage{ -osem_boxes(exposure = NA, model = NA, grouptag = NA, date = NA, - from = NA, to = NA, phenomenon = NA, endpoint = osem_endpoint(), - progress = TRUE, cache = NA) +osem_boxes( + exposure = NA, + model = NA, + grouptag = NA, + date = NA, + from = NA, + to = NA, + phenomenon = NA, + bbox = NA, + endpoint = osem_endpoint(), + progress = TRUE, + cache = NA +) } \arguments{ \item{exposure}{Only return boxes with the given exposure ('indoor', 'outdoor', 'mobile')} @@ -24,6 +34,11 @@ osem_boxes(exposure = NA, model = NA, grouptag = NA, date = NA, \item{phenomenon}{Only return boxes that measured the given phenomenon in the time interval as specified through \code{date} or \code{from / to}} +\item{bbox}{Only return boxes that are within the given boundingbox, +vector of 4 WGS84 coordinates. +Order is: longitude southwest, latitude southwest, longitude northeast, latitude northeast. +Minimal and maximal values are: -180, 180 for longitude and -90, 90 for latitude.} + \item{endpoint}{The URL of the openSenseMap API instance} \item{progress}{Whether to print download progress information, defaults to \code{TRUE}} @@ -46,7 +61,7 @@ Note that some filters do not work together: } \examples{ -\donttest{ +\dontrun{ # get *all* boxes available on the API b = osem_boxes() diff --git a/man/osem_ensure_api_available.Rd b/man/osem_ensure_api_available.Rd new file mode 100644 index 0000000..40520c9 --- /dev/null +++ b/man/osem_ensure_api_available.Rd @@ -0,0 +1,17 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/api.R +\name{osem_ensure_api_available} +\alias{osem_ensure_api_available} +\title{Check if the given openSenseMap API endpoint is available} +\usage{ +osem_ensure_api_available(endpoint = osem_endpoint()) +} +\arguments{ +\item{endpoint}{The API base URL to check, defaulting to \code{\link{osem_endpoint}}} +} +\value{ +\code{TRUE} if the API is available, otherwise \code{stop()} is called. +} +\description{ +Check if the given openSenseMap API endpoint is available +} diff --git a/man/osem_measurements.Rd b/man/osem_measurements.Rd index 07f8953..04a1d26 100644 --- a/man/osem_measurements.Rd +++ b/man/osem_measurements.Rd @@ -11,13 +11,31 @@ osem_measurements(x, ...) \method{osem_measurements}{default}(x, ...) -\method{osem_measurements}{bbox}(x, phenomenon, exposure = NA, - from = NA, to = NA, columns = NA, ..., - endpoint = osem_endpoint(), progress = T, cache = NA) - -\method{osem_measurements}{sensebox}(x, phenomenon, exposure = NA, - from = NA, to = NA, columns = NA, ..., - endpoint = osem_endpoint(), progress = T, cache = NA) +\method{osem_measurements}{bbox}( + x, + phenomenon, + exposure = NA, + from = NA, + to = NA, + columns = NA, + ..., + endpoint = osem_endpoint(), + progress = T, + cache = NA +) + +\method{osem_measurements}{sensebox}( + x, + phenomenon, + exposure = NA, + from = NA, + to = NA, + columns = NA, + ..., + endpoint = osem_endpoint(), + progress = T, + cache = NA +) } \arguments{ \item{x}{Depending on the method, either @@ -58,13 +76,13 @@ a bounding box spanning the whole world. } \section{Methods (by class)}{ \itemize{ -\item \code{default}: Get measurements from \strong{all} senseBoxes. +\item \code{osem_measurements(default)}: Get measurements from \strong{all} senseBoxes. -\item \code{bbox}: Get measurements by a spatial filter. +\item \code{osem_measurements(bbox)}: Get measurements by a spatial filter. -\item \code{sensebox}: Get measurements from a set of senseBoxes. -}} +\item \code{osem_measurements(sensebox)}: Get measurements from a set of senseBoxes. +}} \examples{ \donttest{ # get measurements from all boxes on the phenomenon 'PM10' from the last 48h diff --git a/man/osem_measurements_archive.Rd b/man/osem_measurements_archive.Rd index 1b21d5b..aa32e05 100644 --- a/man/osem_measurements_archive.Rd +++ b/man/osem_measurements_archive.Rd @@ -7,8 +7,14 @@ \usage{ osem_measurements_archive(x, ...) -\method{osem_measurements_archive}{sensebox}(x, fromDate, - toDate = fromDate, sensorFilter = ~T, ..., progress = T) +\method{osem_measurements_archive}{sensebox}( + x, + fromDate, + toDate = fromDate, + sensorFilter = ~T, + ..., + progress = T +) } \arguments{ \item{x}{A `sensebox data.frame` of a single box, as retrieved via \code{\link{osem_box}}, @@ -42,15 +48,15 @@ but continue the remaining download. } \section{Methods (by class)}{ \itemize{ -\item \code{sensebox}: Get daywise measurements for one or more sensors of a single box. -}} +\item \code{osem_measurements_archive(sensebox)}: Get daywise measurements for one or more sensors of a single box. +}} \examples{ -# 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 single day + box = osem_box('593bcd656ccf3b0011791f5a') + m = osem_measurements_archive(box, as.POSIXlt('2018-09-13')) + # fetch measurements for a date range and selected sensors sensors = ~ phenomenon \%in\% c('Temperatur', 'Beleuchtungsstärke') m = osem_measurements_archive( diff --git a/man/osem_phenomena.Rd b/man/osem_phenomena.Rd index d75c382..5d01f9c 100644 --- a/man/osem_phenomena.Rd +++ b/man/osem_phenomena.Rd @@ -21,10 +21,10 @@ Get the counts of sensors for each observed phenomenon. } \section{Methods (by class)}{ \itemize{ -\item \code{sensebox}: Get counts of sensors observing each phenomenon +\item \code{osem_phenomena(sensebox)}: Get counts of sensors observing each phenomenon from a set of senseBoxes. -}} +}} \examples{ # get the phenomena for a single senseBox osem_phenomena(osem_box('593bcd656ccf3b0011791f5a'))