knitr::opts_chunk$set( collapse = TRUE, comment = "#>", fig.path = "man/figures/", out.width = "100%" )
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:
ruODK
's scope:
ruODK
's use cases:
Rmd
(ruODK)Larger projects:
Rmd
(ruODK)Rmd
ckanr
,
CKAN
Out of scope:
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.
ruODK
You can also run ruODK
through hosted or self-built Docker images.
In decreasing order of simplicity:
ruODK
versiondocker 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 in your browser. From there, you can run any available kernel, amongst others are RStudio and a plain R shell.
ruODK
For all available detailed options to configure authentication for ruODK
, read
vignette("setup", package = "ruODK")
.
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.
urODK
, a sing-along ruODK
workshop about you, R, and ODK,
is available on
.
Contributions through issues and PRs are welcome!
See the contributing guide on best practices and further readings for code contributions.
ruODK
was developed 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.
ruODK is maintained and extended by Florian Mayer.
To cite package ruODK
in publications use:
citation("ruODK")
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.
See vignette("comparison", package="ruODK")
for a comprehensive comparison of ruODK to other software packages from
both an ODK and an OData angle.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.