README.Rmd

---
output: rmarkdown::github_document
always_allow_html: yes
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, echo = FALSE}
knitr::opts_chunk$set(collapse = TRUE, 
                      comment = "##", 
                      fig.retina = 2, 
                      fig.path = "README_figs/README-")
```

<!-- badges: start -->
[![R-CMD-check](https://github.com/JohannesFriedrich/senseBox/workflows/R-CMD-check/badge.svg)](https://github.com/JohannesFriedrich/senseBox/actions)
[![Build status](https://ci.appveyor.com/api/projects/status/oljck059k9io6qe7/branch/master?svg=true)](https://ci.appveyor.com/project/JohannesFriedrich/sensebox/branch/master)
[![Coverage Status](https://codecov.io/gh/JohannesFriedrich/senseBox/branch/master/graph/badge.svg)](https://codecov.io/gh/JohannesFriedrich/senseBox)
[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](http://www.repostatus.org/badges/latest/active.svg)](http://www.repostatus.org/#active)
<!-- badges: end -->

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


### Installation

```{r installation, eval=FALSE}
if(!require("devtools"))
  install.packages("devtools")
devtools::install_github("JohannesFriedrich/senseBox")
```

### Usage

Get some information about the senseBox project and list all senseBoxIds

```{r get_senseBox_stats}
library(senseBox)

stats <- get_senseBox_stats()
```


```{r, echo = FALSE}
knitr::kable(
  stats, format = "html"
)
```

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

```{r}
Id_list <- get_senseBox_Ids()
```

```{r echo = FALSE}
knitr::kable(
  head(Id_list),
  format = "html")
```

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

```{r}
indoor <- search_senseBox(exposure =  "indoor")
```

```{r echo = FALSE}
knitr::kable(
  head(indoor, 3),
  format = "html")

```


We chose one ID for the following examples

```{r set senseBoxId}
senseBoxId <- "592ca4b851d3460011ea2635"
```

#### Show location of senseBox

```{r plot_location}
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

```{r get_senseBox_sensor_info}
sensor_info <- get_senseBox_sensor_info(senseBoxId)
```

```{r print_sensor_info, echo = FALSE}
knitr::kable(
  sensor_info,
  format = "html"
)
```

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

```{r get_senseBox_sensor_info_tidy}
sensor_info <- get_senseBox_sensor_info(senseBoxId, tidy = TRUE)
```

```{r print_sensor_info_tidy, echo = FALSE}
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.

```{r}
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()`.

```{r}
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.

```{r}
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()`.

```{r}
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.

```{r eval=FALSE}
get_senseBox_archive(senseBoxId,
                     date = "2018-07-31")
```

### Some senseBox statistics

```{r}
infos <- get_senseBox_info(Id_list$senseBoxId, parallel = TRUE)
```

```{r, message=FALSE}
library(dplyr)
library(tidyr)
```

```{r}
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))

```

```{r}
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))
```

```{r, message=FALSE}
library(lubridate)
```

```{r}
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")
```


## Available senseBoxes

[This site](http://rpubs.com/Johnsenfr/488288) offers a list of all available senseBoxes (27-01-2020).
You can search for any keyword you are interested in.