define_time_blocks: Define time blocks (i.e. diel periods or seasons)

In edwardlavender/prettyGraphics: Pretty Graphics with R

Define time blocks (i.e. diel periods or seasons)

Description

This function defines 'blocks' (i.e., diel periods or seasons) for each day in a time window.

Usage

define_time_blocks(
  t1 = as.POSIXct("2016-01-01", tz = "UTC"),
  t2 = as.POSIXct("2017-01-01", tz = "UTC"),
  type = "diel",
  type_args = list(),
  to_plot = TRUE,
  col = NULL
)

Arguments

t1	The start time, in POSIXct format with the time zone specified.
t2	The end time, in POSIXct format with the time zone specified.
type	A character input specifying the type of block to define. "diel" or "season" are currently supported. "diel" defines a dataframe with date, time and level (1, time of sunrise; 2, time of sunset). "season" defines a dataframe with date, time and level representing seasons.
type_args	A named list of arguments needed to implement type. This is required for type = "diel". A list containing "lon" and "lat" is needed; these arguments are passed to sunriset.
to_plot	A logical input defining whether or not the returned dataframe is to be used as an input for plotting (see add_shading_bar. If so, the function conducts some processing so that the times are defined exactly along the limits provided by t1 and t2. This also adjusts the dataframe returned (see Value).
col	A vector of colours, one for each factor that are added to the dataframe if to_plot = TRUE. For type = "diel", col should specify the colour of day and night and for type = "season", col should specify the colour of winter, spring, summer and autumn (in that order). If col is NULL, colours are chosen by default.

Value

The function returns a dataframe. If to_plot = FALSE, the dataframe contains 3 columns: date, time and level. If type == "diel", levels correspond to day/night; if type == "season", levels correspond to the four seasons. If to_plot = TRUE, x1, x2 and col are returned.

Author(s)

Edward Lavender

Examples

#### Example (1) define diel blocks between two dates
define_time_blocks(t1 = as.POSIXct("2016-01-01", tz = "UTC"),
                   t2 = as.POSIXct("2016-01-10", tz = "UTC"),
                   type = "diel",
                   type_args = list(lon = 56, lat = -5),
                   to_plot = FALSE)

#### Example (2) define diel blocks between two dates to plot
define_time_blocks(t1 = as.POSIXct("2016-01-01", tz = "UTC"),
                   t2 = as.POSIXct("2016-01-10", tz = "UTC"),
                   type = "diel",
                   type_args = list(lon = 56, lat = -5),
                   to_plot = TRUE,
                   col = c("white", "dimgrey")
                   )

#### Example (3) define seasonal blocks between two dates
define_time_blocks(t1 = as.POSIXct("2016-01-01", tz = "UTC"),
                   t2 = as.POSIXct("2016-01-10", tz = "UTC"),
                   type = "diel",
                   type_args = list(lon = 56, lat = -5),
                   to_plot = FALSE)

edwardlavender/prettyGraphics documentation built on Jan. 19, 2025, 2:47 p.m.