improve documentation, rebuild docs

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

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:

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

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
+}

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}

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}

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}

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}

man/opensensmapr.Rd

@@ -46,16 +46,27 @@ implemented:
 
 \section{Retrieving measurements}{
 
-Measurements can be retrieved through \code{\link{osem_measurements}} for a
+There are two ways to retrieve measurements:
-given phenomenon only. A subset of measurements may be selected by
-
 \itemize{
-  \item a list of senseBoxes, previously retrieved through
+  \item \code{\link{osem_measurements_archive}}:
-    \code{\link{osem_box}} or \code{\link{osem_boxes}}.
+    Downloads measurements for a \emph{single box} from the openSenseMap archive.
-  \item a geographic bounding box, which can be generated with the
+    This function does not provide realtime data, but is suitable for long time frames.
-    \code{\link[sf]{sf}} package.
+    
-  \item a time frame
+  \item \code{\link{osem_measurements}}:
-  \item a exposure type of the given box
+    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.

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
+\title{Returns the default endpoint for the archive *download*
-front end domain is archive.opensensemap.org, but file download
+While the front end domain is archive.opensensemap.org, file downloads
-is provided via sciebo}
+are provided via sciebo.}
 \usage{
 osem_archive_endpoint()
 }
 \description{
-Default endpoint for the archive download
+Returns the default endpoint for the archive *download*
-front end domain is archive.opensensemap.org, but file download
+While the front end domain is archive.opensensemap.org, file downloads
-is provided via sciebo
+are provided via sciebo.
 }

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.

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, ...)
 

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
+This function is significantly faster than \code{\link{osem_measurements}} for large
-time-frames, as dayly CSV dumps for each sensor from
+time-frames, as daily CSV dumps for each sensor from
-<archive.opensensemap.org> are used.
+\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{
-
+# fetch measurements for a single day
-\donttest{
+box = osem_box('593bcd656ccf3b0011791f5a')
-  # fetch measurements for a single day
+m = osem_measurements_archive(box, as.POSIXlt('2018-09-13'))
-  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}}
+}

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])
 }

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.}

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.}