photoperiod {LightLogR} | R Documentation |
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)
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 |
tz |
Timezone of the data. Expects a |
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 |
dataset |
A light logger dataset. Expects a |
Datetime.colname |
column name that contains the datetime. Defaults to
|
overwrite |
Logical scalar. If |
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.
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 classDate
-
tz
with the timezone of the output, stored as classcharacter
-
lat
andlon
with the latitude and longitude of the location, stored as classnumeric
-
solar.angle
with the negative solar depression angle, i.e. the sun elevation above the horizon. stored as classnumeric
-
dawn
anddusk
with the calculated datetimes, stored as classPOSIXct
-
photoperiod
with the calculated photoperiod, stored as classdifftime
.
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
See Also
Other photoperiod:
gg_photoperiod()
Examples
#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)