tsibble v0.6.2

0

Monthly downloads

0th

Percentile

Tidy Temporal Data Frames and Tools

Provides a 'tbl_ts' class (the 'tsibble') to store and manage temporal data in a data-centric format, which is built on top of the 'tibble'. The 'tsibble' aims at easily manipulating and analysing temporal data, including counting and filling time gaps, aggregate over calendar periods, performing rolling window calculations, and etc.

Readme

tsibble

/ˈt͡sɪbəl/

Travis-CI Build
Status Coverage
Status CRAN\_Status\_Badge Downloads

The tsibble package provides a data class of tbl_ts to represent tidy temporal data. A tsibble consists of a time index, key and other measured variables in a data-centric format, which is built on top of the tibble.

Installation

You could install the stable version on CRAN:

install.packages("tsibble")

You could install the development version from Github using

# install.packages("remotes")
remotes::install_github("tidyverts/tsibble")

Get started

Coerce to a tsibble with as_tsibble()

The weather data included in the package nycflights13 is used as an example to illustrate. The “index” variable is the time_hour containing the date-times, and the “key” is the origin as weather stations created via id(). The key together with the index uniquely identifies each observation, which gives a valid tsibble. Other columns can be considered as measured variables.

library(tsibble)
weather <- nycflights13::weather %>% 
  select(origin, time_hour, temp, humid, precip)
weather_tsbl <- as_tsibble(weather, key = id(origin), index = time_hour)
weather_tsbl
#> # A tsibble: 26,115 x 5 [1h] <America/New_York>
#> # Key:       origin [3]
#>   origin time_hour            temp humid precip
#>   <chr>  <dttm>              <dbl> <dbl>  <dbl>
#> 1 EWR    2013-01-01 01:00:00  39.0  59.4      0
#> 2 EWR    2013-01-01 02:00:00  39.0  61.6      0
#> 3 EWR    2013-01-01 03:00:00  39.0  64.4      0
#> 4 EWR    2013-01-01 04:00:00  39.9  62.2      0
#> 5 EWR    2013-01-01 05:00:00  39.0  64.4      0
#> # … with 2.611e+04 more rows

The key is comprised of one or more variables. See package?tsibble and vignette("intro-tsibble") for details.

The tsibble internally computes the interval for given time indices based on the time representation, ranging from year to nanosecond. The POSIXct corresponds to sub-daily series, Date to daily, yearweek to weekly, yearmonth/yearmon to monthly, yearquarter/yearqtr to quarterly, and etc.

fill_gaps() to turn implicit missing values into explicit missing values

Often there are implicit missing cases in temporal data. If the observations are made at regular time interval, we could turn these implicit missings to be explicit simply using fill_gaps(), filling gaps in precipitation (precip) with 0 in the meanwhile. It is quite common to replaces NAs with its previous observation for each origin in time series analysis, which is easily done using fill() from tidyr.

full_weather <- weather_tsbl %>%
  fill_gaps(precip = 0) %>% 
  group_by(origin) %>% 
  fill(temp, humid, .direction = "down")
full_weather
#> # A tsibble: 26,190 x 5 [1h] <America/New_York>
#> # Key:       origin [3]
#> # Groups:    origin [3]
#>   origin time_hour            temp humid precip
#>   <chr>  <dttm>              <dbl> <dbl>  <dbl>
#> 1 EWR    2013-01-01 01:00:00  39.0  59.4      0
#> 2 EWR    2013-01-01 02:00:00  39.0  61.6      0
#> 3 EWR    2013-01-01 03:00:00  39.0  64.4      0
#> 4 EWR    2013-01-01 04:00:00  39.9  62.2      0
#> 5 EWR    2013-01-01 05:00:00  39.0  64.4      0
#> # … with 2.618e+04 more rows

fill_gaps() also handles filling time gaps by values or functions, and respects time zones for date-times. Wanna a quick overview of implicit missing values? Check out vignette("implicit-na").

index_by() + summarise() to aggregate over calendar periods

index_by() is the counterpart of group_by() in temporal context, but it groups the index only. In conjunction with index_by(), summarise() and its scoped variants aggregate interested variables over calendar periods. index_by() goes hand in hand with the index functions including as.Date(), yearweek(), yearmonth(), and yearquarter(), as well as other friends from lubridate. For example, it would be of interest in computing average temperature and total precipitation per month, by applying yearmonth() to the hourly time index.

full_weather %>%
  group_by(origin) %>%
  index_by(year_month = yearmonth(time_hour)) %>% # monthly aggregates
  summarise(
    avg_temp = mean(temp, na.rm = TRUE),
    ttl_precip = sum(precip, na.rm = TRUE)
  )
#> # A tsibble: 36 x 4 [1M]
#> # Key:       origin [3]
#>   origin year_month avg_temp ttl_precip
#>   <chr>       <mth>    <dbl>      <dbl>
#> 1 EWR      2013 Jan     35.6       3.53
#> 2 EWR      2013 Feb     34.2       3.83
#> 3 EWR      2013 Mar     40.1       3   
#> 4 EWR      2013 Apr     53.0       1.47
#> 5 EWR      2013 May     63.3       5.44
#> # … with 31 more rows

While collapsing rows (like summarise()), group_by() and index_by() will take care of updating the key and index respectively. This index_by() + summarise() combo can help with regularising a tsibble of irregular time space too.

A family of window functions: slide(), tile(), stretch()

Temporal data often involves moving window calculations. Several functions in tsibble allow for different variations of moving windows using purrr-like syntax:

  • slide()/slide2()/pslide(): sliding window with overlapping observations.
  • tile()/tile2()/ptile(): tiling window without overlapping observations.
  • stretch()/stretch2()/pstretch(): fixing an initial window and expanding to include more observations.

For example, a moving average of window size 3 is carried out on hourly temperatures for each group (origin).

full_weather %>% 
  group_by(origin) %>% 
  mutate(temp_ma = slide_dbl(temp, ~ mean(., na.rm = TRUE), .size = 3))
#> # A tsibble: 26,190 x 6 [1h] <America/New_York>
#> # Key:       origin [3]
#> # Groups:    origin [3]
#>   origin time_hour            temp humid precip temp_ma
#>   <chr>  <dttm>              <dbl> <dbl>  <dbl>   <dbl>
#> 1 EWR    2013-01-01 01:00:00  39.0  59.4      0    NA  
#> 2 EWR    2013-01-01 02:00:00  39.0  61.6      0    NA  
#> 3 EWR    2013-01-01 03:00:00  39.0  64.4      0    39.0
#> 4 EWR    2013-01-01 04:00:00  39.9  62.2      0    39.3
#> 5 EWR    2013-01-01 05:00:00  39.0  64.4      0    39.3
#> # … with 2.618e+04 more rows

Looking for rolling in parallel? Their multiprocessing equivalents are prefixed with future_. More examples can be found at vignette("window").

More around tsibble

Tsibble also serves a natural input to forecasting and many other downstream analytical tasks. Stay tuned for tidyverts.org.


Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Functions in tsibble

Name Description
filter_index A shorthand for filtering time index for a tsibble
guess_frequency Guess a time frequency from other index objects
is_tsibble If the object is a tsibble
time_in If time falls in the ranges using compact expressions
index_valid Add custom index support for a tsibble
id Identifiers used for creating key
time_unit Extract time unit from a vector
pedestrian Pedestrian counts in the city of Melbourne
yearweek Represent year-week (ISO), year-month or year-quarter objects
future_stretch Stretching window in parallel
future_slide Sliding window in parallel
future_tile Tiling window in parallel
count_gaps Count implicit gaps
key_size Compute sizes of key variables
key Return key variables
build_tsibble_meta Low-level constructor to a tsibble object
group_by_key Group by key variables
index_by Group and collapse by time index
gaps Find missing elements in x with respect to y
index Return index variable from a tsibble
has_gaps Does a tsibble have implicit gaps in time?
slide Sliding window calculation
key_by Change key variables for a given tbl_ts
slide2 Sliding window calculation over multiple inputs simultaneously
measures Return measured variables
pull_interval Pull time interval from a vector
reexports Objects exported from other packages
interval Meta-information of a tsibble
tile2 Tiling window calculation over multiple inputs simultaneously
tidyverse Tidyverse methods for tsibble
new_data New tsibble data and append new observations to a tsibble
new_interval Create a time interval
tiler Splits the input to a list according to the tiling window size.
new_tsibble Create a subclass of a tsibble
partial_slider Partially splits the input to a list according to the rolling window size.
stretch2 Stretching window calculation over multiple simultaneously
tile Tiling window calculation
stretcher Split the input to a list according to the stretching window size.
slider Splits the input to a list according to the rolling window size.
scan_gaps Scan a tsibble for implicit missing observations
stretch Stretching window calculation
tsibble Create a tsibble object
units_since Time units since Unix Epoch
tourism Australian domestic overnight trips
tsibble-package tsibble: tidy temporal data frames and tools
difference Lagged differences
build_tsibble Low-level constructor for a tsibble object
as.ts.tbl_ts Coerce a tsibble to a time series
as.tsibble Deprecated functions
is_duplicated Test duplicated observations determined by key and index variables
as_tibble.tbl_ts Coerce to a tibble or data frame
as_tsibble Coerce to a tsibble object
holiday_aus Australian national and state-based public holiday
fill_gaps Turn implicit missing values into explicit missing values
No Results!

Vignettes of tsibble

Name
faq.Rmd
implicit-na.Rmd
intro-tsibble.Rmd
references.bib
window.Rmd
No Results!

Last month downloads

Details

Type Package
License GPL-3
URL https://pkg.earo.me/tsibble
BugReports https://github.com/tidyverts/tsibble/issues
LinkingTo Rcpp (>= 0.12.0)
VignetteBuilder knitr
ByteCompile true
Encoding UTF-8
Language en-GB
LazyData true
RoxygenNote 6.1.1
Collate 'RcppExports.R' 'as-tsibble.R' 'bind.R' 'data.R' 'gaps.R' 'deprecated.R' 'dplyr-verbs.R' 'dplyr-join.R' 'error.R' 'filter-index.R' 'format.R' 'holiday.R' 'index-by.R' 'index-valid.R' 'interval.R' 'key-group.R' 'new-data.R' 'period.R' 'reexports.R' 'slide.R' 'stretch.R' 'subset.R' 'tidyr-verbs.R' 'tile.R' 'time-wise.R' 'ts2tsibble.R' 'tsibble-pkg.R' 'tsibble2ts.R' 'type-sum.R' 'update.R' 'utils-format.R' 'utils.R' 'zzz.R'
NeedsCompilation yes
Packaged 2018-12-12 02:59:25 UTC; earo
Repository CRAN
Date/Publication 2018-12-12 08:40:03 UTC

Include our badge in your README

[![Rdoc](http://www.rdocumentation.org/badges/version/tsibble)](http://www.rdocumentation.org/packages/tsibble)