diff --git a/README.md b/README.md index 7d18958..ef3ea7b 100644 --- a/README.md +++ b/README.md @@ -31,9 +31,11 @@ There are also vignettes showcasing applications of this package: - [Visualising the History of openSenseMap.org][osem-history]: Showcase of `opensensmapr` with `dplyr` + `ggplot2` - [Exploring the openSenseMap dataset][osem-intro]: Showcase of included helper functions +- [Einführung in opensensmapR][intro-deutsch]: Short introduction to the package in German - [Caching openSenseMap Data for reproducibility][osem-serialization] -[osem-intro]: https://sensebox.github.io/opensensmapR/inst/doc/osem-intro.html +[osem-intro]: https://sensebox.github.io/opensensmapR/inst/doc/intro-deutsch.html +[intro-deutsch]: https://sensebox.github.io/opensensmapR/inst/doc/osem-intro.html [osem-history]: https://sensebox.github.io/opensensmapR/inst/doc/osem-history.html [osem-serialization]: https://sensebox.github.io/opensensmapR/inst/doc/osem-serialization.html diff --git a/inst/doc/intro-deutsch.R b/inst/doc/intro-deutsch.R new file mode 100644 index 0000000..357ef50 --- /dev/null +++ b/inst/doc/intro-deutsch.R @@ -0,0 +1,53 @@ +## ----setup, include=FALSE----------------------------------------------------- +knitr::opts_chunk$set(echo = TRUE) + +## ----results = FALSE---------------------------------------------------------- +library(opensensmapr) +all_sensors = osem_boxes() + +## ----------------------------------------------------------------------------- +summary(all_sensors) + +## ---- message=FALSE, warning=FALSE-------------------------------------------- +plot(all_sensors) + +## ----------------------------------------------------------------------------- +phenoms = osem_phenomena(all_sensors) +str(phenoms) + +## ----results = FALSE---------------------------------------------------------- +pm10_sensors = osem_boxes( + exposure = 'outdoor', + date = Sys.time(), # ±4 hours + phenomenon = 'PM10' +) + +## ----------------------------------------------------------------------------- +summary(pm10_sensors) +plot(pm10_sensors) + +## ---- results=FALSE, message=FALSE-------------------------------------------- +# Zunächst werden ein paar Pakete geladen, die es uns ermöglichen mit den räumlichen Daten zu arbeiten +library(sf) +library(units) +library(lubridate) +library(dplyr) +# Dann erstellen wir eine sogenannte Boundingbox, in unserem Fall ein 20 km x 20 km Quadrat um das Zentrum von Münster. +muenster = st_point(c(7.63, 51.95)) %>% # Koordinate Münster Zentrum + st_sfc(crs = 4326) %>% # Koordinatensystem für geographische Koordinaten + st_transform(3857) %>% # Koordinatensystem das Meter versteht + st_buffer(set_units(10, km)) %>% # 10 km Radius um Münster + st_transform(4326) %>% # Wieder Umwandlung in geographische Koordinaten, welche die openSenseMap API erwartet + st_bbox() # erstellen eines boundingbox objektes + +## ----bbox, results = FALSE---------------------------------------------------- +pm10_muenster = osem_measurements( + muenster, + phenomenon = 'PM10', + from = now() - days(3), # defaults to 2 days + to = now() +) + +## ----------------------------------------------------------------------------- +plot(pm10_muenster) + diff --git a/inst/doc/intro-deutsch.Rmd b/inst/doc/intro-deutsch.Rmd new file mode 100644 index 0000000..bbd2179 --- /dev/null +++ b/inst/doc/intro-deutsch.Rmd @@ -0,0 +1,138 @@ +--- +title: "Einführung in opensensmapR" +author: "Jan Stenkamp" +date: "`r Sys.Date()`" +output: + rmarkdown::html_vignette: + fig_margin: 0 + fig_width: 6 + fig_height: 4 +vignette: > + %\VignetteIndexEntry{Einfuehrung in opensensmapR"} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +--- + +[This Rmd file was included after the package was released]: # +[TODO: if this should be inlcuded in the actual vignettes, improve runtime by using precomputed data!]: # + +```{r setup, include=FALSE} +knitr::opts_chunk$set(echo = TRUE) +``` + +Das package opensensmapR kann dazu genutzt werden Daten von der [openSenseMap](https://opensensemap.org) +in R abzufragen und zu analysieren. Damit lassen sich sowohl die Daten einzelner senseBoxen, aber vor allem +auch mehrere senseBoxen gleichzeitig analysieren. + +### Installation + +Um das package in R zu nutzen, muss dieses zuerst installiert werden. Das ist möglich mit dem Befehl `install.packages('opensensmapr')`. +Danach kann das package geladen werden durch den Befehl `library(opensensmapr)`. + + +### Alle Boxen abfragen +Um einen Überblick über alle auf der openSenseMap registrierten Boxen zu bekommen, kann man diese mit dem Befehl `osem_boxes()` über die API beziehen. +Außerdem werden die Boxen dabei automatisch vorbereitet, um sie für weitere Analysen zu nutzen. Die Daten werden dann in der Variablen `all_sensors` gespeichert, um diese weiter zu verwenden. + + +```{r results = FALSE} +library(opensensmapr) +all_sensors = osem_boxes() +``` +Daraufhin ermöglicht die Funktion `summary(boxes)`, eine Zusammenfassung der Metadaten aller Boxen anzuzeigen: +```{r} +summary(all_sensors) +``` +So werden hier unter anderem die Anzahl aller Boxen in dem Datensatz (`boxes total`), die Anzahl der Boxen die Messungen in verschiedenen Zeitintervallen durchgeführt haben (`$last_measurement_within`) und die zuletzt erstellte Box dargestellt (`newest_box`). + +Mit der Funktion `plot(boxes)` können wir dann auch noch alle Stationen auf einer Karte anzeigen. + +```{r, message=FALSE, warning=FALSE} +plot(all_sensors) +``` + +Die Funktion `osem_phenomena(boxes)` gibt uns außerdem Informationen darüber, welche Phänomene von den Stationen gemessen werden. + +```{r} +phenoms = osem_phenomena(all_sensors) +str(phenoms) +``` + + +### Daten filtern + +Mit PM10 als einem der am häufigsten gemessenen Phänomene, wollen wir nun weiterarbeiten. Dazu können wir zum Beispiel mit den folgenden Parametern, nur die Boxen abfragen, die PM10 gemessen haben. Dabei wird die Abfrage durch das setzen der Parameter in der Klammer wie folgt gefiltert: + +- `exposure = 'outdoor'` : gib nur Boxen zurück die draußen stehen. +- `date = Sys.time()` : gib nur Boxen zurück, die zum Datum Sys.time() (+-4 Stunden) eine Messung geschickt haben. Sys.time() steht dabei für die aktuelle Zeit. +- `phenomenon = 'PM10'` : gib nur Boxen zurück, die einen PM10 Sensor haben. + +Die Abfrage der gefilterten Boxen kann ggfs. ein paar Minuten dauern, da die openSenseMap API zuerst die prall gefüllte Datenbank entsprechend filtern muss. + +```{r results = FALSE} +pm10_sensors = osem_boxes( + exposure = 'outdoor', + date = Sys.time(), # ±4 hours + phenomenon = 'PM10' +) +``` +Auch von den gefilterten Daten können wir uns wieder die Zusammenfassung und eine Karte anschauen: + +```{r} +summary(pm10_sensors) +plot(pm10_sensors) +``` + +Wie man sieht, sind jetzt alle Stationen outdoor und es gibt keine Station mehr, die noch nie eine Messung durchgeführt hat. Das liegt an den Parametern, die wir bei der Abfrage der Daten in der Funktion gesetzt haben; alle Stationen sollten draußen sein und vor kurzem eine Messung geschickt haben. + + + +### Daten analysieren + +Bis jetzt haben wir uns ja nur die Stationen angeschaut. Nun wollen wir auch einen genaueren Blick auf die eigentlichen Messungen werfen. Die Messungen die an die openSenseMap geschickt werden, können wir mit der Funktion `osem_measurements()` abfragen. + +Auch dabei können wir verschiedene Filter setzen. Unter anderem wollen wir nur Messungen von Stationen in der Nähe von Münster erhalten. Dazu erstellen wir zunächst ein Objekt, dass die Koordinaten von Münster enthält: + +```{r, results=FALSE, message=FALSE} +# Zunächst werden ein paar Pakete geladen, die es uns ermöglichen mit den räumlichen Daten zu arbeiten +library(sf) +library(units) +library(lubridate) +library(dplyr) +# Dann erstellen wir eine sogenannte Boundingbox, in unserem Fall ein 20 km x 20 km Quadrat um das Zentrum von Münster. +muenster = st_point(c(7.63, 51.95)) %>% # Koordinate Münster Zentrum + st_sfc(crs = 4326) %>% # Koordinatensystem für geographische Koordinaten + st_transform(3857) %>% # Koordinatensystem das Meter versteht + st_buffer(set_units(10, km)) %>% # 10 km Radius um Münster + st_transform(4326) %>% # Wieder Umwandlung in geographische Koordinaten, welche die openSenseMap API erwartet + st_bbox() # erstellen eines boundingbox objektes +``` + +`osem_measurements()` nimmt ähnliche Parameter wie `osem_boxes()` entgegen. + +- `bbox = muenster` : Gib nur Messungen von Boxen zurück, die innerhalb unserer boundingbox liegen. +- `phenomenon = 'PM10'` : Gib nur PM10 Messungen zurück. +- `from = now() - days(3)`: Gib Messungen zurück, die nicht älter als drei Tage sind. +- `to = now()` : Gib nur Messungen zurück, die bis jetzt gemessen wurden. + +Hierbei ersetzen die Parameter `from` und `to`, den Parameter `date`, den wir zuvor in der Funktion `osem_boxes()` benutzt haben. Beide Arten von Datumsfilter, können in beiden Funktionen genutzt werden. + +```{r bbox, results = FALSE} +pm10_muenster = osem_measurements( + muenster, + phenomenon = 'PM10', + from = now() - days(3), # defaults to 2 days + to = now() +) +``` +Die PM10-Messungen können wir nun einfach als Zeitreihe darstellen: + +```{r} +plot(pm10_muenster) +``` + +Jeder Punkt stellt hier eine Messung dar und jede Box hat eine andere Farbe. Wie man sieht sind die meisten Messungen unter einem Wert von 50, jedoch gibt es auch ein paar Ausreißer und eine Station die dauerhaft Werte um 150 misst. + +Für weitere Beispiele lohnt sich ein Blick in die folgenden Dokumente: +- https://github.com/sensebox/opensensmapR/blob/master/inst/doc/osem-history_revised.html +- https://sensebox.github.io/opensensmapR/inst/doc/osem-intro.html \ No newline at end of file diff --git a/inst/doc/intro-deutsch.html b/inst/doc/intro-deutsch.html new file mode 100644 index 0000000..4a84120 --- /dev/null +++ b/inst/doc/intro-deutsch.html @@ -0,0 +1,660 @@ + + + + + + + + + + + + + + + + +Einführung in opensensmapR + + + + + + + + + + + + + + + + + + + + + + + + + + +

Einführung in opensensmapR

+

Jan Stenkamp

+

2023-03-30

+ + + +

Das package opensensmapR kann dazu genutzt werden Daten von der openSenseMap in R abzufragen und zu +analysieren. Damit lassen sich sowohl die Daten einzelner senseBoxen, +aber vor allem auch mehrere senseBoxen gleichzeitig analysieren.

+
+

Installation

+

Um das package in R zu nutzen, muss dieses zuerst installiert werden. +Das ist möglich mit dem Befehl +install.packages('opensensmapr'). Danach kann das package +geladen werden durch den Befehl library(opensensmapr).

+
+
+

Alle Boxen abfragen

+

Um einen Überblick über alle auf der openSenseMap registrierten Boxen +zu bekommen, kann man diese mit dem Befehl osem_boxes() +über die API beziehen. Außerdem werden die Boxen dabei automatisch +vorbereitet, um sie für weitere Analysen zu nutzen. Die Daten werden +dann in der Variablen all_sensors gespeichert, um diese +weiter zu verwenden.

+
library(opensensmapr)
+all_sensors = osem_boxes()
+

Daraufhin ermöglicht die Funktion summary(boxes), eine +Zusammenfassung der Metadaten aller Boxen anzuzeigen:

+
summary(all_sensors)
+
## boxes total: 11589
+## 
+## boxes by exposure:
+##  indoor  mobile outdoor unknown 
+##    2435     598    8537      19 
+## 
+## boxes by model:
+##                   custom          hackair_home_v2             homeEthernet 
+##                     2917                       75                       73 
+##    homeEthernetFeinstaub           homeV2Ethernet  homeV2EthernetFeinstaub 
+##                       55                       20                       40 
+##               homeV2Lora               homeV2Wifi      homeV2WifiFeinstaub 
+##                      248                      595                      751 
+##                 homeWifi        homeWifiFeinstaub        luftdaten_pms1003 
+##                      214                      223                        9 
+## luftdaten_pms1003_bme280        luftdaten_pms3003 luftdaten_pms3003_bme280 
+##                       10                        1                        7 
+##        luftdaten_pms5003 luftdaten_pms5003_bme280        luftdaten_pms7003 
+##                        7                       61                        6 
+## luftdaten_pms7003_bme280         luftdaten_sds011  luftdaten_sds011_bme280 
+##                       81                      287                     3103 
+##  luftdaten_sds011_bmp180   luftdaten_sds011_dht11   luftdaten_sds011_dht22 
+##                      116                      135                     2555 
+## 
+## $last_measurement_within
+##    1h    1d   30d  365d never 
+##  3659  3778  4319  6029  2094 
+## 
+## oldest box: 2016-08-09 19:34:42 (OBS Bohmte UK_02)
+## newest box: 2023-03-29 17:40:59 (Test Nr.1)
+## 
+## sensors per box:
+##    Min. 1st Qu.  Median    Mean 3rd Qu.    Max. 
+##    1.00    4.00    5.00    5.02    5.00   76.00
+

So werden hier unter anderem die Anzahl aller Boxen in dem Datensatz +(boxes total), die Anzahl der Boxen die Messungen in +verschiedenen Zeitintervallen durchgeführt haben +($last_measurement_within) und die zuletzt erstellte Box +dargestellt (newest_box).

+

Mit der Funktion plot(boxes) können wir dann auch noch +alle Stationen auf einer Karte anzeigen.

+
plot(all_sensors)
+

+

Die Funktion osem_phenomena(boxes) gibt uns außerdem +Informationen darüber, welche Phänomene von den Stationen gemessen +werden.

+
phenoms = osem_phenomena(all_sensors)
+str(phenoms)
+
## List of 3640
+##  $ Temperatur                                                   : int 9560
+##  $ rel. Luftfeuchte                                             : int 8436
+##  $ PM10                                                         : int 8239
+##  $ PM2.5                                                        : int 8224
+##  $ Luftdruck                                                    : int 5776
+##  $ Beleuchtungsstärke                                           : int 1712
+##  $ UV-Intensität                                                : int 1700
+##  $ Temperature                                                  : int 663
+##  $ Humidity                                                     : int 489
+##  $ VOC                                                          : int 432
+##  $ Lufttemperatur                                               : int 373
+##  $ Luftfeuchte                                                  : int 371
+##  $ CO₂                                                          : int 325
+##  $ Pressure                                                     : int 308
+##  $ Bodenfeuchte                                                 : int 302
+##  $ Luftfeuchtigkeit                                             : int 275
+##  $ Lautstärke                                                   : int 255
+##  $ atm. Luftdruck                                               : int 251
+##  $ PM01                                                         : int 213
+##  $ Bodentemperatur                                              : int 163
+##  $ IAQ                                                          : int 162
+##  $ Kalibrierungswert                                            : int 156
+##  $ rel. Luftfeuchte SCD30                                       : int 156
+##  $ Temperatur SCD30                                             : int 154
+##  $ CO2eq                                                        : int 153
+##  $ Windgeschwindigkeit                                          : int 153
+##  $ pH-Wert                                                      : int 143
+##  $ Gesamthärte                                                  : int 142
+##  $ Blei                                                         : int 140
+##  $ Eisen                                                        : int 140
+##  $ Gesamthärte 2                                                : int 140
+##  $ Kupfer C                                                     : int 140
+##  $ Kupfer D                                                     : int 140
+##  $ Kupfer1                                                      : int 140
+##  $ Kupfer2                                                      : int 140
+##  $ Nitrat                                                       : int 140
+##  $ Nitrit                                                       : int 140
+##  $ GesamthaerteLabor                                            : int 120
+##  $ CO2                                                          : int 118
+##  $ Feinstaub PM10                                               : int 101
+##  $ Windrichtung                                                 : int 82
+##  $ rel. Luftfeuchte (HECA)                                      : int 78
+##  $ Temperatur (HECA)                                            : int 76
+##  $ Helligkeit                                                   : int 70
+##  $ Temperatura                                                  : int 69
+##  $ Feinstaub PM2.5                                              : int 68
+##  $ Taupunkt                                                     : int 62
+##  $ Latitude                                                     : int 61
+##  $ Longtitude                                                   : int 58
+##  $ Durchschnitt Umgebungslautstärke                             : int 51
+##  $ Minimum Umgebungslautstärke                                  : int 51
+##  $ UV-Index                                                     : int 49
+##  $ temperature                                                  : int 49
+##  $ Batterie                                                     : int 46
+##  $ Feinstaub PM1.0                                              : int 44
+##  $ Umgebungslautstärke                                          : int 41
+##  $ humidity                                                     : int 41
+##  $ UV                                                           : int 40
+##  $ Abstand nach links                                           : int 34
+##  $ Beschleunigung Z-Achse                                       : int 34
+##  $ Beschleunigung X-Achse                                       : int 33
+##  $ Beschleunigung Y-Achse                                       : int 33
+##  $ Geschwindigkeit                                              : int 33
+##  $ Niederschlag                                                 : int 33
+##  $ PM1                                                          : int 33
+##  $ Feinstaub PM25                                               : int 32
+##  $ PM1.0                                                        : int 32
+##  $ Relative Humidity                                            : int 32
+##  $ Abstand nach rechts                                          : int 31
+##  $ rel. Luftfeuchtigkeit                                        : int 30
+##  $ Sonnenstrahlung                                              : int 29
+##  $ Luftdruck relativ                                            : int 28
+##  $ Luftdruck absolut                                            : int 26
+##  $ Rain                                                         : int 26
+##  $ Regenrate                                                    : int 26
+##  $ CO2 Konzentration                                            : int 25
+##  $ RSSI                                                         : int 22
+##  $ gefühlte Temperatur                                          : int 22
+##  $ Battery                                                      : int 21
+##  $ PM 2.5                                                       : int 21
+##  $ Ciśnienie                                                    : int 20
+##  $ EisenLabor                                                   : int 20
+##  $ Air Pressure                                                 : int 19
+##  $ PM4                                                          : int 19
+##  $ Regen                                                        : int 19
+##  $ Schall                                                       : int 19
+##  $ Signal                                                       : int 19
+##  $ UV Index                                                     : int 19
+##  $ Ilmanpaine                                                   : int 18
+##  $ Lämpötila                                                    : int 18
+##  $ Wind Direction                                               : int 18
+##  $ Wind speed                                                   : int 18
+##  $ PM 10                                                        : int 17
+##  $ Air pressure                                                 : int 16
+##  $ Altitude                                                     : int 16
+##  $ Illuminance                                                  : int 16
+##  $ Power Supply                                                 : int 16
+##  $ Temperatur DHT22                                             : int 16
+##  $ Wind Speed                                                   : int 16
+##   [list output truncated]
+
+
+

Daten filtern

+

Mit PM10 als einem der am häufigsten gemessenen Phänomene, wollen wir +nun weiterarbeiten. Dazu können wir zum Beispiel mit den folgenden +Parametern, nur die Boxen abfragen, die PM10 gemessen haben. Dabei wird +die Abfrage durch das setzen der Parameter in der Klammer wie folgt +gefiltert:

+ +

Die Abfrage der gefilterten Boxen kann ggfs. ein paar Minuten dauern, +da die openSenseMap API zuerst die prall gefüllte Datenbank entsprechend +filtern muss.

+
pm10_sensors = osem_boxes(
+  exposure = 'outdoor',
+  date = Sys.time(), # ±4 hours
+  phenomenon = 'PM10'
+)
+

Auch von den gefilterten Daten können wir uns wieder die +Zusammenfassung und eine Karte anschauen:

+
summary(pm10_sensors)
+
## boxes total: 3009
+## 
+## boxes by exposure:
+## outdoor 
+##    3009 
+## 
+## boxes by model:
+##                   custom          hackair_home_v2    homeEthernetFeinstaub 
+##                      172                        7                       13 
+##  homeV2EthernetFeinstaub               homeV2Lora               homeV2Wifi 
+##                        7                       23                        2 
+##      homeV2WifiFeinstaub                 homeWifi        homeWifiFeinstaub 
+##                      125                        2                       30 
+##        luftdaten_pms1003 luftdaten_pms1003_bme280        luftdaten_pms5003 
+##                        1                        4                        3 
+## luftdaten_pms5003_bme280        luftdaten_pms7003 luftdaten_pms7003_bme280 
+##                       11                        2                       30 
+##         luftdaten_sds011  luftdaten_sds011_bme280  luftdaten_sds011_bmp180 
+##                      110                     1382                       60 
+##   luftdaten_sds011_dht11   luftdaten_sds011_dht22 
+##                       40                      985 
+## 
+## $last_measurement_within
+##    1h    1d   30d  365d never 
+##  2985  3009  3009  3009     0 
+## 
+## oldest box: 2017-03-03 18:20:43 (Witten Heven Dorf)
+## newest box: 2023-03-26 17:59:20 (airRohr)
+## 
+## sensors per box:
+##    Min. 1st Qu.  Median    Mean 3rd Qu.    Max. 
+##   2.000   4.000   5.000   4.849   5.000  29.000
+
plot(pm10_sensors)
+

+

Wie man sieht, sind jetzt alle Stationen outdoor und es gibt keine +Station mehr, die noch nie eine Messung durchgeführt hat. Das liegt an +den Parametern, die wir bei der Abfrage der Daten in der Funktion +gesetzt haben; alle Stationen sollten draußen sein und vor kurzem eine +Messung geschickt haben.

+
+
+

Daten analysieren

+

Bis jetzt haben wir uns ja nur die Stationen angeschaut. Nun wollen +wir auch einen genaueren Blick auf die eigentlichen Messungen werfen. +Die Messungen die an die openSenseMap geschickt werden, können wir mit +der Funktion osem_measurements() abfragen.

+

Auch dabei können wir verschiedene Filter setzen. Unter anderem +wollen wir nur Messungen von Stationen in der Nähe von Münster erhalten. +Dazu erstellen wir zunächst ein Objekt, dass die Koordinaten von Münster +enthält:

+
# Zunächst werden ein paar Pakete geladen, die es uns ermöglichen mit den räumlichen Daten zu arbeiten
+library(sf)
+library(units)
+library(lubridate)
+library(dplyr)
+# Dann erstellen wir eine sogenannte Boundingbox, in unserem Fall ein 20 km x 20 km Quadrat um das Zentrum von Münster.
+muenster = st_point(c(7.63, 51.95)) %>% # Koordinate Münster Zentrum
+  st_sfc(crs = 4326) %>% # Koordinatensystem für geographische Koordinaten
+  st_transform(3857) %>% # Koordinatensystem das Meter versteht
+  st_buffer(set_units(10, km)) %>% # 10 km Radius um Münster
+  st_transform(4326) %>% # Wieder Umwandlung in geographische Koordinaten, welche die openSenseMap API erwartet
+  st_bbox() # erstellen eines boundingbox objektes
+

osem_measurements() nimmt ähnliche Parameter wie +osem_boxes() entgegen.

+ +

Hierbei ersetzen die Parameter from und to, +den Parameter date, den wir zuvor in der Funktion +osem_boxes() benutzt haben. Beide Arten von Datumsfilter, +können in beiden Funktionen genutzt werden.

+
pm10_muenster = osem_measurements(
+  muenster, 
+  phenomenon = 'PM10',
+  from = now() - days(3), # defaults to 2 days
+  to = now()
+)
+

Die PM10-Messungen können wir nun einfach als Zeitreihe +darstellen:

+
plot(pm10_muenster)
+

+

Jeder Punkt stellt hier eine Messung dar und jede Box hat eine andere +Farbe. Wie man sieht sind die meisten Messungen unter einem Wert von 50, +jedoch gibt es auch ein paar Ausreißer und eine Station die dauerhaft +Werte um 150 misst.

+

Für weitere Beispiele lohnt sich ein Blick in die folgenden +Dokumente: - https://github.com/sensebox/opensensmapR/blob/master/inst/doc/osem-history_revised.html +- https://sensebox.github.io/opensensmapR/inst/doc/osem-intro.html

+
+ + + + + + + + + + + diff --git a/vignettes/intro-deutsch.Rmd b/vignettes/intro-deutsch.Rmd new file mode 100644 index 0000000..bbd2179 --- /dev/null +++ b/vignettes/intro-deutsch.Rmd @@ -0,0 +1,138 @@ +--- +title: "Einführung in opensensmapR" +author: "Jan Stenkamp" +date: "`r Sys.Date()`" +output: + rmarkdown::html_vignette: + fig_margin: 0 + fig_width: 6 + fig_height: 4 +vignette: > + %\VignetteIndexEntry{Einfuehrung in opensensmapR"} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +--- + +[This Rmd file was included after the package was released]: # +[TODO: if this should be inlcuded in the actual vignettes, improve runtime by using precomputed data!]: # + +```{r setup, include=FALSE} +knitr::opts_chunk$set(echo = TRUE) +``` + +Das package opensensmapR kann dazu genutzt werden Daten von der [openSenseMap](https://opensensemap.org) +in R abzufragen und zu analysieren. Damit lassen sich sowohl die Daten einzelner senseBoxen, aber vor allem +auch mehrere senseBoxen gleichzeitig analysieren. + +### Installation + +Um das package in R zu nutzen, muss dieses zuerst installiert werden. Das ist möglich mit dem Befehl `install.packages('opensensmapr')`. +Danach kann das package geladen werden durch den Befehl `library(opensensmapr)`. + + +### Alle Boxen abfragen +Um einen Überblick über alle auf der openSenseMap registrierten Boxen zu bekommen, kann man diese mit dem Befehl `osem_boxes()` über die API beziehen. +Außerdem werden die Boxen dabei automatisch vorbereitet, um sie für weitere Analysen zu nutzen. Die Daten werden dann in der Variablen `all_sensors` gespeichert, um diese weiter zu verwenden. + + +```{r results = FALSE} +library(opensensmapr) +all_sensors = osem_boxes() +``` +Daraufhin ermöglicht die Funktion `summary(boxes)`, eine Zusammenfassung der Metadaten aller Boxen anzuzeigen: +```{r} +summary(all_sensors) +``` +So werden hier unter anderem die Anzahl aller Boxen in dem Datensatz (`boxes total`), die Anzahl der Boxen die Messungen in verschiedenen Zeitintervallen durchgeführt haben (`$last_measurement_within`) und die zuletzt erstellte Box dargestellt (`newest_box`). + +Mit der Funktion `plot(boxes)` können wir dann auch noch alle Stationen auf einer Karte anzeigen. + +```{r, message=FALSE, warning=FALSE} +plot(all_sensors) +``` + +Die Funktion `osem_phenomena(boxes)` gibt uns außerdem Informationen darüber, welche Phänomene von den Stationen gemessen werden. + +```{r} +phenoms = osem_phenomena(all_sensors) +str(phenoms) +``` + + +### Daten filtern + +Mit PM10 als einem der am häufigsten gemessenen Phänomene, wollen wir nun weiterarbeiten. Dazu können wir zum Beispiel mit den folgenden Parametern, nur die Boxen abfragen, die PM10 gemessen haben. Dabei wird die Abfrage durch das setzen der Parameter in der Klammer wie folgt gefiltert: + +- `exposure = 'outdoor'` : gib nur Boxen zurück die draußen stehen. +- `date = Sys.time()` : gib nur Boxen zurück, die zum Datum Sys.time() (+-4 Stunden) eine Messung geschickt haben. Sys.time() steht dabei für die aktuelle Zeit. +- `phenomenon = 'PM10'` : gib nur Boxen zurück, die einen PM10 Sensor haben. + +Die Abfrage der gefilterten Boxen kann ggfs. ein paar Minuten dauern, da die openSenseMap API zuerst die prall gefüllte Datenbank entsprechend filtern muss. + +```{r results = FALSE} +pm10_sensors = osem_boxes( + exposure = 'outdoor', + date = Sys.time(), # ±4 hours + phenomenon = 'PM10' +) +``` +Auch von den gefilterten Daten können wir uns wieder die Zusammenfassung und eine Karte anschauen: + +```{r} +summary(pm10_sensors) +plot(pm10_sensors) +``` + +Wie man sieht, sind jetzt alle Stationen outdoor und es gibt keine Station mehr, die noch nie eine Messung durchgeführt hat. Das liegt an den Parametern, die wir bei der Abfrage der Daten in der Funktion gesetzt haben; alle Stationen sollten draußen sein und vor kurzem eine Messung geschickt haben. + + + +### Daten analysieren + +Bis jetzt haben wir uns ja nur die Stationen angeschaut. Nun wollen wir auch einen genaueren Blick auf die eigentlichen Messungen werfen. Die Messungen die an die openSenseMap geschickt werden, können wir mit der Funktion `osem_measurements()` abfragen. + +Auch dabei können wir verschiedene Filter setzen. Unter anderem wollen wir nur Messungen von Stationen in der Nähe von Münster erhalten. Dazu erstellen wir zunächst ein Objekt, dass die Koordinaten von Münster enthält: + +```{r, results=FALSE, message=FALSE} +# Zunächst werden ein paar Pakete geladen, die es uns ermöglichen mit den räumlichen Daten zu arbeiten +library(sf) +library(units) +library(lubridate) +library(dplyr) +# Dann erstellen wir eine sogenannte Boundingbox, in unserem Fall ein 20 km x 20 km Quadrat um das Zentrum von Münster. +muenster = st_point(c(7.63, 51.95)) %>% # Koordinate Münster Zentrum + st_sfc(crs = 4326) %>% # Koordinatensystem für geographische Koordinaten + st_transform(3857) %>% # Koordinatensystem das Meter versteht + st_buffer(set_units(10, km)) %>% # 10 km Radius um Münster + st_transform(4326) %>% # Wieder Umwandlung in geographische Koordinaten, welche die openSenseMap API erwartet + st_bbox() # erstellen eines boundingbox objektes +``` + +`osem_measurements()` nimmt ähnliche Parameter wie `osem_boxes()` entgegen. + +- `bbox = muenster` : Gib nur Messungen von Boxen zurück, die innerhalb unserer boundingbox liegen. +- `phenomenon = 'PM10'` : Gib nur PM10 Messungen zurück. +- `from = now() - days(3)`: Gib Messungen zurück, die nicht älter als drei Tage sind. +- `to = now()` : Gib nur Messungen zurück, die bis jetzt gemessen wurden. + +Hierbei ersetzen die Parameter `from` und `to`, den Parameter `date`, den wir zuvor in der Funktion `osem_boxes()` benutzt haben. Beide Arten von Datumsfilter, können in beiden Funktionen genutzt werden. + +```{r bbox, results = FALSE} +pm10_muenster = osem_measurements( + muenster, + phenomenon = 'PM10', + from = now() - days(3), # defaults to 2 days + to = now() +) +``` +Die PM10-Messungen können wir nun einfach als Zeitreihe darstellen: + +```{r} +plot(pm10_muenster) +``` + +Jeder Punkt stellt hier eine Messung dar und jede Box hat eine andere Farbe. Wie man sieht sind die meisten Messungen unter einem Wert von 50, jedoch gibt es auch ein paar Ausreißer und eine Station die dauerhaft Werte um 150 misst. + +Für weitere Beispiele lohnt sich ein Blick in die folgenden Dokumente: +- https://github.com/sensebox/opensensmapR/blob/master/inst/doc/osem-history_revised.html +- https://sensebox.github.io/opensensmapR/inst/doc/osem-intro.html \ No newline at end of file