R/sequence.R

Defines functions `seq.mixtime::mt_time` `seq.mixtime::mixtime`

#' Generate sequences of mixtime values
#'
#' Create regular sequences of time values. This method handles both linear
#' time sequences (dates, date-times) and cyclical time sequences (day of week,
#' month of year).
#'
#' @param from Starting value of the sequence.
#' @param to End value of the sequence (if provided).
#' @param by Increment of the sequence. Can be:
#'   * A numeric for the number of time chronons
#'   * A character string specifying the interval (e.g., "1 day", "2 weeks",
#'     "1 month", "1 year")
#'   * A time granule object created with time unit functions (e.g., `cal_gregorian$year(1L)`,
#'     `cal_gregorian$month(1L)`, `cal_gregorian$day(1L)`)
#'   * A time [duration()] object (e.g., `years(1L)`, `months(1L)`, `days(1L)`)
#' @param length.out Desired length of the sequence (alternative to `to`).
#' @param along.with Take the length from this argument (alternative to `length.out`).
#' @param on_invalid How to handle time points that don't exist, either
#'   because they overflow the cycle when using a `by` argument with different
#'   time granule than the sequence chronon, or because they fall in the local
#'   time skipped when daylight saving starts. Defaults to the
#'   `mixtime.on_invalid` option, or `"clamp"` if it isn't set. Options are:
#'   * `"clamp"`: Reduce the overflowing component to its last valid
#'     value, preserving finer components (e.g., the time of day). A skipped
#'     local time moves back by the size of the gap (02:30 becomes 01:30)
#'   * `"previous"`: Use the end of the cycle, so finer components are not
#'     preserved. For discrete time this is the last chronon within the cycle;
#'     for continuous time it is the end of that chronon, the same instant as
#'     `"next"`. A skipped local time becomes the end of the valid time before
#'     the gap (01:59:59)
#'   * `"next"`: Use the start of the following cycle, so finer components are
#'     not preserved. A skipped local time becomes the start of the valid time
#'     after the gap (03:00)
#'   * `"overflow"`: Allow time points to overflow into the next cycle. A
#'     skipped local time moves forward by the size of the gap (02:30 becomes
#'     03:30)
#'   * `"reject"`: Return `NA` with a warning
#'   * `"error"`: Throw an error
#'
#'   This is relevant when the starting time point has an offset that doesn't
#'   exist in all cycles. For example, starting on day 31 with `by = "1 month"`
#'   will overflow in months with fewer than 31 days (e.g., February). With
#'   `"clamp"`, these will be adjusted to the last day of the month (e.g.,
#'   Feb 28/29). With `"next"`, they move to the first day of the next month,
#'   and with `"overflow"`, the extra days carry into the next month.
#'
#'   If neither `on_invalid` nor the `mixtime.on_invalid` option is set and
#'   overflow occurs, a warning is issued with the default `"clamp"` behavior
#'   applied. See [time_shift()] for shifting
#'   time points with the same options.
#' @param ... Additional arguments passed to the underlying sequence method.
#'
#' @return A mixtime vector containing the sequence.
#'
#' @details
#' For linear time types (Date, POSIXct, yearmonth, etc.), sequences progress
#' forward or backward in time. Located cyclical time (e.g.
#' `month_of_year(yearmonth("2024-11"))`) progresses through time too, so its
#' positions wrap around the cycle.
#'
#' Underspecified cyclical time (e.g. `month_of_year(11)`, see
#' [mt_cyclical_free-arithmetic]) follows the rules of `x + by`: positions in
#' cycles of a fixed length wrap around (a `length.out` sequence of months
#' continues from December to January), while cycles of variable length (e.g.
#' [day_of_month()]) can't be sequenced until located with [time_compose()].
#' Between `from` and `to`, the sequence runs linearly within one cycle, so
#' `seq(month_of_year(11), month_of_year(2))` counts down from November to
#' February.
#'
#' Each time point is `from` (or `to`, if `from` is missing) shifted by a whole
#' number of `by` steps, matching `from + duration(k, by)`. For time-zone-aware times, steps of a day or
#' longer keep the local clock time, while shorter steps (e.g. hours) are real
#' time across daylight saving changes.
#'
#' @examples
#' # Linear time sequences with integer by
#' seq(yearmonth("2020 Jan"), yearmonth("2020 Dec"))
#' seq(yearquarter("2020 Q1"), length.out = 5, by = 3)
#'
#' # Linear time sequences with string intervals
#' seq(date("2020-01-01"), date("2020-12-31"), by = "1 month")
#' seq(yearmonth("2020 Jan"), yearmonth("2025 Jan"), by = "1 year")
#' seq(date("2020-01-01"), length.out = 10, by = "2 weeks")
#'
#' # Linear time sequences incrementing by time granules
#' seq(yearmonth("2020 Jan"), yearmonth(("2020 Dec")), by = cal_gregorian$month(2L))
#' seq(date("2020-01-01"), length.out = 5, by = cal_gregorian$year(1L))
#' seq(date("2020-01-01"), date("2020-01-31"), by = cal_gregorian$day(7L))
#'
#' # Handling invalid dates with on_invalid
#' seq(date("2020-01-31"), length.out = 3, by = "1 month")  # warns, uses clamp
#' seq(date("2020-01-31"), length.out = 3, by = "1 month", on_invalid = "clamp")
#' seq(date("2020-01-31"), length.out = 3, by = "1 month", on_invalid = "next")
#' seq(date("2020-01-31"), length.out = 3, by = "1 month", on_invalid = "overflow")
#'
#' # Cyclical time sequences
#' seq(month_of_year(1L), month_of_year(12L))
#' seq(day_of_week(1L), day_of_week(7L), by = 1)
#' seq(month_of_year(11L), by = "1 month", length.out = 4)
#'
#' @rdname seq.mixtime
#' @aliases seq.mixtime
#' @method seq mixtime::mixtime
#' @export
`seq.mixtime::mixtime` <- function(...) {
  # Strip mixtime vecvec wrapper
  arg <- lapply(
    rlang::list2(...),
    function(x) if (is_mixtime(x)) vecvec::unvecvec(x) else x
  )

  # Call seq method with bare vectors
  new_mixtime(rlang::exec(seq, !!!arg))
}

#' @rdname seq.mixtime
#' @method seq mixtime::mt_time
#' @export
`seq.mixtime::mt_time` <- function(
  from,
  to,
  by,
  length.out = NULL,
  along.with = NULL,
  on_invalid = getOption("mixtime.on_invalid", "clamp"),
  ...
) {
  if (!is.null(along.with)) {
    length.out <- length(along.with)
  } else if (!is.null(length.out)) {
    if (length(length.out) != 1L) {
      cli::cli_abort("{.arg length.out} must be of length 1.")
    }
    length.out <- ceiling(length.out)
  }

  missing_from <- missing(from)
  missing_to <- missing(to)
  missing_by <- missing(by)

  n_provided <- sum(!missing_from, !missing_to, !is.null(length.out))
  if (missing_by && n_provided < 2L) {
    cli::cli_abort(
      "When {.arg by} is missing, at least two of {.arg from}, {.arg to}, or {.arg length.out} must be specified."
    )
  }
  if (!missing_by && n_provided != 2L) {
    cli::cli_abort(
      "When {.arg by} is provided, exactly two of {.arg from}, {.arg to}, or {.arg length.out} must be specified."
    )
  }

  ptype <- if (missing_from) to else from
  # Sequence chronon
  chronon <- chronon_glb(ptype)

  # Check that from and to have the same time classes
  if (!missing_from && !missing_to) {
    to_chronon <- chronon_glb(to)
    if (!granule_identical(chronon, to_chronon)) {
      cli::cli_abort(c(
        "Incompatible time chronons in {.fn seq}.",
        "i" = "{.arg from} has {.cls {time_granule_label(chronon)}} chronons.",
        "i" = "{.arg to} has {.cls {time_granule_label(to_chronon)}} chronons.",
        "x" = "Which time points of the sequence are within {.arg to} is temporally indeterminate.",
        "i" = "Convert {.arg from} and {.arg to} to the same chronon (e.g. {.code seq(yearmonth(from), yearmonth(to))})."
      ), call = NULL)
    }
  }

  if (missing_by) {
    arg <- list(length.out = length.out)
    if (!missing_from) {
      arg$from <- as.numeric(vec_data(from))
    }
    if (!missing_to) {
      arg$to <- as.numeric(vec_data(to))
    }
    return(vec_restore(rlang::exec(seq.int, !!!arg), ptype))
  }

  # Allow duration input for by, but convert to granule
  if (length(by) != 1L) {
    cli::cli_abort("{.var by} must be a single time duration", call. = FALSE)
  }
  if (time_is_duration(by)) {
    by_size <- as.numeric(vec_data(by))
    by <- attr(by, "chronon")
    by@n <- by@n * by_size
  }

  # Parse `by` argument
  if (is.character(by)) {
    by <- parse_time_unit(by)
  }
  # Numeric `by` uses chronon
  if (is.numeric(by) && !S7_inherits(by, mt_unit)) {
    by <- S7::set_props(chronon, n = by)
  }

  # Inherit granule properties from `by` if not given in `chronon` granule
  by <- granule_inherit_props(by, chronon)
  # A negative `by` steps backwards by whole units of `by`
  step <- if (by@n < 0) -1L else 1L
  # Shift by multiples of `by`'s single unit, as `+` does (`months(18L)` is
  # 18 months, not one 18-month window). Calendar shifts add to the unit's
  # count after decomposing the anchor once, which only matches repeated
  # shifts of a multi-unit `by` window when its size divides the calendar
  # cycle (e.g. 18 months drift against years).
  by_n <- abs(by@n)
  by@n <- 1L

  # Warn when clamping by default, unless the default was chosen with the
  # `mixtime.on_invalid` option
  missing_on_invalid <- missing(on_invalid) &&
    is.null(getOption("mixtime.on_invalid"))
  check_on_invalid(on_invalid)

  # Each time point is shifted from an anchor by a whole number of `by` units
  # (`anchor + duration(k, by)`), rather than from the previous time point.
  # The anchor is `from`, or `to` (right aligned) if `from` is missing.
  anchor <- as.numeric(vec_data(ptype))
  if (!missing_to) {
    to <- as.numeric(vec_data(to))
  }
  local_chronon <- chronon_in_context(chronon, by)
  k <- if (missing_from) {
    step * (seq_len(length.out) - length.out)
  } else if (missing_to) {
    step * (seq_len(length.out) - 1L)
  } else if (chronon_shift_is_exact(local_chronon, by)) {
    # Whole `by` steps of real time from `from` to `to`
    d <- chronon_to_utc(chronon, to) - chronon_to_utc(chronon, anchor)
    d <- d / (chronon_fixed_seconds(by) * by_n)
    seq.int(0L, step * floor_ulp(step * d), by = step)
  } else {
    # Whole units of the local calendar from `from` to `to`, found by
    # shifting `to` left by `from`'s offset into its unit. A `by` boundary
    # (e.g. "start of month") is defined on the local wall clock of `by`'s
    # context, the same convention `chronon_parts()` uses.
    local <- chronon_to_local(
      local_chronon,
      chronon_convert_impl(c(anchor, to), chronon, local_chronon, discrete = FALSE)
    )
    from_divmod <- chronon_divmod(chronon, by, local[1L])
    to_divmod <- chronon_divmod(chronon, by, local[2L] - from_divmod$mod)
    # Stepping backwards, round up to stay at or after `to`
    to_div <- to_divmod$div + (step < 0 & to_divmod$mod != 0)
    # Whole `by` steps within those units
    n_steps <- floor(step * (to_div - from_divmod$div) / by_n)
    seq.int(0L, step * n_steps, by = step)
  }

  shifted <- chronon_shift(
    chronon,
    anchor,
    by,
    k * by_n,
    on_invalid,
    discrete = is.integer(ptype)
  )
  res <- shifted$value

  if (missing_on_invalid && any(shifted$invalid & !shifted$skipped)) {
    cli::cli_warn(c(
      "Some time points in the sequence fall past the end of a shorter {unit_name(by, 1L)}.",
      "!" = "Clamping them to the last valid time point in that {unit_name(by, 1L)}, {.code on_invalid = \"clamp\"} (the default).",
      "i" = "Specify {.arg on_invalid}, or set the {.code mixtime.on_invalid} option, to suppress this warning."
    ))
  }
  if (missing_on_invalid && any(shifted$skipped)) {
    n_skipped <- sum(shifted$skipped)
    cli::cli_warn(c(
      "{n_skipped} time point{?s} in the sequence {?falls/fall} in local time skipped by a time zone change (e.g. when daylight saving starts).",
      "!" = "Moving {cli::qty(n_skipped)}{?it/them} back by the size of the gap, {.code on_invalid = \"clamp\"} (the default).",
      "i" = "Specify {.arg on_invalid}, or set the {.code mixtime.on_invalid} option, to suppress this warning."
    ))
  }
  signal_invalid(shifted$invalid, on_invalid)

  if (!missing_from && !missing_to) {
    # A local time that doesn't exist can move forward, past `to`
    past <- step * (res - to) > 8 * .Machine$double.eps * pmax(abs(to), 1)
    res <- res[!(past %in% TRUE)]
  }

  # Restore integer type for discrete time input, rounding like `+` does
  if (is.integer(ptype)) res <- as.integer(round(res))

  vec_restore(res, ptype)
}

# #' @rdname seq.mixtime
# #' @export
# seq.mt_cyclical <- function(from, to, by, length.out = NULL, along.with = NULL, ...) {
#   if (!is.null(along.with)) {
#     length.out <- length(along.with)
#   }
#   else if (!is.null(length.out)) {
#     if (length(length.out) != 1L)
#       stop(sprintf("'%s' must be of length 1", length.out))
#     length.out <- ceiling(length.out)
#   }

#   # Capture extra arguments
#   arg <- rlang::list2(...)
#   if (!missing(by)) arg$by <- by
#   if (!is.null(length.out)) arg$length.out <- length.out
#   # NB: Passing along.with = NULL to seq.int causes an overflow in R
#   if (!is.null(along.with)) arg$along.with <- along.with

#   # Parse `by` argument
#   if (is.character(arg$by)) arg$by <- parse_time_unit(arg$by)

#   # Convert mt_cyclical to numeric for seq() method
#   if (!missing(from) && inherits(from, "mt_cyclical")) {
#     ptype <- from
#     arg$from <- from@n
#   }
#   if (!missing(to) && inherits(to, "mt_cyclical")) {
#     arg$to <- vctrs::vec_data(to)
#     if (!is.null(arg$from)) {
#       # Require compatible cyclical time objects for from:to
#       vec_assert(to, from)
#     } else {
#       ptype <- to
#     }
#   }

#   # Cyclical period
#   period <- chronon_cardinality(attr(ptype, "chronon"), attr(ptype, "cycles")[[1L]])

#   # Adjust from:to for looping around cycles
#   if (!is.null(arg$to) && !is.null(arg$from)) {
#     if (arg$by%||%1 > 0 && to < from) {
#       arg$to <- arg$to + period
#     } else if (to > from && arg$by%||%1 < 0) {
#       arg$to <- arg$to - period
#     }
#   }

#   # Convert `by` to match `ptype` units
#   if (!is.null(arg$by) && S7_inherits(arg$by, mt_unit)) {
#     arg$by <- chronon_cardinality(time_chronon(ptype), arg$by)
#   }

#   # Generate linear sequence
#   res <- rlang::inject(seq.int(!!!arg))

#   # Compute cyclical component
#   res <- res %% period

#   # Restore integer type for discrete time input
#   if (is.integer(ptype)) res <- as.integer(res)

#   # Restore cyclical time attributes
#   vec_restore(res, ptype)
# }

Try the mixtime package in your browser

Any scripts or data that you put into this service are public.

mixtime documentation built on Nov. 18, 2026, 5:08 p.m.