tsibble v0.9.2

0

Monthly downloads

0th

Percentile

Tidy Temporal Data Frames and Tools

Provides a 'tbl_ts' class (the 'tsibble') for temporal data in an data- and model-oriented format. The 'tsibble' provides tools to easily manipulate and analyse temporal data, such as filling in time gaps and aggregating over calendar periods.

Readme

tsibble

R build
status Coverage
Status CRAN\_Status\_Badge Lifecycle:
maturing

The tsibble package provides a data infrastructure for tidy temporal data with wrangling tools. Adapting the tidy data principles, tsibble is a data- and model-oriented object. In tsibble:

  1. Index is a variable with inherent ordering from past to present.
  2. Key is a set of variables that define observational units over time.
  3. Each observation should be uniquely identified by index and key.
  4. Each observational unit should be measured at a common interval, if regularly spaced.

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

To coerce a data frame to tsibble, we need to declare key and index. For example, in the weather data from the package nycflights13, the time_hour containing the date-times should be declared as index, and the origin as key. Other columns can be considered as measured variables.

library(dplyr)
library(tsibble)
weather <- nycflights13::weather %>% 
  select(origin, time_hour, temp, humid, precip)
weather_tsbl <- as_tsibble(weather, key = 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 can be comprised of empty, one, or more variables. See package?tsibble and vignette("intro-tsibble") for details.

The interval is computed from index based on the representation, ranging from year to nanosecond, from numerics to ordered factors. The table below shows how tsibble interprets the common time formats.

Interval Class
Annual integer/double
Quarterly yearquarter
Monthly yearmonth
Weekly yearweek
Daily Date/difftime
Subdaily POSIXt/difftime/hms

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

Often there are implicit missing cases in time series. If the observations are made at regular time interval, we could turn these implicit missingness 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_key() %>% 
  tidyr::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 in 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 index variable (referred to as .).

full_weather %>%
  group_by_key() %>%
  index_by(year_month = ~ yearmonth(.)) %>% # 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.

Learn more about tsibble

An ecosystem, the tidyverts, is built around the tsibble object for tidy time series analysis.

  • The tsibbledata package curates a range of tsibble data examples to poke around the tsibble object.
  • The feasts package provides support for visualising the data and extracting time series features.
  • The fable package provides common forecasting methods for tsibble, such as ARIMA and ETS. The fabletools package, which is fable built upon, lays the modelling infrastructure to ease the programming with tsibble.

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
as.ts.tbl_ts Coerce a tsibble to a time series
has_gaps Does a tsibble have implicit gaps in time?
key_drop_default Default value for .drop argument for key
measures Return measured variables
guess_frequency Guess a time frequency from other index objects
build_tsibble_meta Low-level & high-performance constructor for a tsibble object
as_tibble.tbl_ts Coerce to a tibble or data frame
key_data Keyed data
as_tsibble Coerce to a tsibble object
future_slide() Sliding window in parallel
future_stretch() Stretching window in parallel
tsibble Create a tsibble object
stretch Stretching window calculation
key Return key variables
stretch2 Stretching window calculation over multiple simultaneously
count_gaps Count implicit gaps
fill_gaps Turn implicit missing values into explicit missing values
new_tsibble Create a subclass of a tsibble
filter_index A shorthand for filtering time index for a tsibble
index Return index variable from a tsibble
new_data New tsibble data and append new observations to a tsibble
build_tsibble Low-level constructor for a tsibble object
new_interval Interval constructor for a tsibble
time_in If time falls in the ranges using compact expressions
unnest_tsibble Unnest a data frame consisting of tsibbles to a tsibble
holiday_aus Australian national and state-based public holiday
tourism Australian domestic overnight trips
index_by Group by time index and collapse with summarise()
interval Meta-information of a tsibble
tsibble-tidyverse Tidyverse methods for tsibble
reexports Objects exported from other packages
pedestrian Pedestrian counts in the city of Melbourne
partial_slider Partially splits the input to a list according to the rolling window size.
scan_gaps Scan a tsibble for implicit missing observations
tile_tsibble Perform tiling windows on a tsibble by row
index_valid Add custom index support for a tsibble
default_time_units Time units from tsibble's "interval" class used for seq(by = )
is.tsibble Deprecated functions
future_tile() Tiling window in parallel
yearmonth Represent year-month
update_tsibble Update key and index for a tsibble
slide2 Sliding window calculation over multiple inputs simultaneously
group_by_key Group by key variables
is_tsibble If the object is a tsibble
interval_pull Pull time interval from a vector
yearquarter Represent year-quarter
tile2 Tiling window calculation over multiple inputs simultaneously
slide Sliding window calculation
tiler Splits the input to a list according to the tiling window size.
tile Tiling window calculation
yearweek Represent year-week based on the ISO 8601 standard (with flexible start day)
tsibble-vctrs Internal vctrs methods
slide_tsibble Perform sliding windows on a tsibble by row
slider Splits the input to a list according to the rolling window size.
stretcher Split the input to a list according to the stretching window size.
stretch_tsibble Perform stretching windows on a tsibble by row
tsibble-package tsibble: tidy temporal data frames and tools
tsibble-scales tsibble scales for ggplot2
difference Lagged differences
is_duplicated Test duplicated observations determined by key and index variables
No Results!

Vignettes of tsibble

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

Last month downloads

Details

Type Package
License GPL-3
URL https://tsibble.tidyverts.org
BugReports https://github.com/tidyverts/tsibble/issues
VignetteBuilder knitr
RdMacros lifecycle
ByteCompile true
Encoding UTF-8
Language en-GB
LazyData true
RoxygenNote 7.1.1
NeedsCompilation no
Packaged 2020-07-24 10:10:13 UTC; earo
Repository CRAN
Date/Publication 2020-07-24 10:40:02 UTC

Include our badge in your README

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