From ddc6289ce39af232257986a1037fda226004fb38 Mon Sep 17 00:00:00 2001 From: Norwin Roosen Date: Sat, 20 Oct 2018 01:51:17 +0200 Subject: [PATCH] improve documentation, rebuild docs --- R/measurement.R | 2 +- R/opensensmapr.R | 8 ++++++ README.md | 34 ++++++++++++++++++++++- man/archive_fetch_measurements.Rd | 11 ++++++++ man/filter.osem_measurements.Rd | 4 +-- man/filter.sensebox.Rd | 4 +-- man/mutate.osem_measurements.Rd | 4 +-- man/mutate.sensebox.Rd | 4 +-- man/opensensmapr.Rd | 39 ++++++++++++++++++++------ man/osem_archive_endpoint.Rd | 12 ++++---- man/osem_as_measurements.Rd | 3 +- man/osem_measurements.Rd | 2 +- man/osem_measurements_archive.Rd | 46 ++++++++++++++++++++++++------- man/osem_phenomena.Rd | 12 ++++---- man/st_as_sf.osem_measurements.Rd | 2 +- man/st_as_sf.sensebox.Rd | 2 +- 16 files changed, 144 insertions(+), 45 deletions(-) create mode 100644 man/archive_fetch_measurements.Rd diff --git a/R/measurement.R b/R/measurement.R index 103c9fd..591c4cb 100644 --- a/R/measurement.R +++ b/R/measurement.R @@ -1,6 +1,6 @@ # ============================================================================== # -#' Get the Measurements of a Phenomenon on opensensemap.org +#' Fetch the Measurements of a Phenomenon on opensensemap.org #' #' Measurements can be retrieved either for a set of boxes, or through a spatial #' bounding box filter. To get all measurements, the \code{default} function applies diff --git a/R/opensensmapr.R b/R/opensensmapr.R index 0273df2..6e6b8a5 100644 --- a/R/opensensmapr.R +++ b/R/opensensmapr.R @@ -65,6 +65,14 @@ #' @section Retrieving statistics: #' Count statistics about the database are provided with \code{\link{osem_counts}}. #' +#' @section Using a different API instance / endpoint: +#' You can override the functions \code{osem_endpoint} and \code{osem_endpoint_archive} +#' inside the package namespace: +#' +#' \code{ +#' assignInNamespace("osem_endpoint", function() "http://mynewosem.org", "opensensmapr") +#' } +#' #' @section Integration with other packages: #' The package aims to be compatible with the tidyverse. #' Helpers are implemented to ease the further usage of the retrieved data: diff --git a/README.md b/README.md index 9ad21d7..9e131db 100644 --- a/README.md +++ b/README.md @@ -68,6 +68,20 @@ Where feasible, also add tests for the added / changed functionality in `tests/t Please note that this project is released with a [Contributor Code of Conduct](CONDUCT.md). By participating in this project you agree to abide by its terms. +### development environment + +To set up the development environment for testing and checking, all suggested packages should be installed. +On linux, these require some system dependencies: +```sh +# install dependencies for sf (see https://github.com/r-spatial/sf#installing) +sudo dnf install gdal-devel proj-devel proj-epsg proj-nad geos-devel udunits2-devel + +# install suggested packages +R -e "install.packages(c('maps', 'maptools', 'tibble', 'rgeos', 'sf', + 'knitr', 'rmarkdown', 'lubridate', 'units', 'jsonlite', 'ggplot2', + 'zoo', 'lintr', 'testthat', 'covr')" +``` + ### build To build the package, either use `devtools::build()` or run @@ -75,12 +89,30 @@ To build the package, either use `devtools::build()` or run R CMD build . ``` -next run the tests and checks: +Next, run the **tests and checks**: ```sh R CMD check --as-cran ../opensensmapr_*.tar.gz # alternatively, if you're in a hurry: R CMD check --no-vignettes ../opensensmapr_*.tar.gz ``` + +### release + +To create a release: + +0. make shure you are on master branch +1. run the tests and checks as described above +2. bump the version in `DESCRIPTION` +3. update `CHANGES.md` +3. rebuild the documentation: `R -e 'devtools::document()'` +4. build the package again with the new version: `R CMD build . --no-build-vignettes` +5. tag the commit with the new version: `git tag v0.5.0` +6. push changes: `git push && git push --tags` +7. wait for *all* CI tests to complete successfully (helps in the next step) +8. [upload the new release to CRAN](https://cran.r-project.org/submit.html) +9. get back to the enjoyable parts of your life & hope you won't get bad mail next week. + + ## License GPL-2.0 - Norwin Roosen diff --git a/man/archive_fetch_measurements.Rd b/man/archive_fetch_measurements.Rd new file mode 100644 index 0000000..6754ef4 --- /dev/null +++ b/man/archive_fetch_measurements.Rd @@ -0,0 +1,11 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/archive.R +\name{archive_fetch_measurements} +\alias{archive_fetch_measurements} +\title{fetch measurements from archive from a single box, and a single sensor} +\usage{ +archive_fetch_measurements(box, sensor, fromDate, toDate, progress) +} +\description{ +fetch measurements from archive from a single box, and a single sensor +} diff --git a/man/filter.osem_measurements.Rd b/man/filter.osem_measurements.Rd index ae9ecc4..316c030 100644 --- a/man/filter.osem_measurements.Rd +++ b/man/filter.osem_measurements.Rd @@ -1,10 +1,10 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/measurement_utils.R +% Please edit documentation in R/external_generics.R \name{filter.osem_measurements} \alias{filter.osem_measurements} \title{Return rows with matching conditions, while maintaining class & attributes} \usage{ -\method{filter}{osem_measurements}(.data, ..., .dots) +filter.osem_measurements(.data, ..., .dots) } \arguments{ \item{.data}{A osem_measurements data.frame to filter} diff --git a/man/filter.sensebox.Rd b/man/filter.sensebox.Rd index 1cbb6dd..1696972 100644 --- a/man/filter.sensebox.Rd +++ b/man/filter.sensebox.Rd @@ -1,10 +1,10 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/box_utils.R +% Please edit documentation in R/external_generics.R \name{filter.sensebox} \alias{filter.sensebox} \title{Return rows with matching conditions, while maintaining class & attributes} \usage{ -\method{filter}{sensebox}(.data, ..., .dots) +filter.sensebox(.data, ..., .dots) } \arguments{ \item{.data}{A sensebox data.frame to filter} diff --git a/man/mutate.osem_measurements.Rd b/man/mutate.osem_measurements.Rd index 32e3963..136abfb 100644 --- a/man/mutate.osem_measurements.Rd +++ b/man/mutate.osem_measurements.Rd @@ -1,10 +1,10 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/measurement_utils.R +% Please edit documentation in R/external_generics.R \name{mutate.osem_measurements} \alias{mutate.osem_measurements} \title{Add new variables to the data, while maintaining class & attributes} \usage{ -\method{mutate}{osem_measurements}(.data, ..., .dots) +mutate.osem_measurements(.data, ..., .dots) } \arguments{ \item{.data}{A osem_measurements data.frame to mutate} diff --git a/man/mutate.sensebox.Rd b/man/mutate.sensebox.Rd index 1dabe83..ee95a86 100644 --- a/man/mutate.sensebox.Rd +++ b/man/mutate.sensebox.Rd @@ -1,10 +1,10 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/box_utils.R +% Please edit documentation in R/external_generics.R \name{mutate.sensebox} \alias{mutate.sensebox} \title{Add new variables to the data, while maintaining class & attributes} \usage{ -\method{mutate}{sensebox}(.data, ..., .dots) +mutate.sensebox(.data, ..., .dots) } \arguments{ \item{.data}{A sensebox data.frame to mutate} diff --git a/man/opensensmapr.Rd b/man/opensensmapr.Rd index 48a3066..01d582a 100644 --- a/man/opensensmapr.Rd +++ b/man/opensensmapr.Rd @@ -46,16 +46,27 @@ implemented: \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}. @@ -66,6 +77,16 @@ Data is returned as \code{tibble} with the class \code{osem_measurements}. Count statistics about the database are provided with \code{\link{osem_counts}}. } +\section{Using a different API instance / endpoint}{ + +You can override the functions \code{osem_endpoint} and \code{osem_endpoint_archive} +inside the package namespace: + +\code{ + assignInNamespace("osem_endpoint", function() "http://mynewosem.org", "opensensmapr") +} +} + \section{Integration with other packages}{ The package aims to be compatible with the tidyverse. diff --git a/man/osem_archive_endpoint.Rd b/man/osem_archive_endpoint.Rd index b7cdab3..b71adf8 100644 --- a/man/osem_archive_endpoint.Rd +++ b/man/osem_archive_endpoint.Rd @@ -2,14 +2,14 @@ % Please edit documentation in R/archive.R \name{osem_archive_endpoint} \alias{osem_archive_endpoint} -\title{Default endpoint for the archive download -front end domain is archive.opensensemap.org, but file download -is provided via sciebo} +\title{Returns the default endpoint for the archive *download* +While the front end domain is archive.opensensemap.org, file downloads +are provided via sciebo.} \usage{ osem_archive_endpoint() } \description{ -Default endpoint for the archive download -front end domain is archive.opensensemap.org, but file download -is provided via sciebo +Returns the default endpoint for the archive *download* +While the front end domain is archive.opensensemap.org, file downloads +are provided via sciebo. } diff --git a/man/osem_as_measurements.Rd b/man/osem_as_measurements.Rd index ccb0544..2db6dd5 100644 --- a/man/osem_as_measurements.Rd +++ b/man/osem_as_measurements.Rd @@ -7,7 +7,8 @@ osem_as_measurements(x) } \arguments{ -\item{x}{A data.frame to attach the class to} +\item{x}{A data.frame to attach the class to. +Should have at least a `value` and `createdAt` column.} } \description{ Converts a foreign object to an osem_measurements data.frame. diff --git a/man/osem_measurements.Rd b/man/osem_measurements.Rd index 428c373..07f8953 100644 --- a/man/osem_measurements.Rd +++ b/man/osem_measurements.Rd @@ -5,7 +5,7 @@ \alias{osem_measurements.default} \alias{osem_measurements.bbox} \alias{osem_measurements.sensebox} -\title{Get the Measurements of a Phenomenon on opensensemap.org} +\title{Fetch the Measurements of a Phenomenon on opensensemap.org} \usage{ osem_measurements(x, ...) diff --git a/man/osem_measurements_archive.Rd b/man/osem_measurements_archive.Rd index 7a30334..a9fdcac 100644 --- a/man/osem_measurements_archive.Rd +++ b/man/osem_measurements_archive.Rd @@ -3,20 +3,40 @@ \name{osem_measurements_archive} \alias{osem_measurements_archive} \alias{osem_measurements_archive.sensebox} -\title{Get day-wise measurements for a single box from the openSenseMap archive.} +\title{Fetch day-wise measurements for a single box from the openSenseMap archive.} \usage{ osem_measurements_archive(x, ...) \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}}, +to download measurements for.} + +\item{fromDate}{Start date for measurement download.} + +\item{toDate}{End date for measurement download (inclusive).} + +\item{sensorFilter}{A NSE formula matching to \code{x$sensors}, selecting a subset of sensors.} + +\item{progress}{Whether to print download progress information, defaults to \code{TRUE}.} +} +\value{ +A \code{tbl_df} Containing observations of all selected sensors for each time stamp. +} \description{ -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. +} +\details{ 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. } \section{Methods (by class)}{ \itemize{ @@ -25,14 +45,20 @@ more sensors of a single box }} \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) } } +\seealso{ +\href{https://archive.opensensemap.org}{openSenseMap archive} + +\code{\link{osem_measurements}} + +\code{\link{osem_box}} +} diff --git a/man/osem_phenomena.Rd b/man/osem_phenomena.Rd index 7f744e0..d75c382 100644 --- a/man/osem_phenomena.Rd +++ b/man/osem_phenomena.Rd @@ -29,13 +29,13 @@ from a set of senseBoxes. # get the phenomena for a single senseBox osem_phenomena(osem_box('593bcd656ccf3b0011791f5a')) -# get the phenomena for a group of senseBoxes -osem_phenomena( - osem_boxes(grouptag = 'ifgi', exposure = 'outdoor', date = Sys.time()) -) - -# get phenomena with at least 30 sensors on opensensemap \donttest{ + # get the phenomena for a group of senseBoxes + osem_phenomena( + osem_boxes(grouptag = 'ifgi', exposure = 'outdoor', date = Sys.time()) + ) + + # get phenomena with at least 30 sensors on opensensemap phenoms = osem_phenomena(osem_boxes()) names(phenoms[phenoms > 29]) } diff --git a/man/st_as_sf.osem_measurements.Rd b/man/st_as_sf.osem_measurements.Rd index f541a36..8d46632 100644 --- a/man/st_as_sf.osem_measurements.Rd +++ b/man/st_as_sf.osem_measurements.Rd @@ -1,5 +1,5 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/measurement_utils.R +% Please edit documentation in R/external_generics.R \name{st_as_sf.osem_measurements} \alias{st_as_sf.osem_measurements} \title{Convert a \code{osem_measurements} dataframe to an \code{\link[sf]{st_sf}} object.} diff --git a/man/st_as_sf.sensebox.Rd b/man/st_as_sf.sensebox.Rd index f28a4f7..eeffbd8 100644 --- a/man/st_as_sf.sensebox.Rd +++ b/man/st_as_sf.sensebox.Rd @@ -1,5 +1,5 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/box_utils.R +% Please edit documentation in R/external_generics.R \name{st_as_sf.sensebox} \alias{st_as_sf.sensebox} \title{Convert a \code{sensebox} dataframe to an \code{\link[sf]{st_sf}} object.}