README.md
In odkr: 'Open Data Kit' ('ODK') R API

odkr: Open Data Kit (ODK) R API

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.

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 lastest 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. Jave 8 can be downloaded from here.

The ODK-R interface component of this package requires Java 8 to be installed in your computer. There are known issues when using ODK Briefcase with Java 9. If you have Java 9 installed, uninstall (on Windows; on macOS) and then install Java 8. If issues persist even with Java 8, you may need to reconfigure Java. On the terminal, execute the following command:

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:

sudo R CMD javareconf JAVA_HOME=/usr/java/default

# Install development version of odkr by installing devtools and then installing
# odkr package via git
install.packages("devtools")
devtools::install_github("validmeasures/odkr")
library(odkr)

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:

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:

# 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:

mergeNestedODK(parent = renameODK(sampleData1),
               child = renameODK(sampleData2))

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:

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:

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:

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 stakholders 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:

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 stakholders 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:

export_data(target = "~/Desktop",
            id = "stakeholders",
            from = "~/Desktop",
            to = "~/Desktop",
            filename = "test.csv")