Getting Started with trendseries
In trendseries: Extract Trends from Time Series

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 7,
  fig.height = 4.5,
  fig.align = "center",
  message = FALSE,
  warning = FALSE
)

#| include: false
library(trendseries)
library(ggplot2)
library(ekioplot)

series_palette <- unname(c(
  ekio_pal("blue")["700"],
  ekio_pal("blue")["400"],
  ekio_pal("teal")["600"]
))
highlight_orange <- unname(ekio_pal("orange")["400"])

What is trendseries?

trendseries is a pipe-friendly interface to 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 (a.k.a. the cycle, or output gap).
index_series() rescales one or more series to a common base period and value.

All five share the same pipe-friendly data.frame interface, the same 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?

Most filtering methods in R are designed for ts objects, but analysis workflows use data frames with a date column. Converting back and forth is tedious and error-prone. trendseries works on data frames throughout, and keeps the ts-native interface available for when you need it.

The package sources filtering and smoothing functions across different packages and provides a unified interface when possible. The methods are the ones applied to economic series — Hodrick-Prescott, Hamilton, Beveridge-Nelson, Henderson, Spencer, and moving averages, among others — alongside general-purpose smoothers such as STL and loess.

A simple example

Each function works by adding columns to the data frame, named after the component and the method used (trend_stl, seasadj_stl, detrend_hp, etc.). The examples below use the IBC-Br series (ibcbr), the Brazilian Central Bank's monthly index of economic activity.

augment_trends() fits a smooth trend to a series and returns it as a new column.

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

head(ibcbr_trend)

ggplot(ibcbr_trend, aes(date)) +
  geom_line(aes(y = index, color = "Original"), linewidth = 0.5, alpha = 0.5) +
  geom_line(aes(y = trend_stl, color = "Trend (STL)"), linewidth = 0.7) +
  scale_color_manual(
    values = c("Original" = series_palette[[1]], "Trend (STL)" = highlight_orange)
  ) +
  labs(
    title = "Brazilian economic activity (IBC-Br)",
    x = NULL,
    y = "Index",
    color = NULL
  ) +
  theme_ekio(background = "white") +
  theme(legend.position = "bottom")

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 = highlight_orange)

Indexing series

Use index_series() to compare series on a common base. By default it uses the earliest non-missing observation; base_period can instead select a year or a date range and use its mean as the reference value. If the first dated value is missing, the function warns when it moves the base to a later observation.

ibcbr_indexed <- ibcbr |>
  index_series(value_col = "index", base_period = 2019)

head(ibcbr_indexed)

The function also calculates separate references for grouped data and supports multiple value columns. To select a different base date for each group, pass the name of a Date column to base_period. Each group must have one non-missing date in that column.

Where to go next

Each function has its own article on the package website with worked examples, parameter details, and guidance on choosing between methods.

| Article | 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 the trend methods | | Moving Averages | SMA, WMA, EWMA, Triangular, Median, Gaussian, Spencer, Henderson | | Econometric Filters | HP, BK, CF, Hamilton, Beveridge-Nelson, UCM |

Acknowledgements

trendseries builds on existing packages.

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

Getting Help

Check the documentation: ?augment_trends, ?decompose_series, ?deseason_series, ?detrend_series, ?index_series
View examples: example(augment_trends)
Browse the articles: https://viniciusoike.github.io/trendseries/articles/
Report bugs: GitHub issues