Introducing ona.R – Easily use Ona in R

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.

Installing ona.R

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")

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

library(ona)

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 help(onaDownload) or ?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")

The "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 org_username.
• "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 help(onaRead).
• 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 names are replaced with full labels.

Let us illustrate this with a simple example:

We’ll start by downloading good eats data from mberg’s account. The good eats data is in a public project.

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 food_type and 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 names with 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 labels.

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 "onasupport" and "Can View and Download" privileges. Then go ahead and file an issue on github.