deseason_series: Seasonally adjust (deseason) a time series

In trendseries: Extract Trends from Time Series

Seasonally adjust (deseason) a time series

Description

Pipe-friendly convenience wrapper around decompose_series() focused on a single task: removing the seasonal component from a time series. It adds a ⁠seasadj_{method}⁠ column holding the seasonally adjusted (deseasoned) series and, optionally, the underlying trend, seasonal, and remainder components.

Usage

deseason_series(
  data,
  date_col = "date",
  value_col = "value",
  group_cols = NULL,
  methods = "stl",
  transform = "none",
  frequency = NULL,
  components = FALSE,
  params = list(),
  .quiet = FALSE
)

Arguments

data	A data.frame, tibble, or data.table containing the time series data.
date_col	Name of the date column. Defaults to "date". Must be of class Date.
value_col	Name of the value column. Defaults to "value". Must be numeric.
group_cols	Optional grouping variables for multiple time series. A character vector of column names. When provided, decomposition is applied independently to each group.
methods	Seasonal-adjustment method(s). One or more of "stl" (default) or "seats". When both are supplied, each contributes its own ⁠seasadj_{method}⁠ column (and component columns when components = TRUE) so the adjustments can be compared side by side. "stl": Seasonal-Trend decomposition via Loess (stats::stl()). "seats": X-13ARIMA-SEATS decomposition (requires the seasonal package; see decompose_series() for details).
transform	Transformation applied to the series before decomposition. One of "none" (default, additive decomposition) or "log". With "log", the series is log-transformed, decomposed additively, and the components are exponentiated back, yielding a multiplicative decomposition.
frequency	The frequency of the series. Must be greater than 1; "bsm" supports at most 12. Will be auto-detected if not specified.
components	If FALSE (default), only the seasonally adjusted ⁠seasadj_{method}⁠ column is added. If TRUE, the ⁠trend_{method}⁠, ⁠seasonal_{method}⁠, and ⁠remainder_{method}⁠ columns are also added (the full decompose_series() output).
params	Optional list of method-specific parameters for fine control. Every parameter has a default, so this argument is only needed for non-standard use cases. For STL (methods = "stl"): s.window or stl_s_window: seasonal smoothing window. Either "periodic" (default, assumes constant seasonal pattern) or a positive odd integer (larger values allow more slowly evolving seasonality). t.window or stl_t_window: trend smoothing window (odd integer, or NULL to let stats::stl() choose automatically — recommended default). robust or stl_robust: logical. If TRUE, uses robust fitting to reduce the influence of outliers. Default FALSE. For regression (methods = "regression"): poly_raw: logical. If FALSE (default), uses orthogonal polynomials (numerically stable, recommended). If TRUE, uses raw polynomials (more interpretable coefficients, less stable for degree >= 2). classic, bsm, and seats take no params. For multiplicative seasonality with any method, use transform = "log".
.quiet	If TRUE, suppress informational messages.

Details

deseason_series() is a thin wrapper: it calls decompose_series() with seasadj = TRUE and then keeps only the seasonally adjusted column unless components = TRUE. All seasonal-adjustment behaviour, validation, grouping, and the transform = "log" (multiplicative) path are inherited unchanged from decompose_series(). See its documentation for method internals and the meaning of the params argument.

For a full trend/seasonal/remainder decomposition, or for the regression, classic, and bsm methods, use decompose_series() directly.

Value

A tibble with the original columns plus, for each requested method, a ⁠seasadj_{method}⁠ column holding the seasonally adjusted series. When components = TRUE, the ⁠trend_{method}⁠, ⁠seasonal_{method}⁠, and ⁠remainder_{method}⁠ columns are added as well.

The seasonally adjusted series is the series with the seasonal component removed: trend + remainder for additive decompositions, trend * remainder when transform = "log". Output rows come back in the order they were supplied in.

See Also

decompose_series() for the underlying decomposition and the full set of methods; augment_trends() to extract a trend component only.

Examples

# Seasonally adjust a quarterly series (STL, the default)
gdp_construction |>
  deseason_series(value_col = "index")

# Also keep the trend, seasonal, and remainder components
gdp_construction |>
  deseason_series(value_col = "index", components = TRUE)

# Multiplicative adjustment via log transform (seasonal swings grow with level)
gdp_construction |>
  deseason_series(value_col = "index", transform = "log")

# X-13ARIMA-SEATS adjustment (requires the 'seasonal' package)
if (requireNamespace("seasonal", quietly = TRUE)) {
  gdp_construction |>
    deseason_series(value_col = "index", methods = "seats")
}

# Compare STL and SEATS adjustments side by side
if (requireNamespace("seasonal", quietly = TRUE)) {
  gdp_construction |>
    deseason_series(value_col = "index", methods = c("stl", "seats"))
}

# Grouped seasonal adjustment: one adjustment per electricity sector
electricity |>
  deseason_series(group_cols = "name_series")

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