seq.mixtime: Generate sequences of mixtime values

seq.mixtime::mixtimeR Documentation

Generate sequences of mixtime values

Description

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

Usage

## S3 method for class ''mixtime::mixtime''
seq(...)

## S3 method for class ''mixtime::mt_time''
seq(
  from,
  to,
  by,
  length.out = NULL,
  along.with = NULL,
  on_invalid = getOption("mixtime.on_invalid", "clamp"),
  ...
)

Arguments

...

Additional arguments passed to the underlying sequence method.

from

Starting value of the sequence.

to

End value of the sequence (if provided).

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

length.out

Desired length of the sequence (alternative to to).

along.with

Take the length from this argument (alternative to length.out).

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.

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.

Value

A mixtime vector containing the sequence.

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)


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