x

What is a function, anyway?

x

For programming purposes, one should think of a function as a type of object that takes certain types of INPUTS, and – once those inputs are given – produces a definite OUTPUT.

A simple example is the AVERAGE function, for which the input is a list of numbers

and the output is the average

We can think of the AVERAGE function schematically as follows:

The “object” that acts as input to the function is a finite list of numeric data. The “object” that is output by the function is a single numeric value. The function itself is also an “object”.

Functions in R

x

You can define functions yourself in R using the function command. When you create a function it is an object, that can be used in R like any other object.

A function in R has 3 components:

• The function body. This is the entire code inside the function.
• The function arguments. These are the types of input needed for the function to work. They are specified in the body of the function.
• The function environment. This is a specification of the location of the inputs to the function.

The structure of a function will typically look like this:

functionname<-function(argument1, argument2, … ){computations using the arguments}

An example

In this example we use a function to compute the fraction of data points, from a given data set, that lie within standard deviations from the mean.

We INPUT a vector of numerical data and a positive number .

Note that the input vector is a single object in R: it has numerical components, yet so far as R is concerned it is a column vector (= an ordered list).

We OUTPUT a single number: the fraction of data points, from, that lie within standard deviations from the mean of .

In specifying this function we will do something that is very common – we will make use of other, existing R functions, such as mean and standard deviation (among others).

Let’s see how this might work

Let’s name the function zsf (for “z-score function”).

So our definition will begin:

zsf<-function(argument1, argument2, … ){computations using the arguments}

and we have to fill in the arguments and the computations to get the output.

The function arguments will be a column vector and a numeric value. Let’s call the data vector argument data, and the numeric argument k:

zsf<-function(data, k){computations using the arguments}

To do the computation in the body of the function we have to compute the mean and standard deviation of the input data set:

mean(data), sd(data)

Note that the functions mean and sd are part of the R stats package, which loads automatically when you open R.

Now we have to carry out the remaining computations that will give us the output:

• First, we extract from the data those data points that are within k standard deviations of the mean m. We do this using the built-in subset and abs function:

subset(data, abs(data-mean(data))<=k*sd(data))

• Then we want the ratio of the size of this data subset to the full data set:

length(subset(data, abs(data-mean(data))<=k*sd(data)))/length(data)

Stringing this together, the final form for the function is:

zsf<-function(data, k){length(subset(data, abs(data-mean(data))<=k*sd(data)))/length(data)}

Realizing the function in R

To realize this function in R we first need to import a data set. Here is a data set consisting of birth weights, in ounces, of babies of mothers who did not smoke during pregnancy, taken from the Stat Labs Data Page, and formatted as a .txt file: nosmoke

By right-clicking on the “nosmoke” file link you can get the URL of this file, which is http://www.blog.republicofmath.com/wp-content/uploads/2015/06/nosmoke.txt

We import this data into R, name it “nosmoke” and define the z-score function as above, and use it to  compute what fraction of the data is within 1 standard deviation of the mean:

• First, the read.table command reads in the nosmoke data, which has no header row, and for which we have blank separators:

> nosmoke<-read.table(“http://www.blog.republicofmath.com/wp-content/uploads/2015/06/nosmoke.txt”, header=FALSE, sep=””)

• However, when R reads the data into memory in this format, it is a data frame and not a simple column vector. You can see this by entering:

> str(nosmoke)

to get the structure of the data frame “nosmoke”. You will see in the structure of the data frame a header for the birth weights. In our case the header, given by R, is ‘V1’:

‘data.frame’: 742 obs. of 1 variable:
$ V1: int 120 113 123 136 138 132 120 140 114 115 …

We can extract the column headed ‘V1’ as follows:

> nosmokedata=nosmoke[[‘V1’]]

The “nosmokedata” is now a column vector, and we can, for example, plot a histogram of this data:

> hist(nosmokedata)

• Now we define the z-score function:

> zsf<-function(data,k){length(subset(data,abs(data-mean(data))<=k*sd(data)))/length(data)}

• And then we use the function to calculate what fraction of the data is within 1 standard deviation of the mean:

> zsf(nosmokedata,1)
[1] 0.7277628

So, approximately 72.8% of the data is within 1 standard deviation of the mean.

Plotting the function

Given a data set, such as the “nosmokedata” above, we can vary k and plot the fraction of data within k standard deviations of the mean, as simply a function of k (with the data as a given: in other words, with the data argument fixed).

• First we need to calculate a potential range of values for the variable k.

We calculate:

> (mean(nosmokedata)-min(nosmokedata))/sd(nosmokedata)
[1] 3.911052

and

> (max(nosmokedata)-mean(nosmokedata))/sd(nosmokedata)
[1] 3.043495

and so see that all the data lies within 4 standard deviations of the mean.

• We then create a vector of possible values for k using the seq function:

> values<-seq(0, 4, by=4/20)

Here we have chosen the range from 0 through 4, and divided that into 20 equally spaced intervals. A readout shows us the computed range of k values:

> values
[1] 0.0 0.2 0.4 0.6 0.8 1.0 1.2 1.4 1.6 1.8 2.0 2.2 2.4 2.6 2.8 3.0 3.2 3.4 3.6 3.8 4.0

We check that “values” is a vector:

> is.vector(values)
[1] TRUE

• Now we apply a function of 1 variable, k, to this vector of values.

First we define the function of the variable k:

> func<-function(k){zsf(nosmokedata,k)}

Then we use the function lapply to create a list as a result of applying this function of 1 variable to the vector “values”, and we unlist the result to get a data frame:

> y=unlist(lapply(values, func))

• We combine these two data frames with the cbind function, to get a data frame of k values paired with zsf(nosmokedata, k) values, and then plot that data frame:

> pairs<-cbind(values,z)

> plot(pairs,type=”b”,main=”zsf(k) as a function of k”, xlab=”k”, ylab=”zsf(k)”)

The plot allows us to see visually how the proportion of data within k standard deviations of the mean varies with k.

Note: the option type=“b” in the plot function draws both points and lines.

A skilled R programmer could have done this quicker and slicker: I hope I have laid out enough information so that you can see how functions are defined, can be applied to vectors, and plotted to give useful visual information.

Saving the function

Having defined a function such as the zsf function above, we would like to save it for future use.

Customizing R at Quick R byRob Kabacoff has a useful discussion on loading user-defined functions into R on startup.

Further reading

x

• User-written Functions from Quick R by Rob Kabacoff
• Functions from Advanced R by Hadley Wickham