augment_trends: Add trend columns to data frame

In trendseries: Extract Trends from Time Series

Add trend columns to data frame

Description

Pipe-friendly function that adds trend columns to a tibble or data.frame. Designed for exploratory analysis of monthly and quarterly economic time series. Supports multiple trend extraction methods and handles grouped data.

Usage

augment_trends(
  data,
  date_col = "date",
  value_col = "value",
  group_cols = NULL,
  group_vars = NULL,
  methods = "stl",
  frequency = NULL,
  suffix = NULL,
  window = NULL,
  smoothing = NULL,
  band = NULL,
  align = NULL,
  params = list(),
  .quiet = FALSE
)

Arguments

data	A data.frame, tibble, data.table, or tsibble containing the time series data. Tsibble support requires the optional tsibble package.
date_col	Name of the date column. Defaults to "date". Must be of class Date for data frames. For tsibbles, defaults to the index and must name that index when supplied.
value_col	Name of the value column(s). Defaults to "value". Must be numeric. A character vector of length > 1 is accepted; trends are extracted for each column and named ⁠trend_{method}_{col}⁠ (e.g. trend_stl_consumption).
group_cols	Optional grouping variables for multiple time series. Can be a character vector of column names. For tsibbles, defaults to the key and must match it when supplied.
group_vars	Deprecated. Use group_cols instead.
methods	Character vector of trend methods. Options: "hp", "bk", "cf", "ma", "stl", "loess", "spline", "poly", "bn", "ucm", "hamilton", "spencer", "henderson", "ewma", "wma", "triangular", "kernel", "kalman", "median", "gaussian". Default is "stl".
frequency	The frequency of the series. Supports values from 1 (annual) to 365 (daily). Auto-detected for data frames; a tsibble's yearmonth or yearquarter index supplies 12 or 4. A Date index uses the usual detection. Other tsibble index classes are not supported.
suffix	Optional suffix for trend column names. If NULL, uses method names.
window	Unified window/period parameter for moving average methods (ma, wma, triangular, stl, ewma, median, gaussian, henderson). Must be positive. If NULL, uses frequency-appropriate defaults. For EWMA, the window is converted to the smoothing factor via alpha = 2 / (window + 1). Cannot be used simultaneously with smoothing for EWMA method. For ma, median, and henderson methods, a numeric vector is accepted (e.g., c(9, 13, 23)), which adds one column per window value named trend_henderson_9, trend_henderson_13, etc. Other methods ignore extra values (with a warning).
smoothing	Unified smoothing parameter for smoothing methods (hp, loess, spline, ewma, kernel, kalman). For hp: use large values (1600+) or small values (0-1) that get converted. For EWMA: specifies the alpha parameter (0-1) for traditional exponential smoothing. Cannot be used simultaneously with window for EWMA method. For kernel: multiplier of optimal bandwidth (1.0 = optimal, <1 = less smooth, >1 = more smooth). For kalman: a finite, positive ratio of measurement to process noise (higher = more smoothing). An explicit noise variance in params determines the other variance from this ratio. If both variances are supplied, they take precedence over smoothing. Without a ratio, unspecified measurement and process variances default to 0.1 and 0.01 times the series variance. For others: typically 0-1 range.
band	Unified band parameter for bandpass filters (bk, cf). Provide as c(low, high): the shortest and longest cycle to remove, in periods of the series (months for monthly data). Both values must be positive. Defaults to cycles of 1.5 to 8 years: c(6, 32) for quarterly data, c(18, 96) for monthly, and c(2, 8) for annual.
align	Unified alignment parameter for moving average methods (ma, wma, triangular, gaussian). Valid values: "center" (default, uses surrounding values), "right" (causal, uses past values only), "left" (anti-causal, uses future values only). Note: triangular only supports "center" and "right". If NULL, uses "center" as default.
params	Optional list of method-specific parameters for fine control.
.quiet	If TRUE, suppress informational messages.

Details

This function is designed for monthly (frequency = 12) and quarterly (frequency = 4) economic data, and the defaults for each method follow the conventions for those frequencies.

For grouped data, the function applies trend extraction to each group separately, maintaining the original data structure while adding trend columns. For tsibbles, only Date, yearmonth, and yearquarter indices are supported; the existing missing-period rules apply after conversion to calendar dates.

Value

A tibble with original data plus trend columns named ⁠trend_{method}⁠ or ⁠trend_{method}_{suffix}⁠ if suffix is provided. Rows come back in the order they were supplied in. A tsibble input returns a tsibble with its index class and key preserved.

Examples

# Simple STL decomposition on quarterly GDP construction data
gdp_construction |> augment_trends(value_col = "index")

# Multiple smoothing methods with unified parameter
gdp_construction |>
  augment_trends(
    value_col = "index",
    methods = c("hp", "loess", "ewma"),
    smoothing = 0.3
  )

# Moving averages with unified window on monthly data
vehicles |>
  tail(60) |>
  augment_trends(
    value_col = "production",
    methods = c("ma", "wma", "triangular"),
    window = 8
  )

# Economic indicators with different methods
ibcbr |>
  tail(48) |>
  augment_trends(
    value_col = "index",
    methods = c("median", "kalman", "kernel"),
    window = 9,
    smoothing = 0.15
  )

# Moving average with right alignment (causal filter)
vehicles |>
  tail(60) |>
  augment_trends(
    value_col = "production",
    methods = "ma",
    window = 12,
    align = "right"
  )

# Advanced: fine-tune specific methods
electric |>
  tail(72) |>
  augment_trends(
    value_col = "consumption",
    methods = "median",
    window = 7
  )

# Multiple MA windows in a single call (adds trend_ma_3, trend_ma_6, trend_ma_12)
vehicles |>
  tail(60) |>
  augment_trends(
    value_col = "production",
    methods = "ma",
    window = c(3, 6, 12)
  )

# Preserve a tsibble's index and key (if tsibble is installed)
if (requireNamespace("tsibble", quietly = TRUE)) {
  quarterly <- gdp_construction
  quarterly$date <- tsibble::yearquarter(quarterly$date)
  quarterly <- tsibble::as_tsibble(quarterly, index = date)
  augment_trends(quarterly, value_col = "index", methods = "hp")
}

trendseries documentation built on Oct. 1, 2026, 5:10 p.m.