Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/rapidsurveys/odkr
Open Data Kit R API
https://github.com/rapidsurveys/odkr
odk odk-briefcase open-data-kit
Last synced: about 2 months ago
JSON representation
Open Data Kit R API
- Host: GitHub
- URL: https://github.com/rapidsurveys/odkr
- Owner: rapidsurveys
- License: gpl-3.0
- Created: 2018-01-21T10:01:54.000Z (almost 7 years ago)
- Default Branch: main
- Last Pushed: 2024-04-13T07:26:58.000Z (8 months ago)
- Last Synced: 2024-05-02T03:28:10.071Z (8 months ago)
- Topics: odk, odk-briefcase, open-data-kit
- Language: R
- Homepage: https://rapidsurveys.io/odkr/
- Size: 13 MB
- Stars: 11
- Watchers: 3
- Forks: 4
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE.md
- Code of conduct: .github/CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# odkr: Open Data Kit (ODK) R API
[](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)
**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("odkr")
#> To cite odkr in publications use:
#>
#> Ernest Guevarra, Laura Bramley (2024). _odkr: Open Data Kit (ODK) R
#> API_. doi:10.5281/zenodo.1170514
#> , R package version
#> 0.3.3.9000, .
#>
#> A BibTeX entry for LaTeX users is
#>
#> @Manual{,
#> title = {odkr: Open Data Kit (ODK) R API},
#> author = {{Ernest Guevarra} and {Laura Bramley}},
#> year = {2024},
#> note = {R package version 0.3.3.9000},
#> url = {https://rapidsurveys.io/odkr/},
#> doi = {10.5281/zenodo.1170514},
#> }
```
## 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.