Skip to contents

Linear time helper functions

Source: R/linear_time.R
linear_time_helpers.Rd

Convenience functions for creating common linear time representations. These functions work with different calendar systems and adapt based on the input data's calendar.

Usage

year(data, discrete = TRUE, calendar = time_calendar(data), ...)

yearquarter(data, discrete = TRUE, calendar = time_calendar(data), ...)

yearmonth(data, discrete = TRUE, calendar = time_calendar(data), ...)

yearweek(data, discrete = TRUE, calendar = time_calendar(data), ...)

date(data, discrete = TRUE, calendar = time_calendar(data), ...)

datetime(data, discrete = TRUE, calendar = time_calendar(data), ...)

Arguments

data

A vector of time points (e.g. base::Date, base::POSIXt)

discrete

If TRUE, the number of chronons since Unix epoch that .data falls into is returned as an integer. If FALSE, a fractional number of chronons is returned (analagous to time using a continuous time model).

calendar

A calendar used to evaluate the time units. Defaults to the calendar of the input data. Common options include cal_gregorian and cal_isoweek.

...

Additional arguments for linear_time(), such as tz for timezones.

Value

A mixtime time vector containing an mt_linear vector with chronons matching the function used.

Details

These functions create linear time representations with different chronons and granules:

  • year(): Represents time in whole years. The chronon is one year.

  • yearquarter(): Represents time in quarters, grouped by year. The chronon is one quarter, with years as the granule.

  • yearmonth(): Represents time in months, grouped by year. The chronon is one month, with years as the granule.

  • yearweek(): Represents time in weeks, grouped by year. The chronon is one week, with years as the granule. Defaults to ISO 8601 week calendar.

Calendar flexibility

These functions adapt to the calendar system of the input data. For example:

  • year("2025-12-29") returns a Gregorian year

  • year(yearweek("2025-12-29")) returns an ISO week-based year

You can also explicitly specify a calendar using the calendar argument:

year(yearweek("2025-12-29"), calendar = cal_isoweek)

Custom linear time representations

For more complex time structures, use linear_time() or new_linear_time_fn() to create custom representations with any combination of chronons and granules.

See also

Examples


# Gregorian year
year(Sys.Date())
#> <mixtime[1]>
#> [1] 2026
year(Sys.Date(), discrete = FALSE)
#> <mixtime[1]>
#> [1] 2026 26.6%

# ISO week-based year
year(yearweek(Sys.Date()))
#> <mixtime[1]>
#> [1] 2026

# Year-quarter
yearquarter(Sys.Date())
#> <mixtime[1]>
#> [1] 2026 Q2
yearquarter(Sys.Date(), discrete = FALSE)
#> <mixtime[1]>
#> [1] 2026 Q2 6.3%

# Year-month
yearmonth(Sys.Date())
#> <mixtime[1]>
#> [1] 2026 Apr
yearmonth(Sys.Date(), discrete = FALSE)
#> <mixtime[1]>
#> [1] 2026 Apr 23.3%

# Year-week (ISO 8601)
yearweek(Sys.Date())
#> <mixtime[1]>
#> [1] 2026 W15
yearweek(0:52)
#> <mixtime[53]>
#>  [1] 1970 W01 1970 W02 1970 W03 1970 W04 1970 W05 1970 W06 1970 W07 1970 W08
#>  [9] 1970 W09 1970 W10 1970 W11 1970 W12 1970 W13 1970 W14 1970 W15 1970 W16
#> [17] 1970 W17 1970 W18 1970 W19 1970 W20 1970 W21 1970 W22 1970 W23 1970 W24
#> [25] 1970 W25 1970 W26 1970 W27 1970 W28 1970 W29 1970 W30 1970 W31 1970 W32
#> [33] 1970 W33 1970 W34 1970 W35 1970 W36 1970 W37 1970 W38 1970 W39 1970 W40
#> [41] 1970 W41 1970 W42 1970 W43 1970 W44 1970 W45 1970 W46 1970 W47 1970 W48
#> [49] 1970 W49 1970 W50 1970 W51 1970 W52 1970 W53