Nothing
#' Linear time function factory
#'
#' `new_linear_time_fn()` creates a linear time function for a specified
#' chronon. A chronon is the smallest indivisible time granule (e.g., days,
#' hours).
#'
#' @param chronon A bare call for a time granule object representing the chronon
#' (e.g., `day(1)`)
#' @param default_calendar A default calendar used to find the time units for
#' conversion if they don't exist in the calendar of the input data (e.g.,
#' `cal_isoweek` for week chronons to work with gregorian calendar inputs).
#'
#' @return A function used to create linear time points with a specific chronon.
#'
#' @examples
#'
#' # Linear time with 1 month granules as the chronon
#' ym <- new_linear_time_fn(month(1L))
#' ym(Sys.Date())
#'
#' # Linear time with 1 day granules as the chronon
#' yd <- new_linear_time_fn(day(1L))
#' yd(Sys.Date())
#'
#' # Linear time with 1 week granules as the chronon, using the ISO week calendar
#' yw <- new_linear_time_fn(week(1L), default_calendar = cal_isoweek)
#' yw(Sys.Date())
#'
#' # Linear time with 1 hour granules as the chronon
#' ymd_h <- new_linear_time_fn(hour(1L))
#' ymd_h(Sys.time())
#'
#' @export
new_linear_time_fn <- function(chronon, default_calendar = cal_gregorian) {
chronon <- rlang::new_quosure(
enexpr(chronon),
env = rlang::as_data_mask(default_calendar)
)
function(
data, discrete = TRUE, calendar = time_calendar(data), ...
) {
# Add tz / loc to chronon
chronon <- quo_add_dots(chronon, ...)
linear_time(
data, chronon = !!chronon, discrete = discrete, calendar = calendar
)
}
}
#' Linear time points
#'
#' `linear_time()` creates a vector of linear time points with a specified
#' chronon (smallest time granule). This function is useful for creating custom
#' time representations that aren't covered by the convenience functions like
#' [yearmonth()] or [yearweek()].
#'
#' @param data Input data to convert to linear time. Can be:
#' - Numeric values (interpreted as chronons since Unix epoch)
#' - Character strings (parsed as dates/times)
#' - Date or POSIXct objects
#' - Other time objects
#' @param chronon A time granule expression representing the chronon (smallest
#' indivisible time granule), evaluated in the context of `calendar`. Use
#' unquoted expressions like `month(1L)` or `hour(1L)`. Chronons from a
#' specific calendar can also be used (e.g. `cal_isoweek$week(1L)`).
#' Defaults to the time chronon of the input `data` (`time_chronon(data)`).
#' @param discrete Logical. If `TRUE` (default), returns integer chronons since
#' Unix epoch (discrete time model). If `FALSE`, returns fractional chronons
#' allowing representation of fractional time granules (continuous time model).
#' @param calendar Calendar system used to evaluate `chronon` and `granules`.
#' Defaults to `time_calendar(data)` for existing time objects. Common options
#' include [cal_gregorian] and [cal_isoweek].
#'
#' @return A `mixtime` time vector containing an `mt_linear` vector.
#'
#' @seealso
#' - [new_linear_time_fn()] for creating reusable linear time functions
#' - [yearmonth()], [yearquarter()], [year()] for Gregorian time representations
#' - [yearweek()] for ISO 8601 week-based time
#' - [cal_gregorian], [cal_isoweek] for calendar systems
#'
#' @examples
#' # Hourly time
#' linear_time(
#' Sys.time(),
#' chronon = hour(1L)
#' )
#'
#' # Monthly time
#' linear_time(
#' Sys.Date(),
#' chronon = month(1L)
#' )
#'
#' # Discrete vs continuous time
#' linear_time(Sys.time(), chronon = day(1L), discrete = TRUE)
#' linear_time(Sys.time(), chronon = day(1L), discrete = FALSE)
#'
#' # ISO week calendar with week-day structure
#' linear_time(
#' Sys.Date(),
#' chronon = day(1L),
#' calendar = cal_isoweek
#' )
#'
#' @export
linear_time <- function(
data, chronon = time_chronon(data), discrete = TRUE,
calendar = time_calendar(data)
) {
# Evaluate chronon and granules with a calendar mask
quo_chronon <- enquo(chronon)
tryCatch({
chronon <- eval_tidy(quo_chronon, data = calendar, env = emptyenv())
}, error = function(e) {
# Special hint for common error of 'week' unit not found in Gregorian calendar
if (e$message == "could not find function \"week\"") {
e$message <- c(
e$message,
"i" = "This error often occurs when trying to use a 'week' chronon without the ISO week calendar.\n",
">" = "Try specifying the calendar explicitly, e.g. `calendar = cal_isoweek`."
)
}
cli::cli_abort(e$message, call = NULL)
})
mixtime(data, chronon = chronon, cycle = NULL, discrete = discrete)
}
#' Linear time helper functions
#'
#' Convenience functions for creating common linear time representations. These
#' functions work with different calendar systems and adapt based on the input
#' data's calendar.
#'
#' @param data A vector of time points (e.g. [base::Date], [base::POSIXt])
#' @param 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).
#' @param 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].
#' @param ... Additional arguments for [linear_time()], such as `tz` for timezones.
#'
#' @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.
#'
#' @section Calendar flexibility:
#' These functions adapt to the calendar system of the input data. For example:
#'
#' - `year(date("2025-12-29"))` returns a Gregorian year
#' - `year(yearweek(date("2025-12-29")))` returns an ISO week-based year
#'
#' You can also explicitly specify a calendar using the `calendar` argument:
#'
#' \preformatted{
#' year(date("2025-12-29"), calendar = cal_isoweek)
#' }
#'
#' @section 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.
#'
#' @return A `mixtime` time vector containing an `mt_linear` vector with chronons matching the function used.
#'
#' @seealso
#' - [linear_time()] for creating custom linear time representations
#' - [new_linear_time_fn()] for creating reusable linear time functions
#' - [cal_gregorian], [cal_isoweek] for calendar systems
#'
#' @examples
#'
#' # Gregorian year
#' year(Sys.Date())
#' year(Sys.Date(), discrete = FALSE)
#'
#' # ISO week-based year
#' year(yearweek(Sys.Date()))
#'
#' # Year-quarter
#' yearquarter(Sys.Date())
#' yearquarter(Sys.Date(), discrete = FALSE)
#'
#' # Year-month
#' yearmonth(Sys.Date())
#' yearmonth(Sys.Date(), discrete = FALSE)
#'
#' # Year-week (ISO 8601)
#' yearweek(Sys.Date())
#' yearweek(0:52)
#'
#' @name linear_time_helpers
#' @export
year <- new_linear_time_fn(
chronon = year(1L)
)
#' @rdname linear_time_helpers
#' @export
yearquarter <- new_linear_time_fn(
chronon = quarter(1L)
)
#' @rdname linear_time_helpers
#' @export
yearmonth <- new_linear_time_fn(
chronon = month(1L)
)
#' @rdname linear_time_helpers
#' @export
yearweek <- new_linear_time_fn(
chronon = week(1L),
default_calendar = cal_isoweek
)
#' @rdname linear_time_helpers
#' @export
date <- new_linear_time_fn(
chronon = day(1L)
)
#' @rdname linear_time_helpers
#' @export
datetime <- new_linear_time_fn(
chronon = second(1L)
)
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.