One of the great things about the R programming language is the thousands of packages users have written to solve problems in areas of data import, data wrangling and data visualization.
We’re glad to introduce ona.R, a package that helps you import data from your Ona account into R. This package is a direct fork of Prabhas Pokharel’s awesome formhub.R library. As we work to improve ona.R, we’ll work to ensure it can be easily used with platforms like Formhub.
For the moment we are distributing ona.R from github, we’ll give an update when it’s in CRAN. The required packages are:
RJSONIO stringr plyr RCurl lubridate sp doBy
You can install ona.R by executing:
install.packages("devtools") library(devtools) install_github("onaio/ona.R")
install_github function will need to be called every time you need to update the package, which will be frequent for now, as the package is under active development. After installation, you can load it as you would load any other R package:
After downloading your dataset, ona.R post-processes your dataset to convert the different columns to the correct types, which it derives from the
type you specified during the creation of your XLSform.
Download your first dataset
At this point we should be ready to get started and use some of the ona.R functions. Likely the most useful, and the most basic, one is called
onaDownload. Try typing in
?onaDownload in your R terminal to see what it does. We’ll use it to download the
good_eats dataset from mberg’s Ona account, which is a public dataset and doesn’t require a password. (To download data from an account with a password, simply include it as the fourth parameter).
dataobject <- onaDownload("form_id_string","account","username","password")
"account"parameter can either be a personal account or an organization account that owns the form
good_eats <- onaDownload("good_eats", "mberg","mberg")
"good_eats"– is the form ID String we’re downloading data from, if you’re not sure of the form ID String, you can get it on the settings page of your form.
"mberg"– is the first “mberg” which is the account/username that owns the form. This can also be an
"mberg"– is the username that the form has been shared with or owns the form. This can also be referred to as the username that you use to log in to your account.
"password"– this is entered as the fourth parameter if the form is in a private project, and is the password for the username entered as the third parameter.
Functions in ona.R
onaDownload– download data directly from ona by passing form name, account/username/org_username, username, and password for private data
onaRead– create an onaData object from pre-downloaded files. The first file argument is the CSV file, the second is the form.json file (which you can download from the form page on ona). Note: unexpected things will happen if the files aren’t the right ones. See the full documentation by using
replaceHeaderNamesWithLabels– get a version of the data where the header row is re-written as the actual question asked.
replaceAllNamesWithLabels– get a new dataframe, where all
namesare replaced with full
Let us illustrate this with a simple example:
library(ona) # Download the dataset named good_eats in the account of mberg good_eats_data <- onaDownload("good_eats", "mberg","mberg")
Lets do a simple crosstab using
risk_factor from the data we’ve just downloaded.
# A simple crosstab using the food_type and risk_factor crosstab1 <- table(good_eats_data$food_type,good_eats_data$risk_factor)` # Call the crosstab output for viewing crosstab1
The output looks like:
We can also use the power of ona.R to replace all the
labels as follows:
good_eats_labels <- replaceAllNamesWithLabels(good_eats_data)` # We'll now create a similar crosstab as above, using this new data object. crosstab2 <- table(good_eats_labels$`Type of Eat`,good_eats_labels$`Risk Factor`) > Notice that here we are using the labels, unlike in the first example where we used the name. We've also wrapped the labels inside (` `) quotes because they have spaces in between. # Call the crosstab output for viewing crosstab2
The output looks like:
See the difference? In
crosstab1, we have
names, and in
crosstab2, we have the
And that’s really the gist of it! Hopefully by now you are sold on the usefulness of ona.R. You can learn more by visiting the ona.R Github page.
What if I get an error while running a function?
This is software that has been tested by only a couple of use cases so far, and writing good code in R is pretty tricky, so there are probably errors! If you encounter one, please share your Ona project with our support team by going to your project page, and under “Sharing”, enter the username
"Can View and Download" privileges. Then go ahead and file an issue on github.