photoperiod: Calculate photoperiod and boundary times

Description

A family of functions to extract and add photoperiod information. photoperiod() creates a tibble with the calculated times of dawn and dusk for the given location and date. The function is a convenience wrapper for suntools::crepuscule() to calculate the times of dawn and dusk. By default, civil dawn and dusk are calculated, but the function can be used to calculate other times by changing the solarDep parameter (e.g., 0 for sunrise/sunset, 12 for nautical, and 18 for astronomical).

Taking a light exposure dataset as input, extract_photoperiod() calculates the photoperiods and their boundary times for each unique day in the dataset, given a location and boundary condition (i.e., the solar depression angle). Basically, this is a convenience wrapper for photoperiod() that takes a light logger dataset and extracts unique dates and the time zone from the dataset.

add_photoperiod() adds photoperiod information to a light logger dataset. Beyond the photoperiod information, it will categorize the photoperiod.state as "day" or "night". If overwrite is set to TRUE, the function will overwrite any columns with the same name.

solar_noon() calculates the solar noon for a given location and date. The function is a convenience wrapper for suntools::solarnoon(). The function has no companions like extract_photoperiod() or add_photoperiod(), but will be extended, if there is sufficient interest.

Usage

photoperiod(coordinates, dates, tz, solarDep = 6)
extract_photoperiod(
  dataset,
  coordinates,
  Datetime.colname = Datetime,
  solarDep = 6
)
add_photoperiod(
  dataset,
  coordinates,
  Datetime.colname = Datetime,
  solarDep = 6,
  overwrite = FALSE
)
solar_noon(coordinates, dates, tz)

Value

photoperiod() returns a tibble with the calculated times of dawn and dusk for the given location and date, with the length equal to the dates input parameter . The tibble contains the following columns:

date with the date of the calculation, stored as class Date
tz with the timezone of the output, stored as class character
lat and lon with the latitude and longitude of the location, stored as class numeric
solar.angle with the negative solar depression angle, i.e. the sun elevation above the horizon. stored as class numeric
dawn and dusk with the calculated datetimes, stored as class POSIXct
photoperiod with the calculated photoperiod, stored as class difftime.

extract_photoperiod() returns a tibble of the same structure as photoperiod(), but with a length equal to the number of unique dates in the dataset.

add_photoperiod returns the input dataset with the added photoperiod information. The information is appended with the following columns: dawn, dusk, photoperiod, and photoperiod.state.

solar_noon() returns a tibble with the calculated solar noon

Arguments

coordinates: A two element numeric vector representing the latitude and longitude of the location. Important note: Latitude is the first element and Longitude is the second element.
dates: A date of format Date, or coercible to Date through lubridate::as_date()
tz: Timezone of the data. Expects a character. You can look up the supported timezones with OlsonNames().
solarDep: A numerical value representing the solar depression angle between 90 and -90. This means a value of 6 equals -6 degrees above the horizon. Default is 6, equalling Civil dawn/dusk. Other common values are 12 degrees for Nautical dawn/dusk, 18 degrees for Astronomical dawn/dusk, and 0 degrees for Sunrise/Sunset. Note that the output columns will always be named dawn and dusk, regardless of the solarDep value.
dataset: A light logger dataset. Expects a dataframe. If not imported by LightLogR, take care to choose a sensible variable for the Datetime.colname.
Datetime.colname: column name that contains the datetime. Defaults to "Datetime" which is automatically correct for data imported with LightLogR. Expects a symbol. Needs to be part of the dataset. Must be of type POSIXct.
overwrite: Logical scalar. If TRUE, the function will overwrite any columns with the same name. If FALSE (default), the function will stop if any of the columns already exist in the dataset.

Details

Please note that all functions of the photoperiod family work with one coordinate pair at a time. If you have multiple locations (and multiple time zones), you need to run the function for each location separately. We suggest using a nested dataframe structure, and employ the purrr package to iterate over the locations.

Examples

Run this code

 #example für Tübingen, Germany
 coordinates <- c(48.521637, 9.057645)
 dates <- c("2023-06-01", "2025-08-23")
 tz <- "Europe/Berlin"
 
 #civil dawn/dusk
 photoperiod(coordinates, dates, tz)
 #sunrise/sunset
 photoperiod(coordinates, dates, tz, solarDep = 0)
 #extract_photoperiod
 sample.data.environment |> 
   extract_photoperiod(coordinates)


#add_photoperiod
added_photoperiod <-
 sample.data.environment |>
 add_photoperiod(coordinates)

added_photoperiod |> head()

added_photoperiod |>
  filter_Date(length = "3 days") |>
  gg_days(aes_col = photoperiod.state,
          group = dplyr::consecutive_id(photoperiod.state),
          jco_color = TRUE
          )

added_photoperiod |>
  filter_Date(length = "3 days") |>
  gg_day(aes_col = Id) +
  ggplot2:: geom_rect(
  data = \(x) x |> dplyr::ungroup(Id) |> dplyr::summarize(dawn = mean(dawn) |> hms::as_hms()),
  ggplot2::aes(xmin = 0, xmax = dawn, ymin = -Inf, ymax = Inf),
  alpha = 0.1
  ) +
  ggplot2:: geom_rect(
  data = \(x) x |> dplyr::ungroup(Id) |> dplyr::summarize(dusk = mean(dusk) |> hms::as_hms()),
  ggplot2::aes(xmin = dusk, xmax = 24*60*60, ymin = -Inf, ymax = Inf),
  alpha = 0.1
  )


 added_photoperiod |> dplyr::summarize(dawn = mean(dawn) |> hms::as_hms())

 #solar_noon()
 solar_noon(coordinates, dates, tz)