as_tsibble(
x,
key = NULL,
index,
regular = TRUE,
validate = TRUE,
.drop = TRUE,
...
)
# S3 method for ts
as_tsibble(x, ..., tz = "UTC")
# S3 method for mts
as_tsibble(x, ..., tz = "UTC", pivot_longer = TRUE)
Other objects to be coerced to a tsibble (tbl_ts
).
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
.
TRUE
suggests to verify that each key or each combination
of key variables leads to unique time indices (i.e. a valid tsibble). If you
are sure that it's a valid input, specify FALSE
to skip the checks.
If TRUE
, empty key groups are dropped.
Other arguments passed on to individual methods.
Time zone. May be useful when a ts
object is more frequent than
daily.
TRUE
gives a "longer" form of the data, otherwise as is.
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.
# coerce tibble to tsibble w/o a key
tbl1 <- tibble(
date = as.Date("2017-01-01") + 0:9,
value = rnorm(10)
)
as_tsibble(tbl1)
#> Using `date` as index variable.
#> # A tsibble: 10 x 2 [1D]
#> date value
#> <date> <dbl>
#> 1 2017-01-01 1.54
#> 2 2017-01-02 -1.16
#> 3 2017-01-03 2.68
#> 4 2017-01-04 0.0759
#> 5 2017-01-05 -0.0751
#> 6 2017-01-06 0.302
#> 7 2017-01-07 0.119
#> 8 2017-01-08 -0.198
#> 9 2017-01-09 -0.923
#> 10 2017-01-10 0.956
# supply the index to suppress the message
as_tsibble(tbl1, index = date)
#> # A tsibble: 10 x 2 [1D]
#> date value
#> <date> <dbl>
#> 1 2017-01-01 1.54
#> 2 2017-01-02 -1.16
#> 3 2017-01-03 2.68
#> 4 2017-01-04 0.0759
#> 5 2017-01-05 -0.0751
#> 6 2017-01-06 0.302
#> 7 2017-01-07 0.119
#> 8 2017-01-08 -0.198
#> 9 2017-01-09 -0.923
#> 10 2017-01-10 0.956
# coerce tibble to tsibble with a single variable for key
# use `yearquarter()` to represent quarterly data
tbl2 <- tibble(
qtr = rep(yearquarter("2010 Q1") + 0:9, 3),
group = rep(c("x", "y", "z"), each = 10),
value = rnorm(30)
)
# "qtr" is automatically considered as the index var
as_tsibble(tbl2, 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.125
#> 2 2010 Q2 x 0.207
#> 3 2010 Q3 x 0.161
#> 4 2010 Q4 x -1.02
#> 5 2011 Q1 x 0.128
#> 6 2011 Q2 x -0.939
#> 7 2011 Q3 x -0.512
#> 8 2011 Q4 x 0.786
#> 9 2012 Q1 x -2.17
#> 10 2012 Q2 x 1.20
#> # … with 20 more rows
as_tsibble(tbl2, key = group, index = qtr)
#> # A tsibble: 30 x 3 [1Q]
#> # Key: group [3]
#> qtr group value
#> <qtr> <chr> <dbl>
#> 1 2010 Q1 x 0.125
#> 2 2010 Q2 x 0.207
#> 3 2010 Q3 x 0.161
#> 4 2010 Q4 x -1.02
#> 5 2011 Q1 x 0.128
#> 6 2011 Q2 x -0.939
#> 7 2011 Q3 x -0.512
#> 8 2011 Q4 x 0.786
#> 9 2012 Q1 x -2.17
#> 10 2012 Q2 x 1.20
#> # … with 20 more rows
# create a tsibble with multiple variables for key
# use `yearmonth()` to represent monthly data
tbl3 <- tibble(
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)
)
as_tsibble(tbl3, 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.834
#> 2 2010 Feb x a 0.346
#> 3 2010 Mar x a -0.348
#> 4 2010 Jan x b -0.645
#> 5 2010 Feb x b 1.15
#> 6 2010 Mar x b 0.683
#> 7 2010 Jan x c 1.01
#> 8 2010 Feb x c 0.313
#> 9 2010 Mar x c -0.896
#> 10 2010 Apr y a 0.600
#> # … with 17 more rows
# coerce ts to tsibble
as_tsibble(AirPassengers)
#> # A tsibble: 144 x 2 [1M]
#> index value
#> <mth> <dbl>
#> 1 1949 Jan 112
#> 2 1949 Feb 118
#> 3 1949 Mar 132
#> 4 1949 Apr 129
#> 5 1949 May 121
#> 6 1949 Jun 135
#> 7 1949 Jul 148
#> 8 1949 Aug 148
#> 9 1949 Sep 136
#> 10 1949 Oct 119
#> # … with 134 more rows
as_tsibble(sunspot.year)
#> # A tsibble: 289 x 2 [1Y]
#> index value
#> <dbl> <dbl>
#> 1 1700 5
#> 2 1701 11
#> 3 1702 16
#> 4 1703 23
#> 5 1704 36
#> 6 1705 58
#> 7 1706 29
#> 8 1707 20
#> 9 1708 10
#> 10 1709 8
#> # … with 279 more rows
as_tsibble(sunspot.month)
#> # A tsibble: 3,177 x 2 [1M]
#> index value
#> <mth> <dbl>
#> 1 1749 Jan 58
#> 2 1749 Feb 62.6
#> 3 1749 Mar 70
#> 4 1749 Apr 55.7
#> 5 1749 May 85
#> 6 1749 Jun 83.5
#> 7 1749 Jul 94.8
#> 8 1749 Aug 66.3
#> 9 1749 Sep 75.9
#> 10 1749 Oct 75.5
#> # … with 3,167 more rows
as_tsibble(austres)
#> # A tsibble: 89 x 2 [1Q]
#> index value
#> <qtr> <dbl>
#> 1 1971 Q2 13067.
#> 2 1971 Q3 13130.
#> 3 1971 Q4 13198.
#> 4 1972 Q1 13254.
#> 5 1972 Q2 13304.
#> 6 1972 Q3 13354.
#> 7 1972 Q4 13409.
#> 8 1973 Q1 13459.
#> 9 1973 Q2 13504.
#> 10 1973 Q3 13553.
#> # … with 79 more rows
# coerce mts to tsibble
z <- ts(matrix(rnorm(300), 100, 3), start = c(1961, 1), frequency = 12)
as_tsibble(z)
#> # A tsibble: 300 x 3 [1M]
#> # Key: key [3]
#> index key value
#> <mth> <chr> <dbl>
#> 1 1961 Jan Series 1 -0.986
#> 2 1961 Feb Series 1 1.41
#> 3 1961 Mar Series 1 -0.585
#> 4 1961 Apr Series 1 0.544
#> 5 1961 May Series 1 1.13
#> 6 1961 Jun Series 1 -0.0259
#> 7 1961 Jul Series 1 0.936
#> 8 1961 Aug Series 1 -0.112
#> 9 1961 Sep Series 1 -2.05
#> 10 1961 Oct Series 1 0.138
#> # … with 290 more rows
as_tsibble(z, pivot_longer = FALSE)
#> # A tsibble: 100 x 4 [1M]
#> index `Series 1` `Series 2` `Series 3`
#> <mth> <dbl> <dbl> <dbl>
#> 1 1961 Jan -0.986 0.728 0.296
#> 2 1961 Feb 1.41 1.14 -1.66
#> 3 1961 Mar -0.585 -0.150 0.415
#> 4 1961 Apr 0.544 0.0588 0.225
#> 5 1961 May 1.13 0.581 -1.86
#> 6 1961 Jun -0.0259 0.117 -0.821
#> 7 1961 Jul 0.936 0.838 0.120
#> 8 1961 Aug -0.112 -0.635 -0.0202
#> 9 1961 Sep -2.05 -0.000832 -1.25
#> 10 1961 Oct 0.138 0.0881 -0.672
#> # … with 90 more rows