Detecting Cavity Use From Geolocator Data
cavityuse
is an R package for calculating patterns of cavity use from
geolocator light data. Patterns of light and dark are used to identify
daytime usage, while patterns of sunrise/sunset are used to identify
nighttime usage.
While
cavityuse
is ready to be experimented with, it’s still in early development and should be considered experimental. Please give me a hand by letting me know of any problems you have (missing functionality, difficult to use, bugs, etc.)
You can install cavityuse
directly from my R-Universe:
install.packages("cavityuse",
repos = c("https://steffilazerte.r-universe.dev",
"https://cloud.r-project.org"))
Load the package
library(cavityuse)
## cavityuse v0.5.0
## Please note that 'cavityuse' is still in early development
## Help by submitting bugs/feature requests: http://github.com/steffilazerte/cavityuse/issues
We’ll get started with the built in example file calib
which clearly
shows sunrise/sunset events
Let’s take a look at the patterns in the raw data:
cavity_plot(calib)
Look for any sunrise/sunset events in your geolocator data
s <- sun_detect(calib)
s
## # A tibble: 6 × 7
## date time dir n_range n dur offset_applied
## <date> <dttm> <chr> <dbl> <int> <int> <dbl>
## 1 2011-05-07 2011-05-07 03:45:57 sunrise 24 10 20 -8
## 2 2011-05-07 2011-05-07 20:07:57 sunset 32 10 20 -8
## 3 2011-05-08 2011-05-08 03:47:57 sunrise 63 10 20 -8
## 4 2011-05-08 2011-05-08 20:09:57 sunset 62 10 20 -8
## 5 2011-05-09 2011-05-09 03:39:56 sunrise 32 10 20 -8
## 6 2011-05-09 2011-05-09 20:11:56 sunset 62 10 20 -8
Let’s see what these look like
cavity_plot(data = calib, sun = s, days = 1)
Now let’s move on to the flicker
data set:
cavity_plot(flicker)
s <- sun_detect(flicker) # Nothing detected
e <- cavity_detect(flicker, sun = s)
e
## # A tibble: 217 × 12
## date start end length_hrs location
## <date> <dttm> <dttm> <dbl> <chr>
## 1 2011-06-17 2011-06-17 00:00:50 2011-06-17 03:52:50 3.87 in
## 2 2011-06-17 2011-06-17 03:54:50 2011-06-17 03:54:50 0 in_ambig
## 3 2011-06-17 2011-06-17 03:56:50 2011-06-17 03:58:50 0.0333 ambig
## 4 2011-06-17 2011-06-17 04:00:50 2011-06-17 04:00:50 0 out_ambig
## 5 2011-06-17 2011-06-17 04:02:50 2011-06-17 04:02:50 0 ambig
## 6 2011-06-17 2011-06-17 04:04:50 2011-06-17 04:04:50 0 in_ambig
## 7 2011-06-17 2011-06-17 04:06:50 2011-06-17 04:06:50 0 out_ambig
## 8 2011-06-17 2011-06-17 04:08:50 2011-06-17 04:08:50 0 ambig
## 9 2011-06-17 2011-06-17 04:10:50 2011-06-17 05:06:50 0.933 out
## 10 2011-06-17 2011-06-17 05:08:50 2011-06-17 05:08:50 0 ambig
## # … with 207 more rows, and 7 more variables: offset_applied <dbl>, lon <dbl>,
## # lat <dbl>, thresh_dark <dbl>, thresh_light <dbl>, ambig_dark <dbl>,
## # ambig_light <dbl>
Let’s see how these assignments match the patterns we see
cavity_plot(data = flicker, cavity = e)
You data must be in a data frame with the columns called time
and
light
.
time
must be in adate/time
formatlight
must be a number, representing light levels in lux (low = dark, high = light)
For example:
## # A tibble: 3,600 × 2
## time light
## <dttm> <dbl>
## 1 2011-06-17 08:00:50 0
## 2 2011-06-17 08:02:50 0
## 3 2011-06-17 08:04:50 0
## 4 2011-06-17 08:06:50 0
## 5 2011-06-17 08:08:50 0
## 6 2011-06-17 08:10:50 0
## 7 2011-06-17 08:12:50 0
## 8 2011-06-17 08:14:50 0
## 9 2011-06-17 08:16:50 0
## 10 2011-06-17 08:18:50 0
## # … with 3,590 more rows
Consider using the lubridate
package to format your times
Most geolocator data is in the UTC timezone, and although previous versions of cavityuse recommended converting your data to your the timezone of your location (non-daylight savings), I now recommend keeping it in UTC. cavityuse will apply a timezone offset to your data according to the location.
This means that the time output by cavityuse will be in UTC according to
R, however it will actually have had an offset applied (noted in the new
column tz_offset
). This just makes things simpler.
cavityuse
functions require coordinates in order to more efficiently
detect sunrise/sunset times, but also to estimate sunrise/sunset when
they are not detected in the data.
You can supply coordinates in one of two ways.
- You can have
lon
andlat
columns, indicating the decimal coordinates for your location either in your data
## # A tibble: 3,600 × 4
## time light lon lat
## <dttm> <dbl> <dbl> <dbl>
## 1 2011-06-17 08:00:50 0 -120. 50.7
## 2 2011-06-17 08:02:50 0 -120. 50.7
## 3 2011-06-17 08:04:50 0 -120. 50.7
## 4 2011-06-17 08:06:50 0 -120. 50.7
## 5 2011-06-17 08:08:50 0 -120. 50.7
## 6 2011-06-17 08:10:50 0 -120. 50.7
## 7 2011-06-17 08:12:50 0 -120. 50.7
## 8 2011-06-17 08:14:50 0 -120. 50.7
## 9 2011-06-17 08:16:50 0 -120. 50.7
## 10 2011-06-17 08:18:50 0 -120. 50.7
## # … with 3,590 more rows
- You can have a separate variable that you supply to each function
(order matters, and must be
lon
,lat
):
sun_times(data, loc = c(-120.3408, 50.67611))
Right now, cavityuse
is limited to the follow scenarios:
- No big changes in location (i.e. No migration) Changes in
location can interfere with how
cavityuse
assigns activity based on sunrise/sunset times which are inferred from lon/lat (this may change in the future). Minor migratory changes can be accommodated, and larger ones can be somewhat handled by splitting the data by location (different lat/lons) and applyingcavity_detect()
to each set of locations. But this isn’t perfect. - No extreme latitudes Because of the way
cavityuse
detects sunrise and sunset, extremely latitudes may result in unpredicatable behaviour (this should hopefully be fixed in the future) - Animals which use cavities at night, must normally enter their cavity before it gets dark and exit after it gets light With out the ability to detect sunrise/sunset it is impossible to determine cavityuse at night
Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.