tsibble(..., key = NULL, index, regular = TRUE, .drop = TRUE)
A set of name-value pairs.
Variable(s) that uniquely determine time indices. NULL
for
empty key, and c()
for multiple variables. It works with tidy selector
(e.g. dplyr::starts_with()
).
A variable to specify the time index variable.
Regular time interval (TRUE
) or irregular (FALSE
). The
interval is determined by the greatest common divisor of index column, if TRUE
.
If TRUE
, empty key groups are dropped.
A tsibble object.
A tsibble is sorted by its key first and index.
An extensive range of indices are supported by tsibble:
native time classes in R (such as Date
, POSIXct
, and difftime
)
tsibble's new additions (such as yearweek, yearmonth, and yearquarter).
other commonly-used classes: ordered
, hms::hms
, lubridate::period
,
and nanotime::nanotime
.
For a 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 yearmonth, instead of Date
or POSIXct
. Because months in a year
ensures the regularity, 12 months every year. However, if using 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 index_valid()
for the class and calculate the interval through interval_pull()
.
Key variable(s) together with the index uniquely identifies each record:
Empty: an implicit variable. NULL
resulting in a univariate time series.
A single variable: For example, data(pedestrian)
uses Sensor
as the key.
Multiple variables: For example, Declare key = c(Region, State, Purpose)
for data(tourism)
.
Key can be created in conjunction with tidy selectors like starts_with()
.
The interval function returns the interval associated with the tsibble.
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".
Irregular: as_tsibble(regular = FALSE)
gives the irregular tsibble. It is
marked with !
.
Unknown: Not determined (?
), if it's an empty tsibble, or one entry for
each key variable.
An interval is obtained based on the corresponding index representation:
integerish numerics between 1582 and 2499: "year" (Y
). Note the year of
1582 saw the beginning of the Gregorian Calendar switch.
yearquarter
: "quarter" (Q
)
yearmonth
: "month" (M
)
yearweek
: "week" (W
)
Date
: "day" (D
)
difftime
: "week" (W
), "day" (D), "hour" (h
), "minute" (m
), "second" (s
)
POSIXt
/hms
: "hour" (h
), "minute" (m
), "second" (s
), "millisecond" (us
),
"microsecond" (ms
)
period
: "year" (Y
), "month" (M
), "day" (D
), "hour" (h
),
"minute" (m
), "second" (s
), "millisecond" (us
), "microsecond" (ms
)
nanotime
: "nanosecond" (ns
)
other numerics &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 filter()
, slice()
, and [.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.
# create a tsibble w/o a key
tsibble(
date = as.Date("2017-01-01") + 0:9,
value = rnorm(10)
)
#> Using `date` as index variable.
#> # A tsibble: 10 x 2 [1D]
#> date value
#> <date> <dbl>
#> 1 2017-01-01 1.26
#> 2 2017-01-02 -0.322
#> 3 2017-01-03 0.742
#> 4 2017-01-04 -0.806
#> 5 2017-01-05 -2.38
#> 6 2017-01-06 1.15
#> 7 2017-01-07 -0.821
#> 8 2017-01-08 -0.144
#> 9 2017-01-09 0.665
#> 10 2017-01-10 0.0544
# 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
)
#> Using `qtr` as index variable.
#> # A tsibble: 30 x 3 [1Q]
#> # Key: group [3]
#> qtr group value
#> <qtr> <chr> <dbl>
#> 1 2010 Q1 x 0.541
#> 2 2010 Q2 x 1.47
#> 3 2010 Q3 x 0.162
#> 4 2010 Q4 x 0.669
#> 5 2011 Q1 x -1.88
#> 6 2011 Q2 x -1.06
#> 7 2011 Q3 x 1.42
#> 8 2011 Q4 x -0.878
#> 9 2012 Q1 x -0.847
#> 10 2012 Q2 x -0.904
#> # … with 20 more rows
# 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)
)
#> Using `mth` as index variable.
#> # A tsibble: 27 x 4 [1M]
#> # Key: xyz, abc [9]
#> mth xyz abc value
#> <mth> <chr> <chr> <dbl>
#> 1 2010 Jan x a 0.145
#> 2 2010 Feb x a -1.68
#> 3 2010 Mar x a 0.680
#> 4 2010 Jan x b -0.300
#> 5 2010 Feb x b -0.859
#> 6 2010 Mar x b 0.338
#> 7 2010 Jan x c -0.723
#> 8 2010 Feb x c -0.0651
#> 9 2010 Mar x c -0.667
#> 10 2010 Apr y a 1.59
#> # … with 17 more rows
# 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
)
#> # A tsibble: 30 x 3 [1Q]
#> # Key: key [3]
#> index key value
#> <qtr> <chr> <dbl>
#> 1 2010 Q1 x -0.546
#> 2 2010 Q2 x 0.439
#> 3 2010 Q3 x 0.352
#> 4 2010 Q4 x 0.452
#> 5 2011 Q1 x -1.86
#> 6 2011 Q2 x 1.32
#> 7 2011 Q3 x 0.757
#> 8 2011 Q4 x -1.95
#> 9 2012 Q1 x 0.00282
#> 10 2012 Q2 x 0.392
#> # … with 20 more rows