add_time_vars: Add Time Variables

In ConSciR: Tools for Conservation Science

Add Time Variables

Description

This function adds multiple time-related variables to a dataframe with a Date column. It creates standard factors such as season, month-year, day-hour, and determines summer/winter. It also allows flexible specification of summer and winter start/end dates, and a custom time period.

Usage

add_time_vars(
  mydata,
  Date = "Date",
  openair_vars = c("seasonyear", "season", "monthyear", "daylight"),
  summer_start = "04-15",
  summer_end = "10-15",
  period_start = NULL,
  period_end = NULL,
  period_label = "Period",
  latitude = 51,
  longitude = -0.5,
  ...
)

Arguments

mydata	A dataframe containing a date/time column labelled "Date" and "Sensor" column.
Date	The name of the date/time column in 'mydata' (default "Date").
openair_vars	Variables from 'openair::cutData()' to add (default includes seasonyear, season, monthyear, daylight).
summer_start	Start date for summer season in "MM-DD" format or full date (default "04-15").
summer_end	End date for summer season in "MM-DD" format or full date (default "10-15").
period_start	Start date of custom period in "MM-DD" format or full date (optional).
period_end	End date of custom period in "MM-DD" format or full date (optional).
period_label	Label to assign for dates within the custom period, e.g. if there is an Exhibition or a property is open/closed to the public (default "Period").
latitude	Latitude for daylight calculations (default 51).
longitude	Longitude for daylight calculations (default -0.5).
...	Additional arguments passed to 'openair::cutData()'.

Details

The variables seasonyear, season, monthyear, and daylight are created using the openair::cutData() function internally and rely on geographic coordinates (latitude, longitude) to calculate daylight status. Be sure openair is installed and loaded for these variables.

Value

A data frame with additional time-related columns appended:

seasonyear

Combined year and season factor created by openair::cutData(); useful for seasonal analyses.

season

Season factor (e.g., Spring, Summer) from openair::cutData().

monthyear

Factor combining month and year, created by openair::cutData() to assist month-based grouping.

daylight

Boolean or factor indicating daylight presence/absence, derived using openair::cutData() with latitude and longitude inputs.

day

Date part of the timestamp, rounded down to day boundary, useful for daily aggregation.

hour

Hour of the day extracted from the datetime.

dayhour

Datetime floored to the hour; useful for hourly time series analysis.

weekday

Weekday name/factor, abbreviated, extracted from the date.

month

Month number and its labelled factor version; useful for calendar-based grouping.

year

Year extracted from the datetime for annual analyses.

DayYear

Date with the current year but month and day taken from the original date; used to assign seasons and periods relative to current year.

Summer

A factor ("Summer" or "Winter") determined by comparison of DayYear with user-defined summer_start and summer_end dates, for custom seasonality modelling.

Period

Character flag identifying whether the date falls within a user-defined custom period (e.g., an exhibition), labelled by period_label. Returns NA if no period defined.

Examples

# mydata file
filepath <- data_file_path("mydata.xlsx")
mydata <- readxl::read_excel(filepath, sheet = "mydata", n_max = 5)

mydata |>
  add_time_vars(period_start = "05-01", period_end = "06-30", period_label = "Exhibition") |>
  dplyr::glimpse()

ConSciR documentation built on Nov. 5, 2025, 5:25 p.m.