S3 Classes

S3, so called because it was first implemented in version 3 of the S language, uses a concept called generic functions. Everything in R is an object, and each object has a string property called class that signifies what the object is. There is no validation around it, and we can overwrite the class property ad hoc. That’s the main problem with S3—the lack of validation. If you ever had an esoteric error message returned when trying to use a function, you probably experienced the repercussions of this lack of validation firsthand. The error message was probably generated not from R detecting that an incorrect type had been passed in, but from the function trying to execute with what was passed in and failing at some step along the way.

See the following code, in which we create a matrix and change its class to be a vector:

> m <- matrix(c(1:10), nrow=2)
> m
   [,1] [,2] [,3] [,4] [,5]
[1,]    1    3    5    7    9
[2,]    2    4    6    8   10
> class(m) <- "vector"
> m
   [,1] [,2] [,3] [,4] [,5]
[1,]    1    3    5    7    9
[2,]    2    4    6    8   10
attr(,"class")
[1] "vector"

Generic functions are objects that check the class property of objects passed into them and exhibit different behavior based on that attribute. It’s a nice way to implement polymorphism. We can see the methods that a generic function uses by passing the generic function to the methods() function. The following code shows the methods of the plot() generic function:

> methods(plot)
[1] plot.acf*           plot.data.frame*    plot.decomposed.ts* plot.default        plot.dendrogram*
[6] plot.density        plot.ecdf           plot.factor*        plot.formula*       plot.function
[11] plot.hclust*        plot.histogram*     plot.HoltWinters*   plot.isoreg*        plot.lm
[16] plot.medpolish*     plot.mlm            plot.ppr*           plot.prcomp*        plot.princomp*
[21] plot.profile.nls*   plot.spec           plot.stepfun        plot.stl*           plot.table*
[26] plot.ts             plot.tskernel*      plot.TukeyHSD
Non-visible functions are asterisked

Notice that within the generic plot() function is a myriad of methods to handle all the different types of data that could be passed to it, such as plot.data.frame for when we pass a data frame to plot(); or if we want to plot a TukeyHSD object plot(), plot.TukeyHSD is ready for us.

Now that you know how S3 object-oriented concepts work in R, let’s see how to create our own custom S3 objects and generic functions.

An S3 class is a list of properties and functions with an attribute named class. The class attribute tells generic functions how to treat objects that implement a particular class. Let’s create an example using the UserClass idea from Figure 3-2:

> tom <- list(userid = "tbarker", password = "password123", playlist=c(12,332,45))
> class(tom) <- "user"

We can inspect our new object by using the attributes() function, which tells us the properties that the object has as well as its class:

> attributes(tom)
$names
[1] "userid"   "password" "playlist"
$class
[1] "user"

Now to create generic functions that we can use with our new class. Start by creating a function that will handle only our user object; then generalize it so any class can use it. It will be the createPlaylist() function and it will accept the user on which to perform the operation and a playlist to set. The syntax for this is [ function name ].[ class name ]. Note that we access the properties of S3 objects using the dollar sign:

>createPlaylist.user <- function(user, playlist=NULL){
    user$playlist <- playlist
    return(user)
}

Note that while you type directly into the console, R enables you to span several lines without executing your input until you complete an expression. After your expression is complete, it will be interpreted. If you want to execute several expressions at once, you can copy and paste into the command line.

Let’s test it to make sure it works as desired. It should set the playlist property of the passed-in object to the vector that is passed in:

> tom <- createPlaylist.user(tom, c(11,12))
> tom
$userid
[1] "tbarker"
  
$password
[1] "password123"
  
$playlist
[1] 11 12
  
attr(,"class")
[1] "user"

Excellent! Now let’s generalize the createPlaylist() function to be a generic function. To do this, we just create a function named createPlaylist and have it accept an object and a value. Within our function, we use the UseMethod() function to delegate functionality to our class-specific createPlaylist() function: createPlaylist.user.

The UseMethod() function is the core of generic functions: it evaluates the object, determines its class, and dispatches to the correct class-specific function:

> createPlaylist <- function(object, value)
{
      UseMethod("createPlaylist", object)
}

Now let’s try it out to see whether it worked:

> tom <- createPlaylist(tom, c(21,31))
> tom
$userid
[1] "tbarker"
  
$password
[1] "password123"
  
$playlist
[1] 21 31
  
attr(,"class")
[1] "user"

Excellent!

S4 Classes

Let’s look at S4 objects. Remember that the main complaint about S3 is the lack of validation. S4 addresses this lack by having overhead built into the class structure. Let’s take a look.

First we’ll create the user class. We do this with the setClass() function.

• The first parameter in the setClass() function is a string that signifies the name of the class that we are creating.
• The next parameter is called representation and it is a list of named properties.

  setClass("user",
  representation(userid="character",
      password="character",
      playlist="vector"
  )
  )

  We can test it by creating a new object from this class. We use the new() function to create a new instance of the class:

  > lynn <- new("user", userid="lynn", password="test", playlist=c(1,2))
  > lynn
  An object of class "user"
  Slot "userid":
  [1] "lynn"
    
  Slot "password":
  [1] "test"
    
  Slot "playlist":
  [1] 1 2

  Very nice. Note that for S4 objects, we use the @ symbol to reference properties of objects:

  > lynn@playlist
  [1] 1 2
  > class(lynn)
  [1] "user"
  attr(,"package")
  [1] ".GlobalEnv

  Let’s create a generic function for this class by using the setMethod() function. We simply pass in the function name, the class name, and then an anonymous function that will serve as the generic function:

  > setMethod("createPlaylist", "user", function(object, value){
        object@playlist <- value
        return(object)
   })
  Creating a generic function from function 'createPlaylist' in the global environment
  [1] "createPlaylist"
  >

  Let’s try it out:

  > lynn <- createPlaylist(lynn, c(1001, 400))
  > lynn
  An object of class "user"
  Slot "userid":
  [1] "lynn"
    
  Slot "password":
  [1] "test"
    
  Slot "playlist":
  [1] 1001  400

Excellent!

Although some prefer the simplicity and flexibility of the S3 way, some prefer the structure of the S4 method; the choice of S3 or S4 objects is purely one of personal preference. My own preference is for the simplicity of S3, and that is what we will be using for the remainder of the book. Google, in its R Style Guide available at http://google-styleguide.googlecode.com/svn/trunk/google-r-style.html, mirrors my own feelings about S3, saying “Use S3 objects and methods unless there is a strong reason to use S4 objects or methods.”

Median and Mean

Note that the median is the number that is the middle value in a data set, quite literally the number that has the same amount of numbers greater and less than itself in the data set. If our data set looks like the following, the median is 3:

1, 2, 3, 4, 5

But notice that it’s easy to find the median when there are an odd number of items in a data set. Suppose that there is an even number of items in a data set, as follows:

1, 2, 3, 4, 5, 6

In this case we take the middle pair, 3 and 4, and get the average of those two numbers. The median is 3.5.

Why does the median matter? When you look at a data set, there are usually outliers at either end of the spectrum, values that are much higher or much lower than the rest of the data set. Gathering the median value excludes these outliers, giving a much more realistic view of the average values.

Contrast this idea with the mean, which is simply the sum of the values in a data set divided by the number of items. The values include the outliers, so the mean can be skewed by having significant outliers and really represent the full data set.

For example, look at the following data set:

1, 2, 3, 4, 30

The median is still 3 for this data set, but the mean is 8, because of this:

median = [1,2]3[4,30]
mean =  1 + 2 + 3 + 4 + 30 = 40
    40 / 5 = 8

Quartiles

The median is the center of the data set, which means that the median is the second quartile. Quartiles are the points that divide a data set into four even sections. We can use the quantile() function to pull just the quartiles from our data set.

> quantile(USArrests$Murder)
  0%    25%    50%    75%   100%
0.800  4.075  7.250 11.250 17.400

The summary() function simply returns the quartiles, as well as the minimum, maximum, and mean values. Here are the summary() results for comparison, with the previous quartiles highlighted:

> summary(USArrests)
   Murder          Assault         UrbanPop          Rape
Min.   : 0.800   Min.   : 45.0   Min.   :32.00   Min.   : 7.30
1st Qu.: 4.075   1st Qu.:109.0   1st Qu.:54.50   1st Qu.:15.07
Median : 7.250   Median :159.0   Median :66.00   Median :20.10
Mean   : 7.788   Mean   :170.8   Mean   :65.54   Mean   :21.23
3rd Qu.:11.250   3rd Qu.:249.0   3rd Qu.:77.75   3rd Qu.:26.18
Max.   :17.400   Max.   :337.0   Max.   :91.00   Max.   :46.00

Standard Deviation

Speaking of the idea of the mean, there is also the idea that data has a normal distribution, or that data is normally densely clustered around the mean with lighter groupings above and below the mean. This is usually demonstrated with a bell curve, in which the mean is the top of the curve, and the outliers are distributed on either end of it (see Figure 3-4).

Standard deviation is a unit of measurement that describes the average of how far apart the data is distributed from the mean, so we can detail how far each data point is from the mean in terms of standard deviations.

In R, we can determine the standard deviation using the sd() function. The sd() function expects a vector of numeric values:

> sd(USArrests$Murder)
[1] 4.35551

If we want to gather the standard deviation for a matrix we can use the apply() function to apply the sd() function, like so:

> apply(USArrests, sd)
  Murder    Assault   UrbanPop       Rape murderRank
4.355510  83.337661  14.474763   9.366385  14.574930

R Markdown

In version 0.96 of RStudio, the team announced support for R Markdown using the knitr package. We can now embed R code into markdown documents that can get interpreted by knitr into HTML. But it gets even better.

The RStudio company also makes a product called RPubs that allows users to create accounts and host their R markdown files for distribution over the Web.

A quick overview of markdown syntax follows:

header 1
=========
  
header 2
--------------
  
###header 3
  
####header 4
  
*italic*
**bold**
  
[link text]([URL])
  
![alt text]([path to image])

The great thing about R Markdown is that we can embed R code within our markdown document. We embed R using three tick marks and the letter r in curly braces:

```{r}
[R code]
```

We need three things to begin creating R Markdown (.rmd) documents:

• R
• R Studio IDE version 0.96 or higher
• The knitr package

The knitr package is used to reformat R into several different output formats, including HTML, markdown, or even plain text.

Because you already have R and RStudio IDE installed, you will first install knitr. R Studio IDE has a nice interface to install packages: simply go to the Tools file menu and click Install Packages. You should see the popup that shown in Figure 3-7, in which you can specify the package name (R Studio IDE has a nice type ahead here for package discovery) and what library to install to.

After knitr is installed, you need to close and relaunch RStudio IDE. You then go to the File menu and choose File ➤ New, in which you should see a number of options, including R Markdown. If you choose R Markdown, you get a new file with the template shown in Figure 3-8.

The R Markdown template has the following code:

Title
========================================================
This is an R Markdown document. Markdown is a simple formatting syntax for authoring web pages (click the **MD** toolbar button for help on Markdown).
When you click the **Knit HTML** button a web page will be generated that includes both content as well as the output of any embedded R code chunks within the document. You can embed an R code chunk like this:
```{r}
summary(cars)
```
  
You can also embed plots, for example:
  
```{r fig.width=7, fig.height=6}
plot(cars)
```

This is the template, and when you click the Knit HTML button you will see the output shown in Figure 3-9.

Did you notice the Publish button at the top of Figure 3-9? That is how we push our R Markdown file to RPubs for hosting and distribution over the Web.

RPubs

RPubs is a free web publishing platform for R Markdown files, provided by RStudio (the company). You can create a free account by visiting http://www.rpubs.com. Figure 3-10 shows a screen shot of the RPubs homepage.

Just click the Register button and fill out the form to create your free account. RPubs is fantastic; it’s a platform in which we can post our R Markdown documents for distribution.

After you click the Publish button, you are prompted to log in with your RPubs account. After logging in, you will be directed to the Document Details page, as seen in Figure 3-11.

After filling out the document details, a title for your document, and a description, you will be directed to your document hosted in RPubs. See Figure 3-12 for the template from Figure 3-9 hosted in RPubs and available publicly here: http://www.rpubs.com/tomjbarker/3370.

This is a powerful distribution method for R documents and for communicating data visualizations. In the coming chapters, we will put all the completed R charts up on RPubs for public consumption.