Browse Source

clarify README

development
noerw 1 year ago
parent
commit
93b4f6fe52
1 changed files with 37 additions and 32 deletions
  1. 37
    32
      README.md

+ 37
- 32
README.md View File

@@ -2,8 +2,41 @@
2 2
 
3 3
 [![CRAN status](https://www.r-pkg.org/badges/version/opensensmapr)](https://cran.r-project.org/package=opensensmapr) [![Travis build status](https://travis-ci.org/noerw/opensensmapR.svg?branch=master)](https://travis-ci.org/noerw/opensensmapR) [![AppVeyor Build Status](https://ci.appveyor.com/api/projects/status/github/noerw/opensensmapR?branch=master&svg=true)](https://ci.appveyor.com/project/noerw/opensensmapR) [![Coverage status](https://codecov.io/gh/noerw/opensensmapR/branch/master/graph/badge.svg)](https://codecov.io/github/noerw/opensensmapR?branch=master)
4 4
 
5
-This R package ingests data (environmental measurements, sensor stations) from the API of opensensemap.org for analysis in R.
6
-The package aims to be compatible with sf and the tidyverse.
5
+This R package ingests data from the API of [opensensemap.org][osem] for analysis in R.
6
+
7
+Features include:
8
+
9
+- `osem_boxes()`: fetch sensor station ("box") metadata, with various filters
10
+- `osem_measurements()`: fetch measurements by phenomenon, with various filters such as submitting spatial extent, time range, sensor type, box, exposure..
11
+  - no time frame limitation through request paging!
12
+- many helper functions to help understand the queried data
13
+- caching queries for reproducibility
14
+
15
+The package aims to be compatible with the [`tidyverse`][tidy] and [`sf`][sf],
16
+so it is easy to analyze or vizualize the data with state of the art packages.
17
+
18
+[osem]: https://opensensemap.org/
19
+[sf]: https://github.com/r-spatial/sf
20
+[tidy]: https://www.tidyverse.org/
21
+
22
+## Usage
23
+
24
+Complete documentation is provided via the R help system:
25
+Each function's documentation can be viewed with `?<function-name>`.
26
+A comprehensive overview of all functions is given in `?opensensmapr`.
27
+
28
+There are also vignettes showcasing applications of this package:
29
+
30
+- [Visualising the History of openSenseMap.org][osem-history]: Showcase of `opensensmapr` with `dplyr` + `ggplot2`
31
+- [Exploring the openSenseMap dataset][osem-intro]: Showcase of included helper functions
32
+- [Caching openSenseMap Data for reproducibility][osem-serialization]
33
+
34
+[osem-intro]: https://noerw.github.com/opensensmapR/inst/doc/osem-intro.html
35
+[osem-history]: https://noerw.github.com/opensensmapR/inst/doc/osem-history.html
36
+[osem-serialization]: https://noerw.github.com/opensensmapR/inst/doc/osem-serialization.html
37
+
38
+If you used this package for an analysis and think it could serve as a good
39
+example or showcase, feel free to add a vignette to the package via a [PR](#contribute)!
7 40
 
8 41
 ## Installation
9 42
 
@@ -13,7 +46,7 @@ The package is available on CRAN, install it via
13 46
 install.packages('opensensmapr')
14 47
 ```
15 48
 
16
-To install the veryy latest from GitHub, run:
49
+To install the very latest versions from GitHub, run:
17 50
 
18 51
 ```r
19 52
 install.packages('devtools')
@@ -21,35 +54,6 @@ devtools::install_github('noerw/opensensmapr@master')      # latest stable versi
21 54
 devtools::install_github('noerw/opensensmapr@development') # bleeding edge version
22 55
 ```
23 56
 
24
-## Usage
25
-
26
-Each function's documentation can be viewed with `?<function-name>`.
27
-An overview is given in `?opensensmapr`.
28
-A verbose usage example is shown in the vignette [`osem-intro`](https://noerw.github.com/opensensmapR/inst/doc/osem-intro.html).
29
-
30
-In short, the following pseudocode shows the main functions for data retrieval:
31
-
32
-```r
33
-# retrieve a single box by id, or many boxes by some property-filters
34
-b = osem_box('boxId')
35
-b = osem_boxes(filter1, filter2, ...)
36
-
37
-# get the counts of observed phenomena for a list of boxes
38
-p = osem_phenomena(b)
39
-
40
-# get measurements for a phenomenon
41
-m = osem_measurements(phenomenon, filter1, ...)
42
-# get measurements for a phenomenon from selected boxes
43
-m = osem_measurements(b, phenomenon, filter1, ...)
44
-# get measurements for a phenomenon from a geographic bounding box
45
-m = osem_measurements(bbox, phenomenon, filter1, ...)
46
-
47
-# get general count statistics of the openSenseMap database
48
-osem_counts()
49
-```
50
-
51
-Additionally there are some helpers: `summary.sensebox(), plot.sensebox(), st_as_sf.sensebox(), osem_as_sensebox(), [.sensebox(), filter.sensebox(), mutate.sensebox(), ...`.
52
-
53 57
 ## Changelog
54 58
 
55 59
 This project adheres to semantic versioning, for changes in recent versions please consult [CHANGES.md](CHANGES.md).
@@ -59,6 +63,7 @@ This project adheres to semantic versioning, for changes in recent versions plea
59 63
 Contributions are very welcome!
60 64
 When submitting a patch, please follow the existing [code style](.lintr),
61 65
 and run `R CMD check --no-vignettes .` on the package.
66
+Where feasible, also add tests for the added / changed functionality in `tests/testthat`.
62 67
 
63 68
 Please note that this project is released with a [Contributor Code of Conduct](CONDUCT.md).
64 69
 By participating in this project you agree to abide by its terms.

Loading…
Cancel
Save