/
README.Rmd
246 lines (198 loc) · 11.2 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r setup, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/",
out.width = "100%")
```
# `ruODK`: An R Client for the ODK Central API <img src="man/figures/ruODK2.png" align="right" alt="Especially in these trying times, it is important to ask: ruODK?" width="120" />
<!-- badges: start -->
[](https://doi.org/10.5281/zenodo.3953158)
[](https://www.repostatus.org/#active)
[](https://github.com/ropensci/ruODK/commits/main)
[](https://github.com/ropensci/ruODK/issues/)
[](https://github.com/ropensci/ruODK/actions)
[](https://ci.appveyor.com/project/florianm/ruodk/branch/main)
[](https://codecov.io/gh/ropensci/ruODK)
[](https://www.codefactor.io/repository/github/ropensci/ruodk)
[](https://mybinder.org/v2/gh/ropensci/ruODK/main?urlpath=lab)
[](https://mybinder.org/v2/gh/ropensci/ruODK/main?urlpath=rstudio)
<!-- badges: end -->
Especially in these trying times, it is important to ask "r u ODK?".
`ruODK` is an R client to access and parse data from ODK Central.
[OpenDataKit](https://getodk.org/) (ODK) is
[free-and open-source software](https://getodk.org/software/)
that helps millions of people collect data quickly, accurately, offline,
and at scale. The software is in active use in every country in the world and is
supported by a large and helpful community.
`ruODK` is a community contribution to the ODK ecosystem, but not directly
affiliated with ODK.
`ruODK` assumes some familiarity of its users with the ODK ecosystem and workflows.
For a detailed overview, read the extensive [ODK documentation](https://docs.getodk.org/)
and visit the friendly [ODK forum](https://forum.getodk.org/).
[ODK Central](https://docs.getodk.org/central-intro/) is a cloud-based
data clearinghouse for digitally captured data, replacing the older software
[ODK Aggregate](https://docs.getodk.org/aggregate-intro/).
ODK Central manages user accounts and permissions, stores form definitions,
and allows data collection clients like
[ODK Collect](https://docs.getodk.org/collect-intro/) to connect to it for
form download and submission upload.
A typical [ODK workflow](https://docs.getodk.org/#how-is-odk-used):
An XForm is designed e.g. in [ODK Build](https://build.getodk.org/),
[published to ODK Central](https://docs.getodk.org/central-forms/),
and downloaded onto an Android device running ODK Collect.
After data have been captured digitally using
[ODK Collect](https://docs.getodk.org/collect-intro/), the data are uploaded
and stored in ODK Central. The next step from there is to extract the data,
optionally upload it into another data warehouse, and then to analyse and
generate insight from it.
While data can be retrieved in bulk through the GUI, ODK Central's API provides
access to its data and functionality through both an OData and a RESTful API
with a comprehensive and interactive
[documentation](https://odkcentral.docs.apiary.io/#reference/odata-endpoints).
`ruODK` is aimed at the technically minded researcher who wishes to access and
process data from ODK Central using the programming language R.
Benefits of using the R ecosystem in combination with ODK:
* Scalability: Both R and ODK are free and open source software. Scaling to
many users does not incur license fees.
* Ubiquity: R is known to many scientists and is widely taught at universities.
* Automation: The entire data access and analysis workflow can be automated
through R scripts.
* Reproducible reporting (e.g.
[Sweave](https://support.rstudio.com/hc/en-us/articles/200552056-Using-Sweave-and-knitr),
[RMarkdown](https://rmarkdown.rstudio.com/)), interactive web apps
([Shiny](https://shiny.rstudio.com/)),
workflow scaling ([drake](https://docs.ropensci.org/drake/)).
* Rstudio-as-a-Service (RaaS) at
[](https://mybinder.org/v2/gh/ropensci/ruODK/main?urlpath=rstudio)
`ruODK`'s scope:
* To wrap all ODK Central API endpoints with a focus on **data access**.
* To provide working examples of interacting with the ODK Central API.
* To provide convenience helpers for the day to day tasks when working with
ODK Central data in R: **data munging** the ODK Central API output into tidy
R formats.
<!-- TODO: vignette "workflows" -->
`ruODK`'s use cases:
* Smaller projects: Example [rOzCBI](https://dbca-wa.github.io/rOzCBI/)
1. Data collection: ODK Collect
2. Data clearinghouse: ODK Central
3. Data analysis and reporting: `Rmd` (ruODK)
4. Publishing and dissemination: [`ckanr`](https://docs.ropensci.org/ckanr/),
[`CKAN`](https://ckan.org/)
* Larger projects:
1. Data collection: ODK Collect
2. Data clearinghouse: ODK Central
3. ETL pipeline into data warehouses: `Rmd` (ruODK)
4. QA: in data warehouse
5. Reporting: `Rmd`
6. Publishing and dissemination: [`ckanr`](https://docs.ropensci.org/ckanr/),
[`CKAN`](https://ckan.org/)
Out of scope:
* To wrap "management" API endpoints. ODK Central is a
[VueJS/NodeJS application](https://github.com/getodk/central-frontend/)
which provides a comprehensive graphical user interface for the management of
users, roles, permissions, projects, and forms.
* To provide extensive data visualisation. We show only minimal examples of data
visualisation and presentation, mainly to illustrate the example data.
Once the data is in your hands as tidy tibbles... urODK!
## A quick preview
<img src="man/figures/odata.svg" alt="ruODK screencast" width="100%" />
## Install
You can install the latest release of `ruODK` from the
[rOpenSci R-Universe](https://ropensci.r-universe.dev):
```{r r-universe, eval = FALSE}
# Enable the rOpenSci universe
options(repos = c(ropensci = 'https://ropensci.r-universe.dev',
CRAN = 'https://cloud.r-project.org'))
install.packages('ruODK')
```
Alternatively, you can install the development version from the `main` branch.
```{r gh-installation, eval = FALSE}
if (!requireNamespace("remotes")) install.packages("remotes")
# Full install
remotes::install_github(
"ropensci/ruODK@main",
dependencies = TRUE,
upgrade = "always",
build_vignettes = TRUE)
# Minimal install without vignettes
remotes::install_github(
"ropensci/ruODK@main",
dependencies = TRUE,
upgrade = "ask",
build_vignettes = FALSE)
```
If the install fails, read the error messages carefully and install any unmet
dependencies (system libraries or R packages).
If the install fails on building the vignettes, you can set
`build_vignettes=FALSE` and read the vignettes from the online docs instead.
If the installation still fails, or the above does not make any sense,
feel free to submit a [bug report](https://github.com/ropensci/ruODK/issues/new/choose).
## Try `ruODK`
You can also run `ruODK` through hosted or self-built Docker images.
In decreasing order of simplicity:
* Launch a hosted RStudio Server
[](https://mybinder.org/v2/gh/ropensci/ruODK/main?urlpath=rstudio)
* Launch a hosted JupyterLab server (with all kernel options available)
[](https://mybinder.org/v2/gh/ropensci/ruODK/main?urlpath=lab)
* Download the pre-built
[ruODK Docker image](https://github.com/ropensci/ruODK/pkgs/container/ruodk)
based on the last tagged `ruODK` version
```
docker pull ghcr.io/ropensci/ruodk:latest
docker run ghcr.io/ropensci/ruodk:latest
```
* Build the latest `ruODK` version locally with your own GitHub Personal Access Token (PAT)
```
git clone git@github.com:ropensci/ruODK.git
cd ruODK
docker build . -t <myorg>/ruodk:latest --build-arg GITHUB_PAT="..."
docker run -p 8888:8888 <myorg>/ruodk:latest
```
The running Docker image will print a URL you can click on.
The URL will open [JupyterLab](https://jupyter.org/) in your browser.
From there, you can run any available kernel, amongst others are RStudio and a
plain R shell.
## Configure `ruODK`
For all available detailed options to configure authentication for `ruODK`, read
[`vignette("setup", package = "ruODK")`](https://docs.ropensci.org/ruODK/articles/setup.html).
## Use `ruODK`
A detailed walk-through with some data visualisation examples is available in the
[`vignette("odata-api", package="ruODK")`](https://docs.ropensci.org/ruODK/articles/odata-api.html).
See also [`vignette("restful-api", package="ruODK")`](https://docs.ropensci.org/ruODK/articles/restful-api.html)
for examples using the alternative RESTful API.
`urODK`, a sing-along `ruODK` workshop about you, R, and ODK,
is available on
[](https://mybinder.org/v2/gh/ropensci/ruODK/main?urlpath=rstudio).
## Contribute
Contributions through [issues](https://github.com/ropensci/ruODK/issues) and PRs
are welcome!
See the [contributing guide](https://docs.ropensci.org/ruODK/CONTRIBUTING.html)
on best practices and further readings for code contributions.
## Attribution
`ruODK` was developed, and is maintained, by Florian Mayer for the Western Australian
[Department of Biodiversity, Conservation and Attractions (DBCA)](https://www.dbca.wa.gov.au/).
The development was funded both by DBCA core funding and external funds from
the [North West Shelf Flatback Turtle Conservation Program](https://flatbacks.dbca.wa.gov.au/).
To cite package `ruODK` in publications use:
```{r citation}
citation("ruODK")
```
## Acknowledgements
The Department of Biodiversity, Conservation and Attractions (DBCA) acknowledges
the traditional owners of country throughout Western Australia and their continuing
connection to the land, waters and community. We pay our respects to them, their
culture and to their Elders past and present.
This software was created on Whadjuk boodja (ground) both as a contribution to
the ODK ecosystem and for the conservation of the biodiversity of
Western Australia, and in doing so, caring for country.
## Package functionality
See [`vignette("comparison", package="ruODK")`](https://docs.ropensci.org/ruODK/articles/comparison.html)
for a comprehensive comparison of ruODK to other software packages from
both an ODK and an OData angle.