-
Notifications
You must be signed in to change notification settings - Fork 4
/
Copy pathREADME.Rmd
193 lines (128 loc) · 11.3 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
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# odkr: Open Data Kit (ODK) R API
<!-- badges: start -->
[](http://www.repostatus.org/#active)
[](https://lifecycle.r-lib.org/articles/stages.html#stable)
[](https://github.com/rapidsurveys/odkr/actions/workflows/R-CMD-check.yaml)
[](https://app.codecov.io/gh/rapidsurveys/odkr?branch=main)
[](https://www.codefactor.io/repository/github/rapidsurveys/odkr)
[](https://doi.org/10.5281/zenodo.1170514)
<!-- badges: end -->
**Open Data Kit (ODK)** is a free and open-source set of tools which help organizations author, field, and manage mobile data collection solutions. ODK provides an out-of-the-box solution for users to:
* Build a data collection form or survey;
* Collect the data on a mobile device and send it to a server; and
* Aggregate the collected data on a server and extract it in useful formats.
`odkr` is a set of interface and utility tools for a **useR** working with ODK. The package currently has two classes of functions: 1) *data processing* tools; and, 2) *ODK-R interface* functions.
For *data processing*, there are currently three functions included which can be used to perform typical data processing tasks associated with working with ODK-collected datasets such as renaming variables in a dataset, expansion of responses to questions that allow more than one answer and merging of nested datasets.
For *ODK-R interface*, included are a set of functions that work via a command line interface with the Java application **ODK Briefcase** for fetching and pushing Open Data Kit (ODK) forms and their contents. It can be used to gather and aggregate data from the mobile client **ODK Collect** when there is no internet connectivity, when there is no **ODK Aggregate Server** set-up or when an **ODK Aggregate Server** is not preferred. Current production version of **ODK Briefcase** is v1.8.0 and an executable `.jar` file can be downloaded from the Open Data Kit [website](https://opendatakit.org/use/briefcase/).
As of **ODK Briefcase** version 1.4.4, a scriptable command line interface (CLI) to the Java application has been available. This package provides an R interface to **ODK Briefcase** via the available CLI to pull forms from a remote **ODK Aggregate Server** or from a local ODK folder `/odk` collected from mobile clients. This package has a function that downloads the latest version of **ODK Briefcase** (currently v1.8.0) and additional functions that use the CLI of **ODK Briefcase** to perform data extraction and data export. This package requires Java 8 installed. Java 8 can be downloaded from [here](https://java.com/en/download/).
## Requirements
The ODK-R interface component of this package requires **Java 8** to be installed in your computer. There are known [issues](https://forum.opendatakit.org/t/odk-briefcase-not-running-with-jdk-9/10201) when using ODK Briefcase with **Java 9**. If you have **Java 9** installed, uninstall (on [Windows](https://www.java.com/en/download/help/uninstall_java.xml); on [macOS](https://www.java.com/en/download/help/mac_uninstall_java.xml)) and then [install](https://java.com/en/download/) **Java 8**. If issues persist even with **Java 8**, you may need to reconfigure **Java**. On the terminal, execute the
following command:
```shell
R CMD javareconf
```
If reconfiguring **Java** still doesn't solve the issue, you may need to specify `JAVA_HOME` by executing the following command in terminal:
```shell
sudo R CMD javareconf JAVA_HOME=/usr/java/default
```
## Installation
Install `odkr` from CRAN:
```R
install.packages("odkr")
library(odkr)
```
Install development version of `odkr` by installing devtools and then installing `odkr` package via git
```R
# install.packages("devtools")
devtools::install_github("validmeasures/odkr")
library(odkr)
```
## Usage
### Data processing functions
**1. Rename variables of an ODK-collected dataset**
Depending on how you have designed and structured your ODK form, the standard naming of variables of the output dataset isn't always desirable for eventual data processing and analysis. For example, for ODK forms that groups questions into modules or sets, ODK would append the grouping name as a prefix to the actual name assigned to a variable usually separated by a `/` or a `.`.
The `renameODK()` function extracts the actual variable name assigned when designing the form by removing the prefix grouping labels. This can be done by simply applying the `renameODK()` to the data.frame as follows:
```R
renameODK(sampleData1)
```
**2. Expand multiple answer responses**
For survey questions that allow for multiple answers to be provided, the `expandMultChoice()` function recodes this into multiple columns with `0/1` coding the number of which is equivalent to the number choices that were selected by respondents. This function can be called as follows:
```R
# Expand the choices in variable ws7
expandMultChoice(answers = renameODK(sampleData2)$ws7)
```
**3. Merge nested datasets**
For ODK forms with a `repeat` argument, the resulting dataset splits the data into each of the repeats. Often, these multiple datasets need to be merged to a parent dataset (usually data containing common identifiers such as cluster, household). The `mergeNestedODK()` function merges together these datasets using the ODK-defined `KEY` and `PARENT-KEY` variables. The function can be called as follows:
```R
mergeNestedODK(parent = renameODK(sampleData1),
child = renameODK(sampleData2))
```
### ODK-R interface functions
Following are the ODK interface functions in the `odkr` package. However, before these functions can be utilised, a local copy of **ODK Briefcase** needs to be downloaded and it would be through this local copy of **ODK Briefcase** that the other functions will integrate wit ODK databases.
To download the latest version of **ODK Briefcase**, the `get_briefcase()` function can be utilised as follows:
```R
get_briefcase(destination = "~/Desktop")
```
will download the latest version of **ODK Briefcase** in your `Desktop` and rename it as `odkBriefcase_latest`. Specifying the destination directory for **ODK Briefcase** is required.
If it is preferred to save the **ODK Briefcase** with a different filename, the following command can be issued in R:
```R
get_briefcase(destination = "~/Desktop", briefcase = "odkTool")
```
This will save a local copy of **ODK Briefcase** in the `Desktop` and name it as `odkTool.jar`.
Downloading **ODK Briefcase** can be done only once unless you want to update to the latest version of **ODK Briefcase** from a previously downloaded older version.
Once you have downloaded **ODK Briefcase**, the following functions can be utilised to integrate with ODK databases.
**1. Pull forms from a remote ODK Aggregate Server**
If you have an **ODK Aggregate Server** already setup receiving form submissions from your survey, you can use `odkr` to pull these forms (not the data) into a local directory.
For example, you want to pull ODK form with form id `stakeholders` from your remote **ODK Aggregate Server** (i.e., ONA) `https://ona.io/validtrial/` to a local directory `~/Desktop` using your **ODK Aggregate Server** account with ***username*** `validtrial` and ***password*** `zEF-STN-5ze-qom`. The `pull_remote` function from `odkr` can be used as follows:
```R
pull_remote(target = "~Desktop",
id = "stakeholders",
to = "~/Desktop",
from = "https://ona.io/validtrial/"
username = "validtrial",
password = "zEF-STN-5ze-qom")
```
In this example, you will note that we are using a previously downloaded **ODK Briefcase** saved in the `Desktop`. The `target` specification can be changed to the directory where you have previously saved **ODK Briefcase**.
After the operation has been completed, you would now be able to see a folder named **ODK Briefcase Storage** on your `Desktop` containing the forms and instances from the stakeholders form on the **ODK Aggregate Server**.
**2. Pull forms from a local `/odk` folder extracted from ODK Collect**
If you do not have an **ODK Aggregate Server** setup and plan to use **ODK Briefcase** as your form aggregator, you will have to extract/copy the `/odk` folder in your mobile client to a location in your computer (e.g., `~/Desktop`) to which you can apply the `pull_local` function to pull out the forms and instances to a local directory (e.g., `~/Desktop`) as follows:
```R
pull_local(target = "~/Desktop",
id = "stakeholders",
to = "~/Desktop",
from = "~/Desktop")
```
In this example, you will note that we are using a previously downloaded **ODK Briefcase** saved in the `Desktop`. The `target` specification can be changed to the directory where you have previously saved **ODK Briefcase**.
After the operation has been completed, you would now be able to see a folder named **ODK Briefcase Storage** on your desktop containing the forms and instances from the stakeholders form on the **ODK Aggregate Server**.
**3. Export data from an ODK Briefcase Storage into a CSV file**
If you have pulled your forms from either a remote **ODK Aggregate Server** or a local `/odk` folder and now have an **ODK Briefcase Storage** in one of your local directories, you will probably want to extract the data found in these forms for use in other purposes e.g., data analysis.
The `export_data` function allows you to extract data from a local **ODK Briefcase Storage** (e.g., found in your `~/Desktop`) containing a form `stakeholders` and save it in a local directory (e.g., `~/Desktop`) as a `.csv` file named `test.csv` as follows:
```R
export_data(target = "~/Desktop",
id = "stakeholders",
from = "~/Desktop",
to = "~/Desktop",
filename = "test.csv")
```
## Citation
If you find the `odkr` package useful, please cite using the suggested citation provided by a call to the `citation` function as follows:
```{r citation, echo = TRUE, eval = TRUE}
citation("odkr")
```
## Disclaimer
`odkr` is an independently developed R package and is not officially part of ODK and is not developed, recognised and endorsed as a product/service of ODK.
## Community guidelines
Feedback, bug reports, and feature requests are welcome; file issues or seek support [here](https://github.com/rapidsurveys/odkr/issues). If you would like to contribute to the package, please see our [contributing guidelines](https://rapidsurveys.io/odkr/CONTRIBUTING.html).
This project is released with a [Contributor Code of Conduct](https://contributor-covenant.org/version/2/0/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms.