New version of overlap package

HOME A new version of the overlap package (0.3.2) is now available on CRAN, together with binary builds for Windows and Mac. A minor fix for getBandWidth means it works more often with weird data sets, and there's a new function, sunTime, which maps clock time to sunrise and sunset.

Animal activity patterns are in fact aligned to daylight intensity - in particular, sunrise, sunset and zenith - not to the time on your clock or GPS unit or camera (Nouvellet et al, 2012). Since the times of these events vary with the time of year, using clock time instead of sun time can lead to wrong inferences. Nouvellet et al (2012) give the example of hunting behaviour of African wild dogs: impala are almost always taken before sunset and kudu after sunset, but this effect disappears if time is measured relative to 6pm instead of sunset.

The new function has been used by Azevedo et al (2018) in their study of puma in Southeastern Brazil. Thanks to Daniel Rocha for providing the motivation for this.

overlap works with time in radians, normally mapping 6am to \(\pi/2\) and 6pm to \(3\pi/2\). The sunTime function remaps these times, so that \(\pi/2\) corresponds to sunrise and \(3\pi/2\) to sunset, using the dates and locations of the observations. Times of sunrise and sunset are calculated by the sunriset function in the maptools package, which uses algorithms provided by the National Oceanic & Atmospheric Administration (NOAA).

On 21 June in Scotland, day length (sunrise to sunset) is approximately 18 hours and night length 6 hours. The 18 "clock hours" of day are squeezed into the interval \(\pi/2\) to \(3\pi/2\), while the 6 "clock hours" of night are stretched to fill \(3\pi/2\) to \(\pi/2\). There is an abrupt change from squeezing to stretching at sunrise and back at sunset.

Even at the equator, the times of sunrise and sunset change, varying by 30 minutes over the year, in accordance with the equation of time.


Here is the example code from the help page. You will need to have both overlap and maptools packages installed to run this.

We use a built-in simulated data set with times (and dates) of bird calling activity: 80% occur around sunrise with a strong peak just before sunrise, the remainder occur around sunset. The hypothetical location is near St Andrews, UK, longitude 3 degrees West, latitude 56 degrees North (CRS WGS84) and times are GMT throughout (ie, ignoring daylight saving).

'data.frame':   100 obs. of  2 variables:
 $ time : num  2.38 4.07 1.17 2.26 1.86 ...
 $ dates: chr  "2017-01-05" "2017-01-09" "2017-01-13" "2017-01-14" ...

The dates are in ISO format, so we can easily convert to POSIXct format and set the GMT time zone.  If you have dates with other formats, the lubridate package will be helpful.

Dates <- as.POSIXct(simCalls$dates, tz="GMT")

Next we convert the location data to a SpatialPoints object. This can have a different location for each observation, but in this case they are close together, so we use a single location for all.

coords <- matrix(c(-3, 56), nrow=1)
Coords <- sp::SpatialPoints(coords,
   proj4string=sp::CRS("+proj=longlat +datum=WGS84"))

Now we can plug the times, dates and location(s) into the sunTime function and plot the results.

st <- sunTime(simCalls$time, Dates, Coords)

densityPlot(st, col='red', lwd=2, xaxt='n', main="Sun time")
axis(1, at=c(0, 6, 12, 18, 24),
    labels=c("midnight", "sunrise", "noon", "sunset", "midnight"))
densityPlot(simCalls$time, lwd=2, main="Clock time")

Plotted against clock time, the activity peaks appear to be broader, and the morning activity has become bimodal; this is an artefact of the measure used, as sunrise is around 4:30am for a long period in summer and 7:30am for a similarly long period in winter.


Updated 12 May 2018 by Mike Meredith