In jbhender/camtrap: Inference for camera trap data.

knitr::opts_chunk$set(echo = TRUE)

Introduction

The R package camtrap is built on and extends the capabilities of the overlap package for analyzing time-of-day data such as that generated by camera traps. The primary extensions are:
- modified functions allowing attention to be focused on specific time windows,
- the addition of estimates for the area between densities rather than the overlap alone,
- the addition of "permutation" tests for hypothesis testing.

The following sections are meant to illustrate the use of the added functionality. This documentation and package are both in the early stages of development and not intended for use outside of current collaborators.

Quick Start

In this section we briefly describe how to get up and running with this package. This is a development version of the package available on git hub. For easy installation, first install and load the devtools package.

#install.packages('devtools')
library(devtools)

You can then install the most recent version of camtrap directly from GitHub as indicated in the comments below.

#install.packages('overlap')
#install_git('git://github.com/jbhender/camtrap/')
library(camtrap)

The overlap package is loaded automatically and must be installed prior to installing camtrap. The examples in the following section will make use of data from overlap.

data(simulatedData)
head(tigerObs); head(pigObs)

Overlap and Excess for a Fixed Window

The overlap package takes two vectors of observation times in radians, fits densities to each vector, and then estimates the overlap defined as the area under the minimum of the two density functions:

$$ \textrm{overlap} = \int_{t_0}^{t_1} f_1(s) \wedge f_2(s) ds. $$

overlapPlot(tigerObs,pigObs)
overlapEst(tigerObs,pigObs)

To focus on a specific time interval use the 'window' versions of these functions provided in this package. The time interval of interest is specified using t0 and t1. For overlapEstWindow these endpoints should be given on a 24 hour scale; the scale for overlapPlotWindow can be specified using the xscale option.

overlapPlotWindow(tigerObs,pigObs,t0=0,t1=24)
overlapEstWindow(tigerObs,pigObs,t0=0,t1=24)

The plotting function should include the same options as for overlapPlot, with the exception of providing a 'rug' plot which remains to be implemented.

Comparing the output of overlapEst and overlapEstWindow you can see that the overlap estimate most closely resembles "Dhat1". Both estimates directly use the area under the fitted density curves, but the version in this package uses adaptive quadrature (i.e. integrate) in place of a fixed grid.

Understanding the excess

In addition to estimating the overlap for a fixed user-provided window, the camptrap package also estimates the "excess" defined here to mean the area between the density curves: $$ E_{net}(t_0,t_1) = \int_{t_0}^{t_1} f_1(s) - f_2(s) ds. $$ The type option can be used in overlapPlotWindow to display the excess in place of the overlap.

overlapPlotWindow(tigerObs,pigObs,t0=16,t1=21,type='excess')
overlapEstWindow(tigerObs,pigObs,t0=16,t1=21)

Examining the output above, we can say that the difference in the proportions of tiger and pig activity between 16:00 and 21:00 is nearly 30%. As currently computed, the excess gives the net difference between the curves. We should consider alternate treatments of this such as:

$$ E_{max}(t_0,t_1) = \int_{t_0}^{t_1} (f_1(s) - f_2(s))+ ds \quad \vee \quad \int{t_0}^{t_1} (f_2(s) - f_1(s))+ ds, $$ where $(\cdot)+ = \min(\cdot,0)$.

Finding the points of intersection

The function overlapCross can be used to find the points at which two density curves cross. We will illustrate using the Kerinci data from the overlap package.

data('kerinci')
head(kerinci)
with(kerinci,table(Sps,Zone))

Note that the times there are given in [0,1], so we will multiply by $2\pi$ to scale to radians. The function will find all crossings, provided the minimal time between crossings is longer 1/n.grid.

macaque3 <- with(kerinci,Time[which(Sps=='macaque' & Zone==3)])*2*pi
macaque4 <- with(kerinci,Time[which(Sps=='macaque' & Zone==4)])*2*pi
crossings <- overlapCross(macaque3,macaque4,scale24=T)
crossings

We can extract the crossings between 6am and 6pm as shown below.

tt <- crossings[which(crossings > 6 & crossings < 18)]
overlapPlotWindow(macaque3,macaque4,xcenter='noon',tt[1],tt[2])

Inference using Permutation Tests

Based on these images, tigers and pigs clearly follow different patterns of activity. However, in other cases such as when comparing the same species from different regions we may wish to assess the significance of an observed difference relative to a specific null hypothesis. For example, when making intra-species comparisons, one may wish to assess whether observed differences provide evidence for real differences in activity patterns or can be attributed to the noise from finite sample sizes.

This can be done using the overlapPerm function, which tests against the null hypothesis that the densities generating the two observation vectors are equal during the requested time interval.

To illustrate the functionality, consider again the macaques from zones 3 and 4 in the Kerinci data. Let's focus on the daytime hours between 5am and 7pm.

overlapPlotWindow(macaque3,macaque4,5,19)

perm <- overlapPerm(macaque3,macaque4,t0=5,t1=19,nperm=1000)
print(perm)

Focusing on the overlap row, the output from the permutation tests tells us that the observed overlap during the requested window was r round(100*perm$table[1,1])%. Compare this to the reference value of r round(100*perm$table[1,2])% which is an estimate of the maximum overlap for the requested window. The reference value will always be one when considering the full day. The p-value tells us that from r perm$nperm simulations, only r round(perm$table[1,3]*100,1)% had an overlap smaller than the actually observed overlap suggesting the observed differences are not purely attributable to chance.

In contrast, the net excess during this window is not significantly different from zero. This make sense given that our window includes the bulk of the activity for both sets of macaques since densities always integrate to one.

We can compare our result based on the overlap, to a Kolmogorov-Smirnoff test comparing two distributions.

ks.test(macaque3,macaque4)
perm <- overlapPerm(macaque3,macaque4,t0=0,t1=24,nperm=1000)
print(perm)

This suggests the permutation test may be more powerful, though additional study is needed to ensure we are correctly controlling the type 1 error.

jbhender/camtrap documentation built on May 18, 2019, 5:59 p.m.