In JohannesFriedrich/senseBox: senseBox API Wrapper

knitr::opts_chunk$set(echo = TRUE, 
                      fig.align = "center")

Motivation

The senseBox is a do-it-yourself kit for stationary and mobile sensor stations. With senseBox you can make measurements, helping to answer a variety of scientific questions and to support Citizen Science Projects from the local to global scale. Data collected by senseBox can increase the measured density of various enviromental factors and can contribute to more precise statements regarding climate, pollution or traffic.

openSenseMap is the platform for the publishing of senseBox and other open sensor data. Each senseBox transmits its measurements directly to the map, where anyone can observe, analyze and download the data.

This is the point where this R-pacakge comes into play: The R-package senseBox provides access to the senseBox API and enables the user to download, analyse and visualise the data provided by registered senseBoxes.

With pacakges like ggplot2 or plotly R is the perfect tool to visualise data. In the next chapter you find a short introduction to the basic usage of this R-package and some examples how to visualise the data.

Usage

Get some information about the senseBox project and list all senseBoxIds

library(senseBox)

stats <- get_senseBox_stats()

knitr::kable(
  stats, format = "html"
)

With the function get_senseBox_Ids() you obtain all available senseBox Ids and the name of the staion.

Id_list <- get_senseBox_Ids()

knitr::kable(
  head(Id_list),
  format = "html")

You are just interested in senseBoxes, which collect data from "indoor"? So use the function search_senseBox().

indoor <- search_senseBox(exposure =  "indoor")

knitr::kable(
  head(indoor, 3),
  format = "html")

We chose one ID for the following examples

senseBoxId <- "592ca4b851d3460011ea2635"

Show location of senseBox

location <- get_senseBox_location(senseBoxId)

library(leaflet)
library(htmltools)

leaflet(location) %>%
  addProviderTiles(providers$OpenStreetMap) %>% 
  addTiles() %>%  
  addMarkers(~long, ~lat, popup = ~htmltools::htmlEscape(name))

Sensor Id information

Get some information about the senseBox sensors

sensor_info <- get_senseBox_sensor_info(senseBoxId)

knitr::kable(
  sensor_info,
  format = "html"
)

With the argument tidy = TRUE a tidy data.frame will be produced:

sensor_info <- get_senseBox_sensor_info(senseBoxId, tidy = TRUE)

knitr::kable(
  sensor_info,
  format = "html"
)

Download senseBox data

We can now download data from the senseBox, either from a specific sensorId or from all sensors within the sensBox. In the following we are downloading all available sensors.

data_all <- get_senseBox_data(senseBoxId)

When you are interested in just a selection of sensors, just submit the sensorIds to the function get_senseBox_data().

sensor_ids <- get_senseBox_sensor_Ids(senseBoxId)

data_sel <- get_senseBox_data(senseBoxId, 
                              sensorId = sensor_ids$sensorIds[1:2])

When using the above code, by default, the data from the last 48 h will be downloaded. You can donwload up to 10,000 records and sepcify the date of the record. The maximum time frame for downloading data is back to one month from now. Use the argument fromDate and toDate to specify the desired time frame. Note that in contrast to the code above, all sensors from the senseBox are requested (by default) because argument sensorId is not set.

data_timeframe <- get_senseBox_data(senseBoxId, 
                                    fromDate = "2017-11-11 11:11:11", 
                                    toDate = "2017-11-12 11:11:11")

Visualising the results from all sensors is one of the main aims and we recommend using the R-package ggplot2. We provide a sample code next and you just have to change the data executed in the function melt().

library(ggplot2)
library(reshape2)
library(scales)


data_melt <- melt(data_timeframe, id.vars = c("createdAt", "value"))

ggplot(data_melt, aes(x = createdAt, y = value, colour = L2)) +
  geom_line() +
  scale_x_datetime(labels = date_format("%H:%M", tz = Sys.timezone())) +
  facet_wrap(~L2, scales = "free") +
  theme(legend.position = "bottom",
        legend.title = element_blank())

Download archived data

Receiving data with get_senseBox_data() is limited to 10.000 data points. But every day all measured sensor data are stored in the senseBox archive. With the function get_senseBox_archive() the zip file from a specific senseBox for a date can be downloaded. You have to unzip the folder by yourself and every sensor data is stored in a csv file.

get_senseBox_archive(senseBoxId,
                    date = "2018-07-31")

Some senseBox statistics

infos <- get_senseBox_info(Id_list$senseBoxId, parallel = TRUE)

library(dplyr)
library(tidyr)

infos %>% 
  select(name, phenomena) %>%  
  unnest() %>% 
  count(phenomena) %>% 
  arrange(desc(n)) %>% 
  top_n(10, n) %>% 
  ggplot() +
  geom_histogram(aes(x = phenomena, y = n), stat = "identity") +
  theme(axis.text.x = element_text(angle = 45, hjust = 1))

infos %>% 
  group_by(exposure, grouptag) %>% 
  summarise(n = n()) %>% 
  arrange(desc(n)) %>% 
  na.omit() %>% 
  top_n(5, n) %>% 

  ggplot() +
  geom_bar(aes(x = grouptag, y = n, fill = exposure), stat = "identity") +
  theme(axis.text.x = element_text(angle = 45, hjust = 1))

library(lubridate)

infos %>% 
 mutate(year = year(createdAt),
        month = month(createdAt),
        day = day(createdAt)) %>% 
  group_by(year, exposure) %>% 
  summarise(n = n()) %>% 
  arrange(desc(year)) %>% 

  ggplot() +
  geom_bar(aes(x = year, y = n, fill = exposure), stat = "identity")