% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/linear_time.R
\name{linear_time_helpers}
\alias{linear_time_helpers}
\alias{year}
\alias{yearquarter}
\alias{yearmonth}
\alias{yearweek}
\alias{date}
\alias{datetime}
\title{Linear time helper functions}
\usage{
year(data, discrete = TRUE, calendar = time_calendar(data), ...)

yearquarter(data, discrete = TRUE, calendar = time_calendar(data), ...)

yearmonth(data, discrete = TRUE, calendar = time_calendar(data), ...)

yearweek(data, discrete = TRUE, calendar = time_calendar(data), ...)

date(data, discrete = TRUE, calendar = time_calendar(data), ...)

datetime(data, discrete = TRUE, calendar = time_calendar(data), ...)
}
\arguments{
\item{data}{A vector of time points (e.g. \link[base:Date]{base::Date}, \link[base:POSIXt]{base::POSIXt})}

\item{discrete}{If \code{TRUE}, the number of chronons since Unix epoch that
\code{data} falls into is returned as an integer. If \code{FALSE}, a fractional number
of chronons is returned (analagous to time using a continuous time model).}

\item{calendar}{A calendar used to evaluate the time units. Defaults to the
calendar of the input data. Common options include \link{cal_gregorian} and
\link{cal_isoweek}.}

\item{...}{Additional arguments for \code{\link[=linear_time]{linear_time()}}, such as \code{tz} for timezones.}
}
\value{
A \code{mixtime} time vector containing an \code{mt_linear} vector with chronons matching the function used.
}
\description{
Convenience functions for creating common linear time representations. These
functions work with different calendar systems and adapt based on the input
data's calendar.
}
\details{
These functions create linear time representations with different chronons
and granules:
\itemize{
\item \code{year()}: Represents time in whole years. The chronon is one year.
\item \code{yearquarter()}: Represents time in quarters, grouped by year. The chronon
is one quarter, with years as the granule.
\item \code{yearmonth()}: Represents time in months, grouped by year. The chronon is
one month, with years as the granule.
\item \code{yearweek()}: Represents time in weeks, grouped by year. The chronon is
one week, with years as the granule. Defaults to ISO 8601 week calendar.
}
}
\section{Calendar flexibility}{

These functions adapt to the calendar system of the input data. For example:
\itemize{
\item \code{year(date("2025-12-29"))} returns a Gregorian year
\item \code{year(yearweek(date("2025-12-29")))} returns an ISO week-based year
}

You can also explicitly specify a calendar using the \code{calendar} argument:

\preformatted{
year(date("2025-12-29"), calendar = cal_isoweek)
}
}

\section{Custom linear time representations}{

For more complex time structures, use \code{\link[=linear_time]{linear_time()}} or \code{\link[=new_linear_time_fn]{new_linear_time_fn()}}
to create custom representations with any combination of chronons and granules.
}

\examples{

# Gregorian year
year(Sys.Date())
year(Sys.Date(), discrete = FALSE)

# ISO week-based year
year(yearweek(Sys.Date()))

# Year-quarter
yearquarter(Sys.Date())
yearquarter(Sys.Date(), discrete = FALSE)

# Year-month
yearmonth(Sys.Date())
yearmonth(Sys.Date(), discrete = FALSE)

# Year-week (ISO 8601)
yearweek(Sys.Date())
yearweek(0:52)

}
\seealso{
\itemize{
\item \code{\link[=linear_time]{linear_time()}} for creating custom linear time representations
\item \code{\link[=new_linear_time_fn]{new_linear_time_fn()}} for creating reusable linear time functions
\item \link{cal_gregorian}, \link{cal_isoweek} for calendar systems
}
}
