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

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

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

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)
#>          date level                time
#> 1  2016-01-01     1 2016-01-01 02:06:57
#> 2  2016-01-01     2 2016-01-01 14:31:31
#> 3  2016-01-02     1 2016-01-02 02:07:27
#> 4  2016-01-02     2 2016-01-02 14:31:57
#> 5  2016-01-03     1 2016-01-03 02:07:57
#> 6  2016-01-03     2 2016-01-03 14:32:22
#> 7  2016-01-04     1 2016-01-04 02:08:28
#> 8  2016-01-04     2 2016-01-04 14:32:47
#> 9  2016-01-05     1 2016-01-05 02:08:58
#> 10 2016-01-05     2 2016-01-05 14:33:11
#> 11 2016-01-06     1 2016-01-06 02:09:27
#> 12 2016-01-06     2 2016-01-06 14:33:35
#> 13 2016-01-07     1 2016-01-07 02:09:57
#> 14 2016-01-07     2 2016-01-07 14:33:58
#> 15 2016-01-08     1 2016-01-08 02:10:26
#> 16 2016-01-08     2 2016-01-08 14:34:20
#> 17 2016-01-09     1 2016-01-09 02:10:55
#> 18 2016-01-09     2 2016-01-09 14:34:42
#> 19 2016-01-10     1 2016-01-10 02:11:24
#> 20 2016-01-10     2 2016-01-10 14:35:03

#### 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")
                   )
#>                     x1                  x2     col
#> 1  2016-01-01 00:00:00 2016-01-01 00:00:00   white
#> 2  2016-01-01 00:00:00 2016-01-01 02:06:57 dimgrey
#> 3  2016-01-01 02:06:57 2016-01-01 14:31:31   white
#> 4  2016-01-01 14:31:31 2016-01-02 02:07:27 dimgrey
#> 5  2016-01-02 02:07:27 2016-01-02 14:31:57   white
#> 6  2016-01-02 14:31:57 2016-01-03 02:07:57 dimgrey
#> 7  2016-01-03 02:07:57 2016-01-03 14:32:22   white
#> 8  2016-01-03 14:32:22 2016-01-04 02:08:28 dimgrey
#> 9  2016-01-04 02:08:28 2016-01-04 14:32:47   white
#> 10 2016-01-04 14:32:47 2016-01-05 02:08:58 dimgrey
#> 11 2016-01-05 02:08:58 2016-01-05 14:33:11   white
#> 12 2016-01-05 14:33:11 2016-01-06 02:09:27 dimgrey
#> 13 2016-01-06 02:09:27 2016-01-06 14:33:35   white
#> 14 2016-01-06 14:33:35 2016-01-07 02:09:57 dimgrey
#> 15 2016-01-07 02:09:57 2016-01-07 14:33:58   white
#> 16 2016-01-07 14:33:58 2016-01-08 02:10:26 dimgrey
#> 17 2016-01-08 02:10:26 2016-01-08 14:34:20   white
#> 18 2016-01-08 14:34:20 2016-01-09 02:10:55 dimgrey
#> 19 2016-01-09 02:10:55 2016-01-09 14:34:42   white
#> 20 2016-01-09 14:34:42 2016-01-10 00:00:00 dimgrey
#> 21 2016-01-10 00:00:00 2016-01-10 00:00:00   white

#### 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)
#>          date level                time
#> 1  2016-01-01     1 2016-01-01 02:06:57
#> 2  2016-01-01     2 2016-01-01 14:31:31
#> 3  2016-01-02     1 2016-01-02 02:07:27
#> 4  2016-01-02     2 2016-01-02 14:31:57
#> 5  2016-01-03     1 2016-01-03 02:07:57
#> 6  2016-01-03     2 2016-01-03 14:32:22
#> 7  2016-01-04     1 2016-01-04 02:08:28
#> 8  2016-01-04     2 2016-01-04 14:32:47
#> 9  2016-01-05     1 2016-01-05 02:08:58
#> 10 2016-01-05     2 2016-01-05 14:33:11
#> 11 2016-01-06     1 2016-01-06 02:09:27
#> 12 2016-01-06     2 2016-01-06 14:33:35
#> 13 2016-01-07     1 2016-01-07 02:09:57
#> 14 2016-01-07     2 2016-01-07 14:33:58
#> 15 2016-01-08     1 2016-01-08 02:10:26
#> 16 2016-01-08     2 2016-01-08 14:34:20
#> 17 2016-01-09     1 2016-01-09 02:10:55
#> 18 2016-01-09     2 2016-01-09 14:34:42
#> 19 2016-01-10     1 2016-01-10 02:11:24
#> 20 2016-01-10     2 2016-01-10 14:35:03