LoCoH: R Instructions

Introduction

This manual will walk you through the process of developing an animal's homerange using R. Though you can follow along without knowing anything about R, a little bit of R expertise will come in handy. If you just want to learn more about LoCoH, you might also want to check out the LoCoH web application tutorial:

Go to LoCoH Web Application Tutorial

Getting the Necessary Software

In order to run the R script the first thing you need is R. R is a powerful and flexible environment for running various scientific calculations with a strong emphasis on statistics. R runs on all major operating systems include Windows, Mac OS X, and various flavors of Linux and UNIX.

Download R

Once you've gotten your hands on R, you need to install a number of R libraries. These libraries are: ade4, adehabitat, shapefiles, and gpclib. To install them, just open up R and enter the following:

install.packages(c("gpclib","ade4","adehabitat","shapefiles"), dependencies=TRUE, repos="http://cran.cnr.berkeley.edu/")
	

You then should initialize the adehabitat package with this command:

library(adehabitat)
	

We're almost done. There is just one more thing: the LoCoH (k-NNCH) script itself. The adehabitat package contains a version of the R script, but it is often out of date. To make sure you have the most recent version, you should download it here:

Download LoCoH R Script

You can then load the script into R with the following command (assuming the path to the script is 'C:/NNCH.R'):

source("C:/NNCH.R")
	

Great! That wasn't too hard, was it? Now we are ready to analyze our data.

LoCoH Graphical User Interface

LoCoH includes a simple graphical user interface that is useful for exploring the capabilities of LoCoH. Some people might also prefer it to the command line method of using LoCoH. You will need to download the locoh_gui.R script and load it.

Download LoCoH R GUI

After you have made sure to load the NNCH source file as outlined above, you can invoke LoCoH trivially with the following commands:

#load the LoCoH Graphical Interface
source('C:/locoh_gui.R')

#to save the homerange generated to a variable
homerange<-locoh()

#or just
locoh()
	

Analyzing Data with R

Following the show, not tell method of instruction, why don't you just enter the following commands into your R terminal:

data(puechabon)
xys<-puechabon$locs[,c("X","Y")]
homerange<-NNCH(xys,k=10)
plot(homerange)
	

Up should pop an image which looks something like this: Let's step through what we just did. The first two lines load wild boar location data that is included in the adehabitat library. We store the x and y locations of boar sightings in the two columns of a matrix. Then we call the NNCH method that applies the LoCoH analysis to our data. Because we passed the NNCH method a k variable, the Fixed k LoCoH algorithm is used. If we had a passed an r variable, the Fixed r LoCoH algorithm would have been used. An a variable would have triggered the Adaptive LoCoH method. Lastly we plot our data.

If you look closer at the puechabon data, you will realise that there are actually four boars being tracked. The above homerange shows all four combined, but what if different boars live in different territories? To answer this question, we can analyze the data for each boar separately. Try entering the following into your R terminal:

ids<-puechabon$locs[,c("Name")]
homerange<-NNCH(xys, k=10, id=ids)
plot(homerange)
	

That changes the picture a little. So Jean and Chou are hanging out together at the bottom, while Brock and Calou do their own thing up north. What we just did by defining the id parameter was split our data up into four sets, one for each animal name. You could also use the id parameter to split your data up into 'Summer' and 'Winter' observations, 'Pre-Tsunami' and 'Post-Tsunami' observations, and basically whatever else you choose. The id array only needs to possess the same length of the xy array and must have a label for each point. The '.k10' tag added to the end of each name means that we were using a k value of ten when we constructed the homerange.

Why don't we try analyzing are data with different values of k. k is the number of nearest neighbors that are used in the construction of the minimum convex hulls that make up the foundation of the homerange. The larger the value of k, the greater area the homerange covers. Additionally, as k increases, the homerange converges towards the Minimum Convex Polygon. When k equals the number of points in the data set, the homerange is the MCP. A good suggested value for k is the square root of the number of points in the data set. Try entering the following to analyze the data with four different k's:

homerange<-NNCH(xys,k=c(20,30,40,50))
plot(homerange)
	

Here we can see how the area covered by the homerange expands as k increases. You can set k equal to any vector value, and LoCoH will analyze your data for each k. Be careful when mixing multiple k's and multiple id's though, because the combination can cause LoCoH to carry out a large number of separate runs bringing your computer to its knees!

One of the main reasons that we would want to try multiple k's is because we are not sure which k yields the best results for our homerange. LoCoH has some additional functions that help you locate an accurate value for k. Enter the following into your R terminal:

plot(NNCH.k.area(homerange))
#pause and look at the pretty picture, then
plot(NNCH.der.k.area(homerange,percent=90))

The first graph that is generated should look like this: This graph shows the area of the homerange as k changes. The top line shows the 100% isopleth, the bottom line shows the 50% isopleth. The second graph shows the derivative of the k vs area graph (this time though, only for the 90% isopleth). As you can see, there is a big jump from k=30 to k=40. Looking at the plots of the homerange confirms this. A k value of 40 is probably too big of a value for our data.

It is important to note that all the analysis we have been doing using the Fixed k LoCoH method, can also be done using the Adaptive LoCoH and Fixed r LoCoH algorithms. For instance if we could do the following to used Fixed r LoCoH:

homerange<-NNCH(xys,r=c(100,200,300,400))
plot(NNCH.r.area(homerange))

or, if we are partial to the amazing Adaptive LoCoH algorithm:

homerange<-NNCH(xys,a=c(1000,1500,2000,2500))
plot(NNCH.a.area(homerange))

Because both Fixed r LoCoH and Adaptive LoCoH do not guarantee that every point will be included as part of a hull, you might want to specify a minimum k value that points will be forced to take if they fall below it.

homerange<-NNCH(xys,r=100,min.k=3)

Here each point will be part of a convex hull of at least three points even if points are separated by a distance greater than r (100).

Getting Data in and out of R

Getting your data into R for analysis and then exporting your data is an important task. R has a number of data import and export methods. A useful introduction to them can be found in the R manual:

Go to the R Manual

LoCoH also includes some useful import and export methods for dealing with ESRI's shapefile format.

#Analyze data from a point shapefile
homerange<-NNCH.shapefile('C:/my_shapefile',k=20)
#Export isopleths to a polygon shapefile
NNCH.export.shapefile(homerange,'C:/my_isopleths')

Your input shapefile should be a point shapefile. The exported shapefiles will be polygon shapefiles and can be opened by ArcView, ArcMap, and many other programs. Extensions are not needed when exporting or importing shapefiles. LoCoH will add them.

Lastly, LoCoH has a handy method for analyzing tab deliminated textfiles of points. The first row of the textfile should be a heading labeling the columns. The first column should be the x-coordinate of a point, the second column should be the matching y coordinate. You should use the American system for decimals.

homerange<-NNCH.textfile('C:/my_text_file.txt')

More Features

There are a number of additional features that we have not yet discussed. Here we will quickly go through a number of them.

Duplicated Points

In animal sighting data--especially when data was gathered with a radio collar--there are often duplicated data points where an animal stayed in one location for a while. These may cause problems and could result in zero area hulls, if not handled correctly. We have three options for handling duplicated points.

#Displace duplicated points by n (in this case 10) units in a random direction
homerange<-NNCH(xys,duplicates=10)
#Delete all duplicated points and then analyze data
homerange<-NNCH(xys, duplicates='delete')
#Ignore the fact that we have duplicated points and create zero-area hulls if necessary
homerange<-NNCH(xys, duplicates='ignore')
	

The default method is to displace duplicated points by a distance of one.

Selective Data Examination

Sometimes you analyze a homerange for many k's, a's, r's, or id's, but then you want to be able to look at just a subset of your data, say one value of k, or one id. You can do this easily:

homerange<-NNCH(xys,k=c(10,20,30,40),id=ids)
#just select the brock data
brock_homerange<-NNCH.select(homerange,id='Brock')
#just select the k=20 data
k20_homerange<-NNCH.select(homerange,k=20)
	

Most of the NNCH data viewing functions will take k, a, r, and id values and just display the data selected by those parameters.

plot(homerange, k=c(20,30))
NNCH.k.area(homerange,id='brock')
	

A number of functions will also take a 'percent' vector or scalar that will determine which isopleths are used.

Summaries

You can display a nice summary of your homerange like this:

summary(homerange)
#you can also save the summary to a file
NNCH.summary(homerange,file='C:/Summary.txt')