| mt_unit | R Documentation |
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)
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"))
n |
The step size of time granule. For example, |
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 |
lon |
Numeric. Longitude in decimal degrees. Range: -180 to 180.
Default: naive location (astronomical calculations require |
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 |
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)).
A time granule object of class mt_unit
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.
new_calendar() for creating calendars from time units
# 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")
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.