An example of R in TERR (Package “RinR”) using the Census REST API
In this post we will walk through an example of acquiring data from the US Census RESTful web service API (Application Program Interface) via URL parameters. In simple terms, a RESTful URL allows you to pass URL parameters into an online datasource and returns the data specified by the parameters. Using a RESTful source enables access to data without having to store this information locally in a database or flat file.
Please note, I will be referring to the Census web service as the “Census API” for much of this post; however, at times I may say “Census URL” particularly when speaking of the parameter’s required in the URL. For clarity, the Census URL is the “Interface” portion of the Census Application Program Interface.
Click here to learn more about REST
The full Census API to Spotfire process consists of four parts:
1) Installing R alongside TERR in your local machine
2) Adding new packages to your R instance
3) Manipulating the Census Data API via R
4) Learning how to access R within TERR using the TERR package “RinR”
This post will go over parts one and two. A follow-up post will detail parts three and four.
TIBCO Enterprise Runtime for R (“TERR”)
TIBCO Enterprise Runtime for R or TERR is a powerful, and often overlooked, tool that comes standard with Spotfire Analyst. It allows the use of many R packages optimized for use in Spotfire. While the TERR development team has done a tremendous job of migrating R packages, there are thousands of R packages with new ones being added every day, making it impossible to migrate all of them.
Therefore, to maximize your TERR experience, we need to leverage all the packages available for R.
But first, a warning: This solution is only for a local device running TERR and R. It does not address using Statistics Service or configuring analysis for online consumers.
With that out of the way, let’s install R!
Installing R on your local machine
Installing R starts with downloading the installer from CRAN. R is made available through the Comprehensive R Archive Network (CRAN). This is arguably the most confusing step in installing R – finding what you need to download!
To make things easy here’s the download location for Windows users. Other users can navigate to the download here.
While CRAN does provide installation instructions, you’ll find these few short steps most helpful:
1) Download and run the R installer
2) Select the installation directory, the default is C:Program FilesR<version number>
3) Select if you want both or just the 32- or 64-bit install (R will figure out which one your need in most cases)
4) Select start up options (this just customizes how the R default GUI will display and it will not impact performance)
5) Select your preference of start menu and desktop options
6) Install
You now have R installed!
There are several ways to access R:
1) Original Console /command line / terminal interface (R.exe)
- R was initially entered line by line and that option remains today. Assuming you installed R in your default directory you can access R Console here: C:Program FilesRR-3.0.2bin. Simply double click R.exe to open the Console. It looks just like a command line interface in Windows or a Terminal in UNIX.
2) R GUI (Rgui.exe)
- R also comes packaged with a basic GUI application. There are 32- and 64-bit versions, both found in the x32and x64 folders contained in the “bin” folder you found R.exe and both named Rgui.exe. The R GUI is also the application opened when selecting the R application from your start menu or desktop, if you elected to have those shortcuts created when installing R.
3) Third Party Application
- There are many different applications which use R (like Spotfire!); however, creating complex scripts in Spotfire’s interface can be difficult, almost as difficult as using R’s command line interface. Therefore, several third party applications exist to make your R coding experience much easier. We will not go into these here, but in an upcoming post we’ll go in-depth on setting up Rstudio to program in both R and TERR.
Now you’ve installed R and you can open it, so let’s use it!
Installing Packages in R
Let’s open up our R GUI application. You should be able to find it in your start menu. If it’s not there, check in your R “bin” folder C:Program FilesRR-3.0.2bin<64 or 32> for the file called Rgui.exe.
See the image below for some help if this is your first time using R:
All you get initially is a fancy version of the R Console. The red cursor at the bottom is where you enter commands, so let’s enter a command.
First, to verify R is working, let’s try something simple. Type 2+2 and hit Enter:
It should return 4.
Click here for an excellent tutorial and explanation on R functionality and commands.
Now that we have confirmed R is working, it is time to extend its functionality. As we mentioned before, in order to get the most out of R, we need to install packages. In this example, we are installing the jsonlite package (R is case sensitive) in order to extract and transform JSON data from the Census API.
Installing packages is a relatively painless process. It is as simple as executing install.packages(<packagename>) if you know the exact name and case of your package. You can also select Packages > Install Packages… from your R GUI for a list of available packages.
In this example we will install jsonlite by typing install.packages(“jsonlite”) in the console and hit Enter.
What. Is. Happening!?
A feature of R GUI is an easy way to select your CRAN mirror. A CRAN mirror is an online repository of R packages. Typically highlighting the location closest to you geographically, then clicking “OK” will work fine.
Also notice the line on the Console output à Installing package into C:/Users/<user>/Documents/R/win-library/3.0 (as ‘lib’ is unspecified)
This is your default library location. It is where packages are installed. In TERR this will be different; therefore, if you run into issues combining TERR and R, the first step is to define the library location of scripts when loading libraries. There will be additional info on library locations in a future post.
Once you select a CRAN mirror, jsonlite will begin to install. R may also install other dependent packages required for jsonlite to function properly if they are not already present. So don’t panic if it starts “Installing Dependencies.”
Finally, confirm jsonlite has been successfully installed by loading it from the package library via library(jsonlite) or requrie(jsonlite). library(<package name>) is how you tell R to use a particular package in your script. Remember, a library is the location a package is stored in, but in most cases you can use the terms “library” and “package” interchangeably when talking about these things.
If there are no error messages when calling the library, you have successfully installed jsonlite.
With R and jsonlite successfully installed our next step is to access data, then manipulate it with Spotfire. Our next post will show you how to use the jsonlite package to access data via the Census REST URL, then use the R jsonlite code within a TERR script to run everything within Spotfire.
That’s all for now – stay tuned for PART 2 on How to use R-Scripts in TIBCO Spotfire® TERR.
Take your TERR knowledge to the next level with our latest Ebook!
[maxbutton id=”8″]
