sun_detect: Detect patterns of sunrise and sunset

In steffilazerte/cavityuse: Detecting Cavity Use From Geolocator Data

Detect patterns of sunrise and sunset

Description

Detects patterns of sunrise and sunset in geolocator data.

Usage

sun_detect(
  data,
  n = 10,
  range = 10,
  cutoff = 0.95,
  loc = NULL,
  local = TRUE,
  window = 3,
  filter_problems = TRUE,
  thresh_dark = 1,
  ambig_dark = 10,
  poly_order = 3,
  max_light = 64
)

Arguments

data	Data frame. Raw light data. Requires two columns: "time" and "light"
n	Numeric. Number of light observations to use when assessing a sunrise/sunset event
range	Numeric. Minimum lux difference between minimum and maximum light levels in sunrise and sunset event
cutoff	Numeric. R-Squared cutoff value to assess the model fit to sunrise and sunset. Higher values are more stringent, lower values are less.
loc	Numeric vector. Longitude and Latitude of the observations (if not in the data, this must be provided).
local	Logical. Restrict data to expect windows of sunrise/sunset based on coordinates (will speed up the function, but may result in problems if sunrise/sunset occur close to midnight)
window	Numeric. Number of hours around expected sunrise/sunset to look for evidence of actual sunrise/sunset. Only applies if 'local = TRUE'.
filter_problems	Logical. Remove problematic sunrise/sunset events? Problematic events are defined as those which are preceded/proceeded by unexpectedly variable light levels (True sunrise/sunset events should only be preceded/proceeded by darkness)
thresh_dark	Numeric. Light levels below which are considered 'dark'
ambig_dark	Numeric. Light levels below which are considered 'darkish'
poly_order	Numeric. Polynomial order for modelling sunrise and sunset. For low resolution data (e.g. >=5min intervals), use 2, for higher resolution data (e.g., <=2min intervals) use 3. Play with this if sunrise/sunsets are consistently missclassified.
max_light	Numeric. Light levels to consider full brightness. Fixes problems with high resolution geolocators that record light into the 1000s

Details

This function looks for sunrise/sunset events by matching n points to a cubic polynomial regression. Events with a high degree of model fit (determined by an R-squared cutoff of cutoff are returned.

Because this essentially fits models to every point in the data, it can be very time consuming. local = TRUE attempts to reduce this time by first filtering the data to blocks of time which should contain sunrise/sunset, based on the coordinates of the data.

Only one sunrise and one sunset event are allowed per day. If filter_problems = TRUE, then sunrise events that are preceded by variable light levels and sunset events proceeded by variable light levels are omitted (before sunrise and after sunset, it should be dark).

Value

Data frame containing sunrise and sunset events

Examples

# Calibration data should have perfect sunrise/sunset event detection
s <- sun_detect(calib)
cavity_plot(calib, sun =s)

# Sunrise/sunset events missed with extra stringent cutoff values
s <- sun_detect(calib, cutoff = 0.9995)
cavity_plot(calib, sun = s)

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