https://github.com/steffilazerte/cavityuse
An R package for detecting cavity use from geolocator data
https://github.com/steffilazerte/cavityuse
animal-behaviour animals biology data geolocator r
Last synced: about 1 year ago
JSON representation
An R package for detecting cavity use from geolocator data
- Host: GitHub
- URL: https://github.com/steffilazerte/cavityuse
- Owner: steffilazerte
- License: gpl-3.0
- Created: 2018-08-07T20:32:12.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2022-08-04T17:05:19.000Z (almost 4 years ago)
- Last Synced: 2025-03-30T03:01:46.724Z (about 1 year ago)
- Topics: animal-behaviour, animals, biology, data, geolocator, r
- Language: R
- Homepage: https://steffilazerte.github.io/cavityuse
- Size: 1.8 MB
- Stars: 6
- Watchers: 1
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.Rmd
- License: LICENSE
Awesome Lists containing this project
README
---
output: github_document
---
[](https://github.com/steffilazerte/cavityuse/actions)
[](https://codecov.io/gh/steffilazerte/cavityuse)
# cavityuse
_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.)
```{r, include = FALSE}
knitr::opts_chunk$set(fig.path = "man/figures/", out.width = "100%",
fig.asp = 0.5, fig.width = 10)
```
## Installing `cavityuse`
You can install `cavityuse` directly from my R-Universe:
```{r, eval = FALSE}
install.packages("cavityuse",
repos = c("https://steffilazerte.r-universe.dev",
"https://cloud.r-project.org"))
```
## Getting started
Load the package
```{r}
library(cavityuse)
```
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:
```{r}
cavity_plot(calib)
```
Look for any sunrise/sunset events in your geolocator data
```{r}
s <- sun_detect(calib)
s
```
Let's see what these look like
```{r}
cavity_plot(data = calib, sun = s, days = 1)
```
Now let's move on to the `flicker` data set:
```{r}
cavity_plot(flicker)
s <- sun_detect(flicker) # Nothing detected
e <- cavity_detect(flicker, sun = s)
e
```
Let's see how these assignments match the patterns we see
```{r}
cavity_plot(data = flicker, cavity = e)
```
## With your own data
You data must be in a data frame with the columns called `time` and `light`.
- `time` must be in a `date/time` format
- `light` must be a number, representing light levels in lux (low = dark, high = light)
For example:
```{r, echo = FALSE}
dplyr::select(flicker, time, light)
```
Consider using the [`lubridate`](https://lubridate.tidyverse.org/) package to format your times
### Timezones
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.
### Coordinates
`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` and `lat` columns, indicating the decimal coordinates for your location either in your data
```{r, echo = FALSE}
dplyr::select(flicker, time, light, lon, lat)
```
- You can have a separate variable that you supply to each function (order matters, and must be `lon`, `lat`):
```{r, eval = FALSE}
sun_times(data, loc = c(-120.3408, 50.67611))
```
## Limitations
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 applying `cavity_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](CONDUCT.md). By participating in this project you agree to abide by its terms.