% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/compose.R
\name{time_compose}
\alias{time_compose}
\title{Compose a linear time vector from linear and cyclical components}
\usage{
time_compose(..., discrete = TRUE, calendar = cal_gregorian)
}
\arguments{
\item{...}{Components used to build the time point. Each element is either:
\itemize{
\item a two-sided formula, \verb{lin(<granule>) ~ <value>} or
\verb{cyc(<granule>, <cycle>) ~ <value>} (see \code{\link[=lin]{lin()}}/\code{\link[=cyc]{cyc()}}), or
\item an existing linear or cyclical \code{mixtime} vector.
}}

\item{discrete}{Logical. If \code{TRUE} (default), returns integer chronons since
Unix epoch (discrete time model). If \code{FALSE}, returns fractional chronons
allowing representation of fractional time granules (continuous time model).}

\item{calendar}{Calendar used to resolve bare granule names in \code{lin()}/
\code{cyc()} formulas. Defaults to \link{cal_gregorian}.}
}
\value{
A \code{mixtime} time vector, at the finest chronon reached by the
chain (or the root's own chronon, if only one component is given).
Linear with a \code{lin()} anchor, cyclical otherwise.
}
\description{
\code{time_compose()} is the inverse of \code{\link[=time_components]{time_components()}}: given a set of
\code{\link[=lin]{lin()}}/\code{\link[=cyc]{cyc()}} components it reconstructs the corresponding time points.
Each component is either a two-sided formula pairing a spec with its value,
or an already-tagged linear/cyclical time vector (e.g. produced by
\code{\link[=linear_time]{linear_time()}}, \code{\link[=cyclical_time]{cyclical_time()}}, or a \code{\link[=time_components]{time_components()}} column).
}
\details{
A \code{lin()} component (the \strong{anchor}), when supplied, fixes the absolute
position at some granule (e.g. the year). Every other component must be
\code{cyc()}, chaining without gaps or branches from the anchor down to the
target chronon: each cycle must equal another component's chronon exactly.

With no \code{lin()} anchor, every component must be \code{cyc()}, chained the same
way but rooted at whichever component's cycle isn't itself another
component's chronon. The result is cyclical time tagged with that root's
cycle: \code{cyc(month, year) ~ 3} alone matches \code{month_of_year()} for any
March; chaining \code{cyc(day, month) ~ 15} onto it collapses to one (day,
year) pair, day-of-year 74, matching \code{day_of_year()} for 15 March.

Values of linear and cyclical components are specified on the right-hand-side
of the formula. A \code{lin()} value is the real-world count (e.g. the literal
year 1980); a \code{cyc()} value is the 1-indexed position within the cycle
(e.g. \code{cyc(month, year) ~ 3} is the 3rd month, March), matching everyday
counting rather than the raw 0-indexed position \code{\link[=time_components]{time_components()}} uses
internally.
}
\examples{
# cyc() values are 1-indexed positions: month 3 is March, day 15 is the 15th
time_compose(lin(year) ~ 1980, cyc(month, year) ~ 3, cyc(day, month) ~ 15)

# A lin() anchor alone is a valid (coarser) time point
time_compose(lin(year) ~ 1980)

# No lin() anchor: composes cyclical time
time_compose(cyc(month, year) ~ 3)

# Chaining collapses to one (chronon, cycle) pair: day 15 of month 3
# becomes day-of-year 74
time_compose(cyc(day, month) ~ 15, cyc(month, year) ~ 3)

# Round-tripping through time_components()
parts <- time_components(as.Date("2024-03-15"), yr = lin(year), mth = cyc(month, year))
with(parts, time_compose(yr, mth))

# Multi-unit (self-referencing) cycles: the 3rd month (1-indexed) of the
# 4th 3-month block since epoch (block 3 = months 9-11 -> December 1970)
time_compose(lin(month(3L)) ~ 3, cyc(month(1L), month(3L)) ~ 3)

}
\seealso{
\code{\link[=time_components]{time_components()}} for the inverse operation, \code{\link[=lin]{lin()}}/\code{\link[=cyc]{cyc()}} for
the component vocabulary shared with \code{\link[=time_components]{time_components()}} and \code{\link[=format]{format()}}.
}
