% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/as-tsibble.R
\name{tsibble}
\alias{tsibble}
\title{Create a tsibble object}
\usage{
tsibble(..., key = NULL, index, regular = TRUE, .drop = TRUE)
}
\arguments{
\item{...}{A set of name-value pairs.}

\item{key}{Variable(s) that uniquely determine time indices. \code{NULL} for
empty key, and \code{c()} for multiple variables. It works with tidy selector
(e.g. \code{\link[dplyr:reexports]{dplyr::starts_with()}}).}

\item{index}{A variable to specify the time index variable.}

\item{regular}{Regular time interval (\code{TRUE}) or irregular (\code{FALSE}). The
interval is determined by the greatest common divisor of index column, if \code{TRUE}.}

\item{.drop}{If \code{TRUE}, empty key groups are dropped.}
}
\value{
A tsibble object.
}
\description{
\lifecycle{stable}
}
\details{
A tsibble is sorted by its key first and index.
}
\section{Index}{

An extensive range of indices are supported by tsibble:
\itemize{
\item native time classes in R (such as \code{Date}, \code{POSIXct}, and \code{difftime})
\item tsibble's new additions (such as \link{yearweek}, \link{yearmonth}, and \link{yearquarter}).
\item other commonly-used classes: \code{ordered}, \code{hms::hms}, \code{lubridate::period},
and \code{nanotime::nanotime}.
}

For a \code{tbl_ts} of regular interval, a choice of index representation has to
be made. For example, a monthly data should correspond to time index created
by \link{yearmonth}, instead of \code{Date} or \code{POSIXct}. Because months in a year
ensures the regularity, 12 months every year. However, if using \code{Date}, a
month containing days ranges from 28 to 31 days, which results in irregular
time space. This is also applicable to year-week and year-quarter.

Tsibble supports arbitrary index classes, as long as they can be ordered from
past to future. To support a custom class, you need to define \code{\link[=index_valid]{index_valid()}}
for the class and calculate the interval through \code{\link[=interval_pull]{interval_pull()}}.
}

\section{Key}{

Key variable(s) together with the index uniquely identifies each record:
\itemize{
\item Empty: an implicit variable. \code{NULL} resulting in a univariate time series.
\item A single variable: For example, \code{data(pedestrian)} uses \code{Sensor} as the key.
\item Multiple variables: For example, Declare \code{key = c(Region, State, Purpose)}
for \code{data(tourism)}.
Key can be created in conjunction with tidy selectors like \code{starts_with()}.
}
}

\section{Interval}{

The \link{interval} function returns the interval associated with the tsibble.
\itemize{
\item Regular: the value and its time unit including "nanosecond", "microsecond",
"millisecond", "second", "minute", "hour", "day", "week", "month", "quarter",
"year". An unrecognisable time interval is labelled as "unit".
\item Irregular: \code{as_tsibble(regular = FALSE)} gives the irregular tsibble. It is
marked with \code{!}.
\item Unknown: Not determined (\verb{?}), if it's an empty tsibble, or one entry for
each key variable.
}

An interval is obtained based on the corresponding index representation:
\itemize{
\item integerish numerics between 1582 and 2499: "year" (\code{Y}). Note the year of
1582 saw the beginning of the Gregorian Calendar switch.
\item \code{yearquarter}: "quarter" (\code{Q})
\item \code{yearmonth}: "month" (\code{M})
\item \code{yearweek}: "week" (\code{W})
\item \code{Date}: "day" (\code{D})
\item \code{difftime}: "week" (\code{W}), "day" (D), "hour" (\code{h}), "minute" (\code{m}), "second" (\code{s})
\item \code{POSIXt}/\code{hms}: "hour" (\code{h}), "minute" (\code{m}), "second" (\code{s}), "millisecond" (\code{us}),
"microsecond" (\code{ms})
\item \code{period}: "year" (\code{Y}), "month" (\code{M}), "day" (\code{D}), "hour" (\code{h}),
"minute" (\code{m}), "second" (\code{s}), "millisecond" (\code{us}), "microsecond" (\code{ms})
\item \code{nanotime}: "nanosecond" (\code{ns})
\item other numerics &\code{ordered} (ordered factor): "unit"
When the interval cannot be obtained due to the mismatched index format, an
error is issued.
}

The interval is invariant to subsetting, such as \code{filter()}, \code{slice()}, and \verb{[.tbl_ts}.
However, if the result is an empty tsibble, the interval is always unknown.
When joining a tsibble with other data sources and aggregating to different
time scales, the interval gets re-calculated.
}

\examples{
# create a tsibble w/o a key
tsibble(
  date = as.Date("2017-01-01") + 0:9,
  value = rnorm(10)
)

# create a tsibble with a single variable for key
tsibble(
  qtr = rep(yearquarter("2010 Q1") + 0:9, 3),
  group = rep(c("x", "y", "z"), each = 10),
  value = rnorm(30),
  key = group
)

# create a tsibble with multiple variables for key
tsibble(
  mth = rep(yearmonth("2010 Jan") + 0:8, each = 3),
  xyz = rep(c("x", "y", "z"), each = 9),
  abc = rep(letters[1:3], times = 9),
  value = rnorm(27),
  key = c(xyz, abc)
)

# create a tsibble containing "key" and "index" as column names
tsibble(!!!list(
  index = rep(yearquarter("2010 Q1") + 0:9, 3),
  key = rep(c("x", "y", "z"), each = 10),
  value = rnorm(30)),
  key = key, index = index
)
}
\seealso{
\link{build_tsibble}
}
