Coerce to a tsibble object

Usage

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)

Arguments

x: Other objects to be coerced to a tsibble (tbl_ts).
key: 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()).
index: A variable to specify the time index variable.
regular: Regular time interval (TRUE) or irregular (FALSE). The interval is determined by the greatest common divisor of index column, if TRUE.
validate: 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.
.drop: If TRUE, empty key groups are dropped.
...: Other arguments passed on to individual methods.
tz: Time zone. May be useful when a ts object is more frequent than daily.
pivot_longer: TRUE gives a "longer" form of the data, otherwise as is.

Value

A tsibble object.

Details

A tsibble is sorted by its key first and index.

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

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().

Interval

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.

Examples

# 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.40   
#>  2 2017-01-02  0.255  
#>  3 2017-01-03 -2.44   
#>  4 2017-01-04 -0.00557
#>  5 2017-01-05  0.622  
#>  6 2017-01-06  1.15   
#>  7 2017-01-07 -1.82   
#>  8 2017-01-08 -0.247  
#>  9 2017-01-09 -0.244  
#> 10 2017-01-10 -0.283  
# 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.40   
#>  2 2017-01-02  0.255  
#>  3 2017-01-03 -2.44   
#>  4 2017-01-04 -0.00557
#>  5 2017-01-05  0.622  
#>  6 2017-01-06  1.15   
#>  7 2017-01-07 -1.82   
#>  8 2017-01-08 -0.247  
#>  9 2017-01-09 -0.244  
#> 10 2017-01-10 -0.283  

# 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.554 
#>  2 2010 Q2 x      0.629 
#>  3 2010 Q3 x      2.07  
#>  4 2010 Q4 x     -1.63  
#>  5 2011 Q1 x      0.512 
#>  6 2011 Q2 x     -1.86  
#>  7 2011 Q3 x     -0.522 
#>  8 2011 Q4 x     -0.0526
#>  9 2012 Q1 x      0.543 
#> 10 2012 Q2 x     -0.914 
#> # ℹ 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.554 
#>  2 2010 Q2 x      0.629 
#>  3 2010 Q3 x      2.07  
#>  4 2010 Q4 x     -1.63  
#>  5 2011 Q1 x      0.512 
#>  6 2011 Q2 x     -1.86  
#>  7 2011 Q3 x     -0.522 
#>  8 2011 Q4 x     -0.0526
#>  9 2012 Q1 x      0.543 
#> 10 2012 Q2 x     -0.914 
#> # ℹ 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.0700
#>  2 2010 Feb x     a     -0.251 
#>  3 2010 Mar x     a      0.0465
#>  4 2010 Jan x     b     -0.639 
#>  5 2010 Feb x     b      0.445 
#>  6 2010 Mar x     b      0.578 
#>  7 2010 Jan x     c     -0.0500
#>  8 2010 Feb x     c      2.76  
#>  9 2010 Mar x     c      0.118 
#> 10 2010 Apr y     a     -1.91  
#> # ℹ 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
#> # ℹ 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
#> # ℹ 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
#> # ℹ 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.
#> # ℹ 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.132
#>  2 1961 Feb Series 1  0.489
#>  3 1961 Mar Series 1 -1.70 
#>  4 1961 Apr Series 1 -1.47 
#>  5 1961 May Series 1  0.284
#>  6 1961 Jun Series 1  1.34 
#>  7 1961 Jul Series 1  0.237
#>  8 1961 Aug Series 1  1.32 
#>  9 1961 Sep Series 1  0.524
#> 10 1961 Oct Series 1  0.607
#> # ℹ 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.132      0.364   -0.968  
#>  2 1961 Feb      0.489     -0.286   -0.103  
#>  3 1961 Mar     -1.70       0.518    0.240  
#>  4 1961 Apr     -1.47      -0.103    0.0609 
#>  5 1961 May      0.284     -0.974   -2.18   
#>  6 1961 Jun      1.34       1.27    -0.118  
#>  7 1961 Jul      0.237      0.961    0.112  
#>  8 1961 Aug      1.32       0.769    0.00789
#>  9 1961 Sep      0.524      1.04     1.88   
#> 10 1961 Oct      0.607     -0.474    2.16   
#> # ℹ 90 more rows