mt_unit: Base S7 class for creating new time units

mt_unitR Documentation

Base S7 class for creating new time units

Description

This class is the primitive class for time units, and should be extended from when creating new time units. A new class is typically created with new_time_unit() using: new_time_unit("tu_***", parent = mt_tz_unit)

Usage

mt_unit(n = 1L, calendar = attr(sys.function(), "cal"))

mt_loc_unit(
  n = 1L,
  lat = naive_loc,
  lon = naive_loc,
  alt = naive(0),
  calendar = attr(sys.function(), "cal")
)

mt_tz_unit(n = 1L, tz = naive_tz, calendar = attr(sys.function(), "cal"))

Arguments

n

The step size of time granule. For example, n = 2L is 2 time units, and cal_isoweek$week(2L) would represent 2 weeks (a fortnight).

calendar

The calendar containing the unit. Calendar constructors supply this automatically.

lat

Numeric. Latitude in decimal degrees. Range: -90 to 90. Default: naive location (astronomical calculations require lat).

lon

Numeric. Longitude in decimal degrees. Range: -180 to 180. Default: naive location (astronomical calculations require lon).

alt

Numeric. Altitude in meters above sea level. Default: 0 (sea level).

tz

The timezone name for the unit (valid units can be found with ⁠[tzdb::tzdb_names()]⁠)

Details

Time units are the building blocks of calendars in mixtime. Each unit represents a specific temporal component (e.g., day, month, year) and can be combined using new_calendar() to create a calendar system.

When creating custom calendars, define time unit classes that inherit from either mt_unit (for standard units) or mt_tz_unit (for timezone-aware units), then pass them as named arguments to new_calendar(). The calendar will use these names to create constructor functions accessible via $ notation (e.g., calendar$day(1L)).

Value

A time granule object of class mt_unit

Calendar Algebra Methods

Time units enable calendar arithmetic through key generic methods that should be implemented for custom time units:

  • chronon_cardinality_fixed(x, y) - Returns the number of unit x granules that fit within one unit y granule, for relationships that are a constant, context-independent number (e.g., 7 days per week, 24 hours per day). Prefer this over chronon_cardinality() whenever the relationship does not depend on at, since it is also used to determine which relationships are safe to use for chronon_divmod()'s graph traversal.

  • chronon_cardinality(x, y, at) - Returns the number of x granule that fit within one y granule. This is variable based on at (e.g., 28-31 days per month). Only implement this directly (rather than chronon_cardinality_fixed()) when the relationship genuinely depends on at, and pair it with a direct chronon_divmod() method so that the relationship remains reachable during graph traversal.

  • chronon_divmod(x, from, to) - Converts time point x from granules of from to granules of to, returning a list with div (the quotient) and mod. This enables conversions between granules that have variable cardinality (e.g., the date 2020-03-23 to the month 2020-03). All conversions should be based on chronons since epoch (1970-01-01), in the UTC time zone.

These methods work together to enable mixtime to perform calendar-aware arithmetic, understanding that months have variable lengths and handling timezone-aware conversions.

See Also

new_calendar() for creating calendars from time units

Examples

# Create a timezone-aware unit class

# Use these units to create a calendar
my_calendar <- new_calendar(
  day = new_time_unit("tu_my_day", parent = mt_unit),
  month = new_time_unit("tu_my_month", parent = mt_tz_unit),
  name = "my_calendar"
)

# Access unit constructors from the calendar
my_calendar$day(1L)
my_calendar$month(3L, tz = "America/New_York")


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