Getting Started with trendseries

What is trendseries?

The trendseries package is a suite of four functions for analyzing the trend, seasonal, and cyclical structure of economic time series:

• augment_trends() fits a smooth trend to a series.
• decompose_series() splits a series into trend, seasonal, and remainder components.
• deseason_series() removes the seasonal component, returning a seasonally adjusted series.
• detrend_series() removes the trend, returning the deviation from trend — the cycle, or output gap.

All four share the same pipe-friendly data.frame interface, the same 20 underlying trend methods, and the same unified parameter system. Throughout this vignette (and the package documentation generally) the terms data.frame and “data frame” refer to any dataset in a rectangular format, i.e., data.frame/tibble/data.table.

Why trendseries?

Working with economic time series in R often involves cumbersome conversions between data frames and ts objects. Most filtering methods are designed for ts objects, but modern data analysis workflows use data.frame objects with a date column. Converting back and forth between ts and data.frame is tedious and error-prone.

The goal of trendseries is to provide a modern interface for exploratory analysis of time series data in conventional data.frame format, without giving up access to ts-native tools when you need them: every function has a ts/xts/zoo counterpart (extract_trends(), or the ts_col/df_to_ts() converters).

This package was designed with economic time series in mind. It includes methods commonly used in economics (e.g., Hodrick-Prescott, Hamilton, etc.) as well as general-purpose smoothing methods (e.g., LOESS, moving averages).

The four functions

Each function adds new columns to a data frame, named after the component and the method used (trend_stl, seasadj_stl, detrend_hp, etc.). The example below threads the same dataset — ibcbr, the Central Bank’s monthly index of Brazilian economic activity — through all four.

ggplot(ibcbr, aes(date, index)) +
  geom_line(linewidth = 0.7) +
  theme_minimal() +
  labs(title = "Brazilian economic activity (IBC-Br)", x = NULL, y = "Index")

augment_trends(): fit a trend

ibcbr_trend <- augment_trends(ibcbr, value_col = "index", methods = "stl")

head(ibcbr_trend)
#> # A tibble: 6 × 3
#>   date       index trend_stl
#>   <date>     <dbl>     <dbl>
#> 1 2003-01-01  67.1      70.2
#> 2 2003-02-01  68.8      70.2
#> 3 2003-03-01  72.2      70.3
#> 4 2003-04-01  71.3      70.4
#> 5 2003-05-01  70.0      70.5
#> 6 2003-06-01  68.8      70.7

decompose_series(): split into trend, seasonal, and remainder

ibcbr_parts <- decompose_series(ibcbr, value_col = "index")

head(ibcbr_parts)
#> # A tibble: 6 × 5
#>   date       index trend_stl seasonal_stl remainder_stl
#>   <date>     <dbl>     <dbl>        <dbl>         <dbl>
#> 1 2003-01-01  67.1      70.2       -4.31         1.25  
#> 2 2003-02-01  68.8      70.2       -3.61         2.22  
#> 3 2003-03-01  72.2      70.3        3.50        -1.65  
#> 4 2003-04-01  71.3      70.4        0.159        0.726 
#> 5 2003-05-01  70.0      70.5       -0.473       -0.0703
#> 6 2003-06-01  68.8      70.7       -0.826       -1.05

deseason_series(): remove seasonality

ibcbr_sa <- deseason_series(ibcbr, value_col = "index")

head(ibcbr_sa)
#> # A tibble: 6 × 3
#>   date       index seasadj_stl
#>   <date>     <dbl>       <dbl>
#> 1 2003-01-01  67.1        71.4
#> 2 2003-02-01  68.8        72.5
#> 3 2003-03-01  72.2        68.7
#> 4 2003-04-01  71.3        71.1
#> 5 2003-05-01  70.0        70.5
#> 6 2003-06-01  68.8        69.6

detrend_series(): extract the cycle

ibcbr_cycle <- detrend_series(ibcbr, value_col = "index")

head(ibcbr_cycle)
#> # A tibble: 6 × 3
#>   date       index detrend_hp
#>   <date>     <dbl>      <dbl>
#> 1 2003-01-01  67.1     -1.93 
#> 2 2003-02-01  68.8     -0.482
#> 3 2003-03-01  72.2      2.53 
#> 4 2003-04-01  71.3      1.37 
#> 5 2003-05-01  70.0     -0.250
#> 6 2003-06-01  68.8     -1.75

extract_trends(): the ts-native interface

Every trend method reachable through augment_trends() is also reachable through extract_trends(), which takes ts/xts/zoo objects instead of data frames and returns them, for users who prefer to stay in base R’s time series ecosystem.

stl_trend <- extract_trends(AirPassengers, methods = "stl")
plot.ts(AirPassengers)
lines(stl_trend, col = "#C53030")

Where to go next

This vignette is intentionally just a map. Each function has its own vignette with worked examples, parameter details, and guidance on choosing between methods:

Vignette	Covers
Augmenting Trends	augment_trends()/extract_trends(): grouping, multiple methods, finer control
Decomposing Series	decompose_series()/deseason_series(): trend/seasonal/remainder splits
Detrending Series	detrend_series(): cycles, output gaps, the deseason-then-detrend workflow
Trend Extraction Methods	Catalogue of all 20 trend methods, by family
Moving Averages	SMA, WMA, EWMA, Triangular, Median, Gaussian, Spencer, Henderson
Econometric Filters	HP, BK, CF, Hamilton, Beveridge-Nelson, UCM

Acknowledgements

This package was inspired by the need for a simpler workflow for trend extraction in R. It builds upon many existing packages, including:

• mFilter for economic filters.
• hpfilter for Hodrick-Prescott filtering.
• tsbox for time series conversions.

Getting Help

If you run into issues:

• Check the documentation: ?augment_trends, ?decompose_series, ?deseason_series, ?detrend_series
• View examples: example(augment_trends)
• Read other vignettes: vignette(package = "trendseries")
• Report bugs: GitHub issues