cavity_detect: Summarize light into bouts of cavity use

View source: R/cavity.R

cavity_detectR Documentation

Summarize light into bouts of cavity use

Description

Summarize light into bouts of cavity use

Usage

cavity_detect(
  data,
  sun = NULL,
  loc = NULL,
  n = 2,
  thresh_dark = 1,
  thresh_light = 60,
  ambig_dark = 10,
  ambig_light = 25,
  gap_cutoff = 10
)

Arguments

data

Data frame. Raw light data. Requires two columns: "time" and "light"

sun

Data frame. Detected sunrise and sunset events, output of sun_detect

loc

Numeric vector. Longitude and Latitude of the observations (if not in the data, this must be provided).

n

Numeric. Number of points before and after a given observation to use in the calculation of cavity use (similar to a running mean)

thresh_dark

Numeric. Light threshold for "in" (see details)

thresh_light

Numeric. Light threshold for "out" (see details)

ambig_dark

Numeric. Light threshold for "in_ambig" (see details)

ambig_light

Numeric. Light threshold for "out_ambig" (see details)

gap_cutoff

Numeric. Minimum number of sequential missing observations defining a "gap" in the data record

Details

Thresholds This function assigns points to four categories based on their light intensity: "in", "out", "in_ambig", "out_ambig", "ambig". The thresholds are used to determine which category a point is assigned to.

  • in: Light <= thresh_dark

  • out: Light >= thresh_light

  • in_ambig: thresh_dark < Light <= ambig_dark

  • out_ambig: thresh_light > Light >= ambig_light

  • ambig: ambig_dark < Light < ambig_light

These points are then smoothed into bouts of cavity use. The argument n, determines how many points before and after a given point, should be used to influence the final cavity use designation. For example, an "ambig" point, surrounded by "in" points will be assigned as part of an "in" cavity use bout. However, 3 "ambig" points in a row will result in an "ambig" bout. How many points to smooth over is affected by n. The argument gap_cutoff determines the maximum number of minutes between observations allowed before a bout is split and a gap in the data is introduced.

To detect cavity use in the evening and overnight, this function relies on detections of sunrise and sunset (detected with sun_detect). If you really don't want to use this, assign an empty data frame, but be aware that your overnight locations will always be defined as "in", which, in many cases would be incorrect. sun = data.frame()

Value

A data frame summarizing light into bouts of cavity use, each with a start, end, and location designation.

Examples


# Single individual
s <- sun_detect(wtsp)
e <- cavity_detect(wtsp, sun = s)

cavity_plot(wtsp, cavity = e, sun = s)

# Use `map` from purrr package for multiple individuals
library(dplyr)
library(tidyr)
library(purrr)

d <- flicker_mult %>%
  nest(-id, .key = "light_data") %>%
  mutate(s = map(light_data, ~sun_detect(.)),
         e = map2(light_data, s, ~cavity_detect(.x, sun = .y)))
d

cavity_plot(d$light_data[[1]], cavity = d$e[[1]], sun = d$s[[1]])
cavity_plot(d$light_data[[2]], cavity = d$e[[2]], sun = d$s[[2]])



steffilazerte/cavityuse documentation built on Aug. 4, 2022, 11:22 p.m.