Nothing
# Compute numeric time parts from a time object
#
# `chronon_parts()` decomposes a time object into its numeric linear and cyclical
# components by repeatedly applying `chronon_divmod()` along the call path of a
# minimal Steiner tree. The linear parts are the `$div` result, which is re-used
# along the divmod path where `$mod` results form the required cyclical parts.
#
# @param x A `mt_time` object (an uni-typed mixtime vector)
# @param linear A list of time granules representing linear (non-repeating)
# components, e.g. `list(cal_gregorian$year(1L))`.
# @param cyclical A list of cyclical component specifications, where each
# element is a list of two time granules `list(from, to)` (chronon and cycle),
# e.g. `list(list(cal_gregorian$month(1L), cal_gregorian$year(1L)))` for
# month-of-year.
#
# @return A list with three elements:
# - `$linear`: a list of integer vectors, one per element of `linear`.
# - `$cyclical`: a list of integer vectors, one per element of `cyclical`.
# - `$cyclical_at`: a list of integer vectors, one per element of `cyclical`,
# giving the linear position of the cycle granule.
chronon_parts <- function(x, linear = list(), cyclical = list()) {
start_tu <- attr(x, "chronon")
# Read the time points as local wall-clock values. A continuous time model
# keeps its fractional position instead of flooring it away here, less any
# floating-point error that would floor a whole unit away.
x <- vec_data(x)
discrete <- is.integer(x)
x <- chronon_to_local(start_tu, round_ulp(x))
x <- if (discrete) floor_ulp(x) else round_ulp(x)
# The two granules of a cyclical part: the chronon is the finer unit (the
# desired output unit) and the cycle the coarser unit it repeats within.
cyclical_chronon <- lapply(cyclical, `[[`, 1L)
cyclical_cycle <- lapply(cyclical, `[[`, 2L)
# Parts are recognised by matching class ids against the node reached at each
# step of the traversal, so each set of targets is keyed by position in a
# vector of the class id it is matched on (NA where the match cannot apply).
linear_ids <- vapply(linear, S7_class_id, character(1L))
chronon_ids <- vapply(cyclical_chronon, S7_class_id, character(1L))
cycle_ids <- vapply(cyclical_cycle, S7_class_id, character(1L))
# Multi-unit cycles (e.g. a month within 15 months) repeat within a coarser
# granule of the *same* time unit, so their chronon and cycle resolve to one
# node: a self-loop in the class-keyed cardinality graph rather than a path
# through it. They ask the graph only to reach that node (a terminal, with no
# co-occurrence to enforce) and are matched on their chronon, since matching
# them on their cycle would pair them with the degenerate divmod of a granule
# with itself.
self_cycle <- chronon_ids == cycle_ids
self_cycle_ids <- chronon_ids
self_cycle_ids[!self_cycle] <- NA_character_
cycle_ids[self_cycle] <- NA_character_
# Prepare results to be filled via recursive divmod execution
linear_results <- vector("list", length(linear))
cyclical_results <- vector("list", length(cyclical))
cyclical_at <- vector("list", length(cyclical))
# Resolve parts with finer granules than the chronon for continuous time data
cycle_is_root <- !self_cycle &
cycle_ids == S7_class_id(start_tu) &
vapply(cyclical_cycle, function(cy) cy@n == start_tu@n, logical(1L))
if (any(cycle_is_root)) {
whole <- if (discrete) x else floor(x)
for (i in which(cycle_is_root)) {
chronon_i <- cyclical_chronon[[i]]
cyclical_results[[i]] <- if (discrete) {
rep(NA_integer_, length(x))
} else {
chronon_divmod(start_tu, chronon_i, x)$div -
chronon_divmod(start_tu, chronon_i, whole)$div
}
cyclical_at[[i]] <- whole
}
cycle_ids[cycle_is_root] <- NA_character_
}
# Find a suitable tree of chronon_divmod() steps that computes all cyclical
# and linear parts. Cross-unit cycles must reach both of their granules on one
# root-to-leaf path, while the other targets need only be reached.
#
# `group_idx` maps each element of the `groups` argument back to its
# position in `cyclical`/`chronon_ids`/`cycle_ids` (the filtered list passed
# as `groups` drops elements in order, so `which()` recovers the original
# index of each survivor).
group_idx <- which(!self_cycle & !cycle_is_root)
dispatch <- S7_graph_dispatch_multi(
graph = chronon_cardinality_graph(),
start = start_tu,
terminals = c(linear, cyclical_chronon[self_cycle]),
groups = cyclical[group_idx]
)
tree <- dispatch$tree
# A group that could not be co-located on one path (a real structural gap
# in the registered graph, not something to paper over) must not let
# traverse() match its chronon/cycle by class id alone: either class might
# still be reachable via some *other*, unrelated group or terminal, which
# would silently compute a wrong (non-NULL) value instead of leaving the
# part genuinely missing. Nulling both ids here (the same pattern already
# used above for self_cycle/cycle_is_root) makes them unmatchable, so
# abort_missing_parts() below correctly reports them.
failed <- group_idx[dispatch$failed_groups]
chronon_ids[failed] <- NA_character_
cycle_ids[failed] <- NA_character_
# Traverse the divmod path to compute parts. `parent_id` is the caller's
# `child_id`, so it is handed down rather than looked up again.
traverse <- function(node, parent_tu, parent_id, x) {
child_tu <- node$node
child_id <- S7_class_id(child_tu)
dm <- chronon_divmod(
from = parent_tu,
to = child_tu,
x = x
)
# Collect linear result: div when child matches a linear target
for (i in which(child_id == linear_ids)) {
linear_results[[i]] <<- count_in_granule(dm$div, child_tu, linear[[i]]) +
chronon_epoch(child_tu)
}
# Complete multi-unit cycles rooted at this granule. `dm$div` is the time
# point in `child_tu` units (at the root, an identity divmod of `x`), so the
# position within the cycle is a single divmod away.
for (i in which(child_id == self_cycle_ids)) {
dm_self <- chronon_divmod(
from = cyclical_chronon[[i]],
to = cyclical_cycle[[i]],
x = count_in_granule(dm$div, child_tu, cyclical_chronon[[i]])
)
cyclical_results[[i]] <<- dm_self$mod
cyclical_at[[i]] <<- dm_self$div
}
# Recurse each child with $div as the new time point (now in child_tu units)
incomplete <- unlist(lapply(node$children, traverse, child_tu, child_id, dm$div))
# Unwind recursion with backward conversion for cyclical parts: an
# incomplete result counts `child_tu` units so far, so re-expressing it in
# the finer `parent_tu` multiplies by the cardinality at the current `dm$div`
# position and adds this step's remainder. The cardinality is a property of
# this step alone, so it is found once for all of them.
if (length(incomplete) > 0L) {
cardinality <- chronon_cardinality(parent_tu, child_tu, dm$div)
for (i in incomplete) {
cyclical_results[[i]] <<- cyclical_results[[i]] * cardinality + dm$mod
}
}
# Cycles whose coarser granule is this node start counting here
starting <- which(child_id == cycle_ids)
if (length(starting) > 0L) {
cyclical_results[starting] <<- list(dm$mod)
cyclical_at[starting] <<- list(dm$div)
incomplete <- c(incomplete, starting)
}
# Cyclical parts accumulate in `parent_tu`, the finest granule of their
# chronon's unit, so those completing here are rescaled to the size asked for.
complete <- chronon_ids[incomplete] == parent_id
for (i in incomplete[complete]) {
cyclical_results[[i]] <<- count_in_granule(
cyclical_results[[i]], parent_tu, cyclical_chronon[[i]]
)
}
# Return vector of which cyclical targets are still incomplete after this step
incomplete[!complete]
}
traverse(tree, start_tu, S7_class_id(start_tu), x)
# Check if all targets were found
abort_missing_parts(linear_results, linear, time_granule_label, "linear")
abort_missing_parts(cyclical_results, cyclical, cycle_label, "cyclical")
# Return list of the same order as input
list(linear = linear_results, cyclical = cyclical_results, cyclical_at = cyclical_at)
}
# Re-express `value`, a count of `from` granules, as a count of `to` granules of
# the same time unit (e.g. months at the month node into quarters for
# `month(3L)`). Nodes hold the finest granule of their time unit, so `to` is
# never finer than `from` and the conversion is a division away.
count_in_granule <- function(value, from, to) {
if (from@n == to@n) value else chronon_divmod(from, to, value)$div
}
# Abort when the traversal did not reach every requested part, describing those
# it missed with `label()` applied to the corresponding element of `targets`.
abort_missing_parts <- function(results, targets, label, type) {
found <- !vapply(results, is.null, logical(1L))
if (all(found)) return(invisible(NULL))
missed <- vapply(targets[!found], label, character(1L))
cli::cli_abort(
c(
"The following {type} time parts could not be computed from the input time object:",
i = "{missed}",
i = "All requested {type} parts need to be included as granules for {.code linear_time()}"
),
call = NULL
)
}
# Describe a cyclical part for error messages, e.g. "1 month -> 15 months".
cycle_label <- function(x) {
paste(time_granule_label(x[[1L]]), "->", time_granule_label(x[[2L]]))
}
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.