Cyclical time points

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().

Usage

cyclical_time(
  data,
  chronon = time_chronon(data),
  cycle = time_cycle(data),
  discrete = TRUE,
  calendar = time_calendar(data)
)

Arguments

data

Input data to convert to cyclical time. Can be:

• Numeric values (interpreted as chronons, 1-indexed)

• Character strings (parsed as dates/times)

• Date or POSIXct objects

• Other time objects

chronon

A time granule representing the chronon (finest indivisible time granule), evaluated in the context of calendar. Use unquoted expressions like day(1L) or month(1L). Chronons from a specific calendar can also be used (e.g. cal_isoweek$day(1L)).

cycle

A time granule representing the cycle (coarser time granule that defines the period), evaluated in the context of calendar. Use unquoted expressions like week(1L) or year(1L).

discrete

Logical. If TRUE (default), returns integer positions within the cycle (discrete time model). If FALSE, returns fractional positions allowing representation of fractional time chronons (continuous time model).

calendar

Calendar system used to evaluate chronon and cycle. Defaults to time_calendar(data) for existing time objects. Common options include cal_gregorian and cal_isoweek.

Value

A mixtime time vector containing an mt_cyclical vector.

See also

• 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

Examples

# Day of week (1-7, Monday = 1)
cyclical_time(
  Sys.Date(),
  chronon = day(1L),
  cycle = week(1L),
  calendar = cal_isoweek
)
#> <mixtime[1]>
#> [1] Thu

# Month of year (1-12)
cyclical_time(
  Sys.Date(),
  chronon = month(1L),
  cycle = year(1L)
)
#> <mixtime[1]>
#> [1] May

# Discrete vs continuous time
# yearweek(x) is linear_time(x, chronon = day(1L), cycle = week(1L), calendar = cal_isoweek)
yearweek(Sys.time(), discrete = TRUE)
#> <mixtime[1]>
#> [1] 2026 W19
yearweek(Sys.time(), discrete = FALSE)
#> <mixtime[1]>
#> [1] 2026 W19 52.5%

# Day of month with Gregorian calendar
cyclical_time(
  Sys.Date(),
  chronon = day(1L),
  cycle = month(1L),
  calendar = cal_gregorian
)
#> <mixtime[1]>
#> [1] D07

# Hours, minutes, and seconds
cyclical_time(
  Sys.time(),
  chronon = second(1L),
  cycle = day(1L)
)
#> <mixtime[1]>
#> [1] 16:10:42