README.md

ruODK: An R Client for the ODK Central API

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 (ODK) is free-and open-source 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 and visit the friendly ODK forum.

ODK Central is a cloud-based data clearinghouse for digitally captured data, replacing the older software ODK Aggregate. ODK Central manages user accounts and permissions, stores form definitions, and allows data collection clients like ODK Collect to connect to it for form download and submission upload.

A typical ODK workflow: An XForm is designed e.g. in ODK Build, published to ODK Central, and downloaded onto an Android device running ODK Collect. After data have been captured digitally using ODK Collect, 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.

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, RMarkdown), interactive web apps (Shiny), workflow scaling (drake).
• Rstudio-as-a-Service (RaaS) at

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.

ruODK’s use cases:

• Smaller projects: Example rOzCBI
  1. Data collection: ODK Collect
  2. Data clearinghouse: ODK Central
  3. Data analysis and reporting: Rmd (ruODK)
  4. Publishing and dissemination: ckanr, CKAN
• 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, CKAN

Out of scope:

• To wrap “management” API endpoints. ODK Central is a VueJS/NodeJS application 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

Install

You can install the latest release of ruODK from the rOpenSci R-Universe:

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

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.

ODK Central

Access to an ODK Central instance

First, we need an ODK Central instance and some data to play with!

Either request a free trial or follow the setup instructions to build and deploy your very own ODK Central instance.

ODK Central setup

The ODK Central user manual provides up-to-date descriptions of the steps below.

• Create a web user account on an ODK Central instance. Your username will be an email address.
• Create a project and give the web user at least read permissions.
• Create an XForm, e.g. using ODK Build, or use the example forms provided by ruODK. The .odkbuild versions can be loaded into ODK Build, while the .xml versions can be directly imported into ODK Central.
• Publish the form to ODK Central.
• Collect some data for this form on ODK Collect and let ODK Collect submit the finalised forms to ODK Central.

Configure ruODK

For all available detailed options to configure authentication for ruODK, read vignette("setup", package = "ruODK").

Use ruODK

A detailed walk-through with some data visualisation examples is available in the vignette("odata-api", package="ruODK").

See also vignette("restful-api", package="ruODK") for examples using the alternative RESTful API.

Try ruODK

will launch a disposable, hosted RStudio instance with ruODK installed and the companion package urODK opened as starting point for a hands-on workshop or instant demo of ruODK usage.

Create a new RMarkdown workbook from ruODK template “ODK Central via OData” and follow the instructions within.

Contribute

Contributions through issues and PRs are welcome!

See the contributing guide 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). The development was funded both by DBCA core funding and external funds from the North West Shelf Flatback Turtle Conservation Program.

To cite package ruODK in publications use:

citation("ruODK")
#> 
#> To cite ruODK in publications use (with the respective version number:
#> 
#>   Mayer, Florian Wendelin. (2020, Nov 19).  ruODK: An R Client for the
#>   ODK Central API (Version X.X.X).  Zenodo.
#>   https://doi.org/10.5281/zenodo.3953158
#> 
#> A BibTeX entry for LaTeX users is
#> 
#>   @Misc{,
#>     title = {ruODK: Client for the ODK Central API},
#>     author = {Florian W. Mayer},
#>     note = {R package version X.X.X},
#>     year = {2020},
#>     url = {https://github.com/ropensci/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") for a comprehensive comparison of ruODK to other software packages from both an ODK and an OData angle.