Crunch.io provides a cloud-based data store and analytic engine. It has a web client for interactive data exploration and visualization. The crunch package for R allows analysts to interact with and manipulate Crunch datasets from within R. Importantly, this allows technical researchers to collaborate naturally with team members, managers, and clients who prefer a point-and-click interface: because all connect to the same dataset in the cloud, there is no need to email files back and forth continually to share results.
Subscribe to the mailing list to receive notification of releases and to ask general support questions.
crunch can be installed from CRAN with
The pre-release version of the package can be pulled from GitHub using the
remotes package (part of
# install.packages("remotes") remotes::install_github("Crunch-io/rcrunch")
Connecting to Crunch and working with datasets is simple: load the
crunch package and then
$ R > library(crunch) > login("firstname.lastname@example.org") Crunch password for email@example.com: You are now logged into Crunch as firstname.lastname@example.org [crunch] > ...
If you use OAuth to log into the web application, you'll need to create a Crunch password to use with the R package. To set one, load the package, call
resetPassword("email@example.com"), and check your email for instructions. You may need to log out of your current web app session before you click the link in that email to set your Crunch password.
Once you've logged in, check out
listDatasets() to see the names of your existing datasets, which you can load like
ds <- loadDataset("The name of my dataset"). New Crunch datasets can be made from a
data.frame, a .csv or .sav file, or a URL to a file with
newDataset(). See the help for these functions or
vignette("crunch") for more information.
You can set several parameters in your .Rprofile to simplify your workflow:
crunch.pw: you can save your Crunch credentials so that you don't have to enter them each time. I.e., you can just
> login(). Please be advised of the risks of storing your password like this. See
?loginfor more information. Also, note that you can opt to store just your
crunch.emailand enter your password each time you log in--a mix of convenience and security.
crunch.api: if not defined, it defaults to "
https://app.crunch.io/api/", the production server. To specify a different location, either set it in your .Rprofile or after loading the
If you prefer, you can set the environment variables
crunch requires R version 3.0 or greater. Note that if you're on Ubuntu, particularly older versions, you'll need to add an alternative PPA before trying to
apt-get install R. For 12.04 Precise, for example,
# apt-key adv --keyserver keyserver.ubuntu.com --recv-keys E084DAB9 # echo "deb http://cran.r-project.org/bin/linux/ubuntu precise/" >> /etc/apt/sources.list # apt-get update # apt-get install libcurl4-openssl-dev # sudo apt-get install r-base r-base-dev
See https://cran.r-project.org/bin/linux/ubuntu/README for more details.
The tests for the rcrunch package relies on mocks that are compressed into a tarball
so that the package stays within the CRAN 5MB size limit. To avoid git merge conflicts
this file is not checked in so it must be created before you can run tests. It is
created for you if you run
make test, or you can create it explicitly by running
make compress-fixtures or
See the contribution guidelines.
Installing from a local checkout
# make deps # make test
This installs dependencies and then runs the tests, which installs
crunch from your local checkout in the process. If the dependencies fail to install, check the error message. You may need to install
libcurl on your system before installing the R packages.
You can run tests in an interactive session, or from the command line,
$ make test is all you need. Requires the
httptest package for R. You can also specify a specific test file or files to run by adding a "file=" argument, like
$ make test file=auth.
test_package will do a regular-expression pattern match within the file names. See its documentation in the
Testing has two options: unit tests only, and tests that communicate with an API server. This is governed by an environment variable,
INTEGRATION, which is false by default, meaning that API integration tests are not run. To modify this and test against the Crunch API, you can run
$ make test INTEGRATION=TRUE.
To run integration tests, you will need to specify a test user, password, and API server to communicate with, either by setting
test.api in your
.Rprofile, as in:
options( test.user="firstname.lastname@example.org", test.pw="t0pSecretP@ssw0rD", test.api="https://app.crunch.io/api/" )
or by setting the environment variables
If you are a Crunch developer serving a version of the API/backend with Vagrant or Docker, you will have best results if your R_TEST_API/test.api (1) is
local.crunch.io, thanks to a mapping of localhost to that in your hosts file. In order to avoid self-signed certificate errors use the environment variable
R_TEST_VERIFY_SSL=FALSE. You might point at "https://local.crunch.io:8443/api/", for example. Some tests that cannot run successfully in the local environment will be skipped when run against a local.crunch.io URL.
Example of local usage:
$ R_TEST_VERIFY_SSL=TRUE R_TEST_USERemail@example.com R_TEST_PW=t0pSecretP@ssw0rD R_TEST_API=https://local.crunch.io:28443/api/ make test INTEGRATION=TRUE file=variable-summary
$ make doc. Requires the