View source: R/cyclical_time.R
| cyclical_time | R Documentation |
cyclical_time() creates a vector of cyclical time points representing
positions within repeating cycles. This function is useful for creating custom
cyclical time representations that aren't covered by the convenience functions
like day_of_week() or month_of_year().
cyclical_time(
data,
chronon = time_chronon(data),
cycle = time_cycle(data),
discrete = TRUE,
calendar = time_calendar(data)
)
data |
Input data to convert to cyclical time. Can be:
|
chronon |
A time granule representing the chronon (finest
indivisible time granule), evaluated in the context of |
cycle |
A time granule representing the cycle (coarser time granule
that defines the period), evaluated in the context of |
discrete |
Logical. If |
calendar |
Calendar system used to evaluate |
A mixtime time vector of located cyclical time (mt_cyclical),
or underspecified cyclical time (mt_cyclical_free) for numeric data.
A cyclical time point is a position within a cycle, such as March within a year. The cycle it falls in (which year) is its enclosing cycle, and whether that is known gives two types of cyclical time:
Located cyclical time knows its enclosing cycle. It is created from
time points: month_of_year(as.Date("2024-03-15")) is March 2024,
displayed as Mar.
Underspecified cyclical time doesn't. It is created from positions:
month_of_year(3) is March of any year.
Both compare and sort by their position within the cycle, so
month_of_year(3) == month_of_year(as.Date("2024-03-15")) is TRUE.
They differ in operations that move a position. Located cyclical time moves
its underlying time point, so the result accounts for the enclosing cycle:
adding a day to day_of_month(as.Date(c("2023-02-28", "2024-02-28"))) gives
D01 D29.
Underspecified cyclical time only supports operations that don't need its enclosing cycle, and which those are depends on the cycle's length:
Fixed-length cycles (e.g. months of the year, days of the week) wrap
around: month_of_year(12) + 1 is Jan.
Variable-length cycles (e.g. days of the month or year) can't be
moved: day_of_month(28) + 1 is day 29, or day 1 of a non-leap February,
so it is an error. Positions are only checked against the longest cycle,
so day_of_month(31) is valid but day_of_month(32) is NA.
Locate underspecified cyclical time in a specific enclosing cycle with
time_compose(): adding a day to
time_compose(yearmonth("2024-02"), day_of_month(28)) gives 2024-02-29.
The two types can't be cast into each other.
See mt_cyclical_free-arithmetic and mt_cyclical_free-compare for details.
new_cyclical_time_fn() for creating reusable cyclical time functions
day_of_week(), day_of_month(), day_of_year() for common cyclical representations
month_of_year(), week_of_year() for other cyclical time helpers
cal_gregorian, cal_isoweek for calendar systems
# Day of week (1-7, Monday = 1)
cyclical_time(
Sys.Date(),
chronon = day(1L),
cycle = week(1L),
calendar = cal_isoweek
)
# Month of year (1-12)
cyclical_time(
Sys.Date(),
chronon = month(1L),
cycle = year(1L)
)
# Continuous time (discrete = FALSE) for fractional month of year
cyclical_time(
Sys.Date(),
chronon = month(1L),
cycle = year(1L),
discrete = FALSE
)
# Day of month with Gregorian calendar
cyclical_time(
Sys.Date(),
chronon = day(1L),
cycle = month(1L),
calendar = cal_gregorian
)
# Hours, minutes, and seconds
cyclical_time(
Sys.time(),
chronon = second(1L),
cycle = day(1L)
)
#' # Underspecified cyclical time from positions
month_of_year(c(3, 12)) + 1
try(day_of_month(28) + 1)
time_compose(yearmonth("2024-02"), day_of_month(28)) + days(1)
# Located cyclical time moves with its enclosing cycle
day_of_month(as.Date(c("2023-02-28", "2024-02-28"))) + days(1)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.