[Stable]

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:

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.

See also

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 #> # … 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.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 #> # … 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.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 #> # … 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.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 #> # … 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.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 #> # … with 90 more rows