Remotely use R packages on Github through OpenCPU

October 1, 2013


Any R package on Github can be used remotely on OpenCPU through the /ocpu/github/ API. Users on the internet can browse code, objects, help pages, or call functions in the package without having to learn R or install it on their local machine. Thereby you can make your method, algorithm, plot or DPU more accessible outside the R community.

For example: last time we discussed how OpenMHealth uses the geodistance function to calculate the total distance along a set of lon/lat coordinates using Haversine formula. The geodistance function is included in the dpu.mobility R package and avaible on the openmhealth github repository. By putting the dpu.mobility package on Github, all functionality in the package can now be accessed directly though the OpenCPU cloud server. Try opening some of the URL’s below in your browser (play around with the URL to get a sense of the API). The package help pages are available under /man/ (in several formats):

The R functions and objects in the package are available under /R/:

Any R function in the package can be called remotely using HTTP POST. For example to calculate the distance from LA to NY and back with curl:

#POST function call as url-encoded
curl https://cloud.opencpu.org/ocpu/github/openmhealth/dpu.mobility/R/geodistance/json -d \
 'long=[-74.0064,-118.2430,-74.0064]&lat=[40.7142,34.0522,40.7142]'

#POST equivalent call using json
curl https://cloud.opencpu.org/ocpu/github/openmhealth/dpu.mobility/R/geodistance/json \
 -H "Content-Type: application/json" -d '{"long":[-74.0064,-118.2430,-74.0064],"lat":[40.7142,34.0522,40.7142]}' 

We use curl for illustration in this example, but any browser or web client could do the same thing, allowing anyone to embed your algorithms or plots in systems and applications.

Try it yourself!

For an R package to be used remotely on OpenCPU, it must be installible with install_github and the R package name must be identical to the repository name. I.e. if this works on your local machine:

library(devtools)
install_github("plyr", "hadley")

Then the package will be available remotely though:

Try to see if you can access your own packages! Some of the usual suspects:

HTTP POST calls a function in any of these packages straight from github:

#from ?llply
curl https://cloud.opencpu.org/ocpu/github/hadley/plyr/R/llply/json -d '.data=baseball&.fun=summary'

#simple plot
curl https://cloud.opencpu.org/ocpu/github/hadley/ggplot2/R/qplot -d 'x=[1,2,3,4,5]&y=[2,3,2,4,2]'

Publishing OpenCPU apps

An OpenCPU app is an R package which includes some web page(s) that call the R functions in the package using the OpenCPU API. Some public example apps are published on the OpenCPU Github Repo, but you can just as easily develop and publish apps by putting them on your own Github repository. For example: Scott Chamberlain has an (old) version of the gitstats app on his personal github repo at github.com/SChamberlain/gitstats We can access this version of the app directly on the OpenCPU cloud server using the corresponding url: /ocpu/github/SChamberlain/gitstats/www/

Final note

One final note: in the current implementation of OpenCPU, packages from Github are installed no more than once every 24 hours. So your most recent Github commits might not show up immediately. The recommended workflow is to use the OpenCPU local single user server to develop your package/app. Once it works locally, push your package to Github to make it available on the OpenCPU cloud server.