Package {rjd3highfreq}

Type:	Package
Title:	Seasonal Adjustment of High Frequency Data with 'JDemetra+ 3.x'
Version:	3.0.1
Description:	R interface to 'JDemetra+ 3.x' (https://github.com/jdemetra), the time series analysis software. It provides functions for seasonal adjustment of higher-frequency data, including those with multiple or non-integer periodicities. It includes pre-adjustment via the extended airline model and several seasonal decomposition methods: extended airline model based decomposition, extended X-11, and augmented STL.
Depends:	R (≥ 4.1.0)
Imports:	rJava (≥ 1.0-6), rjd3toolkit (≥ 3.7.1), rjd3xjars (≥ 0.1.0)
SystemRequirements:	Java (>= 21)
License:	EUPL-1.2
URL:	https://github.com/rjdverse/rjd3highfreq/, https://rjdverse.github.io/rjd3highfreq/
Suggests:	knitr, rmarkdown, testthat
BugReports:	https://github.com/rjdverse/rjd3highfreq/issues
VignetteBuilder:	knitr
Encoding:	UTF-8
Collate:	'auxiliaries.R' 'ic_r.R' 'jd3_extendedairline.R' 'jd3_fractionalairline.R' 'jd3_stl.R' 'jd3_x11.R' 'plot.R' 'print.R' 'summary.R' 'x11correction.R' 'zzz.R'
Config/roxygen2/version:	8.0.0
NeedsCompilation:	no
Packaged:	2026-10-12 05:07:16 UTC; s3504do
Author:	Jean Palate [aut], Daniel Ollech [cre, ctb], Christiane Hofer [ctb], Witthohn Thomas [ctb], Lea Hengen [ctb], Martin Stefan [ctb], Alessandro Piovani [ctb], Tanguy Barthelemy [ctb, art], Karsten Webel [ctb] (method: X-11 method)
Maintainer:	Daniel Ollech <daniel.ollech@bundesbank.de>
Repository:	CRAN
Date/Publication:	2026-10-21 16:10:02 UTC

Extract an ARIMA model from a Java object

Description

This internal function retrieves the ARIMA specification associated with a given path in a Java object. It extracts the model structure (description string, AR/MA polynomials, differencing order) and the innovation variance, and returns them as an R 'arima_model' object.

Usage

.arima_extract(jrslt, path)

Arguments

Value

An 'arima_model' object as constructed by 'rjd3toolkit::arima_model()'.

Estimate an Extended Airline RegARIMA model

Description

This function combines the three main Extended Airline steps:

Usage

.estimate_extended_airline(
  series,
  period,
  differencing = -1,
  ar = FALSE,
  to_int = FALSE,
  mean = FALSE,
  xreg = NULL,
  eps = 1e-09,
  deps = 1e-09,
  exact_hessian = FALSE
)

Arguments

Details

1. create an Extended Airline specification, 2. initialise a RegARIMA model, 3. estimate the model parameters.

The Java estimation result is post-processed so that selected vector components, such as the input series and full residuals, are returned as regular R vectors.

Value

A list with elements:

spec

The Java ExtendedAirlineSpec object.

regarima

The initialised Java RegArimaModel object.

estimation

A formatted R list containing extracted estimation components.

estimation_raw

The original raw Java estimation object.

Estimate parameters of an Extended Airline RegARIMA model

Description

This internal function performs maximum likelihood estimation of an Extended Airline model that has been previously specified and initialized.

Usage

.extended_airline_estimation(
  jregarima,
  jspec,
  eps = 1e-09,
  deps = 1e-09,
  exact_hessian = FALSE
)

Arguments

Value

A list object containing detailed estimation results.

Create a RegARIMA model based on an Extended Airline specification

Description

This internal function constructs a Java RegArimaModel object by fitting an Extended Airline model.

Usage

.extended_airline_regarima(series, jspec, mean = FALSE, xreg = NULL)

Arguments

Value

A Java object of class RegArimaModel from the JDemetra+ toolkit.

Create a specification for the Extended Airline model

Description

This internal function constructs a Java ExtendedAirlineSpec object. The Extended Airline model is an extension of the classic seasonal ARIMA model that can handle multiple simultaneous periods.

Usage

.extended_airline_spec(period, differencing = -1, ar = FALSE, to_int = FALSE)

Arguments

Value

A Java object of class ExtendedAirlineSpec.

Convert a raw fractional airline decomposition to an R-friendly object

Description

This function takes a Java object returned by fractionalAirlineDecomposition_raw() and converts it into a structured R object of class JDFractionalAirlineDecomposition. The result includes the estimated Ucarima model, the decomposition components, standard errors (optional), parameter estimates, and likelihood diagnostics.

Usage

.jd2r_fractional_airline_decomposition(
  jrslt,
  sn = FALSE,
  stde = FALSE,
  period,
  log = FALSE,
  series_time = NULL
)

Arguments

Value

An object of class JDFractionalAirlineDecomposition containing:

• ucarima: the Ucarima model with its components,

• decomposition: list of original series, seasonally adjusted series, and components (trend, irregular, seasonal), with optional standard deviations,

• estimation: estimated parameters, covariance matrix, and score,

• likelihood: likelihood diagnostics.

Convert a raw multi-period AMB decomposition to an R-friendly object

Description

This function takes a Java object returned by multiAirlineDecomposition_raw() and converts it into a structured R object of class JDFractionalAirlineDecomposition. The result includes the estimated Ucarima model, the decomposition components, standard errors (optional), parameter estimates, and likelihood diagnostics.

Usage

.jd2r_multi_airline_decomposition(
  jrslt,
  stde = FALSE,
  period,
  log = FALSE,
  series_time = NULL
)

Arguments

Value

An object of class JDFractionalAirlineDecomposition containing:

• ucarima: the Ucarima model with its components,

• decomposition: list of original series, seasonally adjusted series, and component time series (with optional standard deviations),

• estimation: estimated parameters, covariance matrix, and score,

• likelihood: likelihood diagnostics.

Convert an R numeric vector to a Java DoubleSeq object

Description

This internal helper function converts an R object to a Java DoubleSeq object from the JDemetra+ toolkit.

Usage

.r2jd_doubleseq(x)

Arguments

Details

The input is first coerced to numeric using as.numeric() and is then passed to the static Java factory method DoubleSeq.of().

This function is mainly intended for internal use when passing numeric R vectors to Java methods that expect a DoubleSeq.

Value

A Java object of class jdplus.toolkit.base.api.data.DoubleSeq.

Extract a specific UCM component from a Java UcarimaModel object

Description

This internal function retrieves a single component from a UCM (Unobserved Components Model) result object returned by the Java backend. The component can be specified either by name or by its integer code.

Usage

.ucm_extract(jrslt, cmp)

Arguments

Value

The requested component extracted from the UCM result.

Perform an X-11 like decomposition with any (non-integer) periodicity.

Description

Perform an X-11 like decomposition with any (non-integer) periodicity.

Usage

.x11plus_default(
  series,
  period,
  multiplicative = TRUE,
  trend_horizon = 6,
  trend_degree = 3,
  trend_kernel = c("Henderson", "BiWeight", "TriWeight", "TriCube", "Uniform",
    "Triangular", "Epanechnikov", "Trapezoidal"),
  trend_asymmetric = c("CutAndNormalize", "Direct", "MMSRE"),
  seas_s0 = c("S3X3", "S3X1", "S3X5", "S3X9", "S3X15"),
  seas_s1 = c("S3X5", "S3X3", "S3X1", "S3X9", "S3X15"),
  extreme_lsig = 1.5,
  extreme_usig = 2.5,
  user_defined = NULL
)

Arguments

Details

If trend_coefs are provided, the other trend-settings are ignored and .x11plus_trend() is run.

Value

An object of the class 'hf_decomposition', containing the decomposition and the parameters

X-11 Decomposition With Custom Trend Filters

Description

Perform the X-11 decomposition using custom trend filter

Usage

.x11plus_trend(
  series,
  period = stats::frequency(series),
  trend_coefs,
  multiplicative = TRUE,
  seas_s0 = c("S3X3", "S3X1", "S3X5", "S3X9", "S3X15"),
  seas_s1 = c("S3X5", "S3X3", "S3X1", "S3X9", "S3X15"),
  extreme_lsig = 1.5,
  extreme_usig = 2.5,
  user_defined = NULL
)

Arguments

Check whether the installed Java version is supported

Description

Checks whether the Java executable found through JAVA_HOME or PATH satisfies the minimum Java version required by the package.

Usage

check_java_version(silent = TRUE, startup = TRUE)

Arguments

Details

If the installed Java version is equal to or greater than the required version, the function returns TRUE. Otherwise, it returns FALSE and, unless suppressed, displays a diagnostic message.

Value

A logical scalar. TRUE indicates that Java 21 or newer was found. FALSE indicates that Java was not found, its version could not be determined, or its version is older than Java 21.

'X11' Extreme Values Corrector

Description

'X11' Extreme Values Corrector

Usage

extreme_values_correction(
  series,
  period,
  corrected_s,
  lsigma = 1.5,
  usigma = 2.5,
  multiplicative = FALSE,
  start = 0,
  clean_extremities = TRUE
)

Arguments

Details

The 'X11' Extreme Values Corrector is used to compute the tables b4, b4g, b9, b9g, b17, b20, c17 and c20.

#' The returned correction contains the following columns:

obs_weight

Extreme value corrections weight of each observation

correction_factors

Extreme value correction factors

Value

A numeric matrix with two columns, obs_weight and correction_factors. If series is a ts object, the result is returned as a multivariate ts object with the corresponding time attributes. The number of rows corresponds to the observations in series.

Examples

extreme_values_correction(rjd3toolkit::ABS$X0.2.09.10.M, 12)

Outlier Detection for Extended Airline Models

Description

This internal function performs automatic outlier detection in high-frequency time series using Extended Airline models.

Usage

find_outliers(
  input,
  types = c("AO"),
  start = 0,
  end = 0,
  critical_value = 0,
  max_outliers = 30,
  max_round = 30,
  precision = 1e-05,
  deps = 1e-04
)

Arguments

Value

A numeric matrix with dimensions [number of outliers detected × 2].

References

Outlier critical value using the Ljung algorithm as given in Ljung, G. M. (1993). On outlier detection in time series. Journal of Royal Statistical Society B 55, 559-567. Solution proposed by Brian Monsell (LBS), January 2022

Examples

series <- rjd3toolkit::Exports$Malta
find_outliers(series, critical_value = 3.5, types = c("LS", "WO"))

Perform an Arima Model Based (AMB) decomposition

Description

Performs an Arima Model Based (AMB) decomposition using a (fractional) airline model, suitable for high-frequency time series. The method decomposes the input series into trend, seasonal and irregular components, with optional signal–noise decomposition.

Usage

fractional_airline_decomposition(
  series,
  period,
  sn = FALSE,
  stde = FALSE,
  nbcasts = 0,
  nfcasts = 0,
  eps = 1e-09,
  deps = 1e-04,
  log = FALSE,
  series_time = NULL
)

Arguments

Details

If 'sn = TRUE', the decomposition is restricted to two components only (signal and noise). When 'stde = TRUE', the computation of standard deviations may fail for long series or high-frequency data due to memory constraints.

Value

An object containing the AMB decomposition results, including the estimated components and, if requested, their standard deviations.

Examples

series <- rnorm(70)+100

### Example with a daily time series with a day-of-the-week effect
weekday <- rjd3highfreq::fractional_airline_decomposition(
  series,
  period = 7,
  log = TRUE,
  series_time = seq.Date(from=as.Date("2025-01-01"),
                         by = "days",
                         length.out = length(series))
)

### Example with a weekly time series
series <-  rnorm(200)+100
weekly <- rjd3highfreq::fractional_airline_decomposition(
  series,
  period = 52.18,
  log =  TRUE,
  series_time = seq.Date(from=as.Date("2025-01-01"),
                         by = "days",
                         length.out = length(series))
)

Linearize a time series using a fractional airline model

Description

This function estimates a (fractional) airline RegARIMA model and returns the linearized series together with regression effects, outlier components, estimation results and likelihood diagnostics. It is typically used as a preprocessing step prior to AMB or UCM-based decompositions.

Usage

fractional_airline_estimation(
  series,
  period,
  xreg = NULL,
  ndiff = 2,
  ar = FALSE,
  mean = FALSE,
  outliers = NULL,
  critical_value = 6,
  precision = 1e-12,
  deps = 1e-04,
  approximate_hessian = FALSE,
  nfcasts = 0,
  log = FALSE,
  series_time = NULL
)

Arguments

Details

Automatic outlier detection can be enabled by specifying the outlier types and a critical value for the detection threshold.

Value

An object of class "hf_estimation" containing:

• the original and linearized series,

• estimated regression effects and outlier components,

• model parameters and covariance matrices,

• likelihood and diagnostic information.

Examples

# Simulated examples with and without regressor
set.seed(125)
reg <- data.frame(
   reg1 = round(runif(1000, min = 0, max = 1))*2-1,
 reg2 = round(runif(1000, min = 0, max = 1))*2-1
)

y = 100 + 2*reg$reg1 -2*reg$reg2 + rnorm(nrow(reg))

# input data
data <- list(
   series = y,
   date = seq.Date(from = as.Date("2020-01-01"),
   by = "day",
                   length.out = 1000)
)

# Linearize the series using weekly and annual periodicities
est <- fractional_airline_estimation(
   data$series,
   period = c(7, 30.4),
   log = FALSE,
   xreg = reg,
   series_time = data$date
)

est

est2 <- fractional_airline_estimation(
  data$series,
  period = c(7, 30.4),
  log = FALSE,
  series_time = data$date
)

est2

Apply Henderson linear filter

Description

Apply Henderson linear filter

Usage

henderson(series, length, musgrave = TRUE, ic = 4.5)

Arguments

Value

A numeric array corresponding to the estimated trend.

Examples

q <- x11plus(rjd3toolkit::ABS$X0.2.09.10.M, 12)

henderson(q$decomposition$sa, 13)

Compute IC-Ratio

Description

Compute IC-Ratio

Usage

ic_ratio(
  series,
  frequency = NULL,
  trend_length = NULL,
  musgrave = FALSE,
  multiplicative = FALSE,
  seasonally_adjust = TRUE,
  sma = "S3X5",
  ...
)

Arguments

Details

In the traditional calculation of the IC-ratio, no asymmetric filters used for the preliminary trend estimation (see Ladiray and Quenneville 2001, Table B7).

Value

A numeric. The IC-ratio.

References

Ladiray, D., Quenneville, B. (2001). The Various Tables. In: Seasonal Adjustment with the X-11 Method. Lecture Notes in Statistics, vol 158. Springer, New York, NY. doi:10.1007/978-1-4613-0175-2_5

Examples

series <- rjd3toolkit::Retail$AllOtherGenMerchandiseStores
ic_ratio(series)

Iterative multiple seasonal decomposition using ISTL

Description

Performs an iterative stlplus-type decomposition for time series with multiple seasonal periods. This function provides an R interface to the JD+ Java implementation. It decomposes a time series into a trend component, several seasonal components, and an irregular component using an iterative STL-based procedure.

Usage

istl(
  series,
  period,
  multiplicative = TRUE,
  swindow = NULL,
  twindow = NULL,
  robust = NULL,
  ninnerloop = 1,
  nouterloop = 15,
  nojump = FALSE,
  weight_threshold = 0.001,
  weight_function = c("biweight", "uniform", "triangular", "epanechnikov", "tricube",
    "triweight")
)

Arguments

Details

The returned decomposition contains the following columns:

series

The original input series.

sa

The seasonally adjusted series (trend+irregular for additive, trend*irregular for multiplicative decomposition).

t

The trend component.

s<period>

One seasonal component for each value supplied in period. For example, if period = c(7, 365), the output contains columns s7 and s365.

i

The irregular component.

fit

The fitted values from the decomposition (trend+seasonal for additive, trend*seasonal for multiplicative decomposition).

weights

The final robust weights.

If multiplicative = TRUE, the decomposition is interpreted as a multiplicative decomposition. If multiplicative = FALSE, it is interpreted as an additive decomposition.

If robust = TRUE, the parameters nouterloop and ninnerloop are overwritten, so that 15 iterations of the outer loop and one run of the inner loop are completed. If robust = FALSE, nouterloop is set to 0, and ninnerloop is set to 2.

Value

An object of class "hf_decomposition", consisting of a list with two elements:

decomposition

A data.frame containing the original series, the seasonally adjusted series, the trend, one seasonal component for each period, the irregular component, fitted values and robust weights.

parameters

A list containing the main parameters used for the decomposition.

See Also

stlplus, mstl, plot.hf_decomposition

Examples

q <- istl(
  series = rjd3toolkit::ABS$X0.2.09.10.M,
  period = c(12, 19)
)

plot(q)

Fit a LOESS smoother

Description

Applies a LOESS smoother to a numeric time series.

Usage

loess(series, window, degree = 1, jump = 0)

Arguments

Details

This function provides a simple R interface to the JD+ Java implementation of the LOESS smoother used internally by the stlplus decomposition routines. It smoothes the input series using a local polynomial of degree 0 or 1.

This function is not the same as loess from the stats package. It does not use a formula interface and is intended for smoothing a single numeric series with the JD+ stlplus|loess implementation. Also, it can handle time series with missing values.

Value

A numeric vector containing the smoothed series.

See Also

stlplus, mstl, istl, loess

Examples

q <- stlplus(
  series = rjd3toolkit::ABS$X0.2.09.10.M,
  period = 12
)

trend <- q$decomposition[, "t"]

smoothed_trend <- loess(
  series = trend,
  window = 121
)

ts.plot(
  cbind(trend, smoothed_trend),
  col = c("black", "red")
)

Log-Level test for Extended Airline Models

Description

This function performs a statistical test to determine whether data should be transformed to logarithmic scale or kept in level (original scale)

Usage

loglevel(input, precision = 1e-05, deps = 1e-04)

Arguments

Value

An object containing the log-level test results. First the AICc of the model in levels and then the AICc of the model with logs

Examples

series <- rjd3toolkit::Retail$BookStores

loglevel(series)

Simultaneous, multiple seasonal decomposition using MSTL

Description

Performs an stlplus-type decomposition for time series with multiple seasonal periods. This function provides an R interface to the JD+ Java implementation.. It simultaneously decomposes a time series into a trend component, several seasonal components, and an irregular component.

Usage

mstl(
  series,
  period,
  multiplicative = TRUE,
  swindow = NULL,
  twindow = 0,
  robust = NULL,
  ninnerloop = 1,
  nouterloop = 15,
  nojump = FALSE,
  weight_threshold = 0.001,
  weight_function = c("biweight", "uniform", "triangular", "epanechnikov", "tricube",
    "triweight")
)

Arguments

Details

The returned decomposition contains the following columns:

series

The original input series.

sa

The seasonally adjusted series (trend+irregular for additive, trend*irregular for multiplicative decomposition).

t

The trend component.

s<period>

One seasonal component for each value supplied in period. For example, if period = c(7, 365), the output contains columns s7 and s365.

i

The irregular component.

fit

The fitted values from the decomposition (trend+seasonal(s) for additive, trend*seasonal(s) for multiplicative decomposition).

weights

The final robust weights.

If multiplicative = TRUE, the decomposition is interpreted as a multiplicative decomposition. If multiplicative = FALSE, it is interpreted as an additive decomposition.

If robust = TRUE, the parameters nouterloop and ninnerloop are overwritten, so that 15 iterations of the outer loop and one run of the inner loop are completed. If robust = FALSE, nouterloop is set to 0, and ninnerloop is set to 2.

Value

An object of class "hf_decomposition", consisting of a list with two elements:

decomposition

A data.frame containing the original series, the seasonally adjusted series, the trend, one seasonal component for each period, the irregular component, fitted values and robust weights.

parameters

A list containing the main parameters used for the decomposition.

See Also

stlplus, plot.hf_decomposition

Examples

q <- mstl(
  series = rjd3toolkit::ABS$X0.2.09.10.M,
  period = c(12, 19)
)

plot(q)

Perform an Arima Model Based (AMB) decomposition with multiple periodicities

Description

This function performs an AMB decomposition based on (fractional) airline models allowing for multiple seasonal periodicities at once. It is intended for high-frequency time series where more than one seasonal cycle may be present (e.g. weekly and annual effects).

Usage

multi_airline_decomposition(
  series,
  period,
  ndiff = 2,
  ar = FALSE,
  stde = FALSE,
  nbcasts = 0,
  nfcasts = 0,
  eps = 1e-09,
  deps = 1e-04,
  log = FALSE,
  series_time = NULL
)

Arguments

Details

If a single period is supplied, the function falls back to fractional_airline_decomposition().

Value

A decomposition object containing the estimated components for each periodicity. If multiple periods are provided, a multi-period decomposition is returned.

Examples

series <- rnorm(200)+100
dual_season <- multi_airline_decomposition(
  series,
  period = c(7, 30.4),
  log = TRUE,
  series_time = seq.Date(from=as.Date("2025-01-01"),
                         by = "days",
                         length.out = length(series))
)

Plot method for hf_decomposition objects

Description

Plot method for hf_decomposition objects

Usage

## S3 method for class 'hf_decomposition'
plot(
  x,
  ...,
  col_bg = "white",
  col_grid = "#777777",
  col_labels = "#777777",
  col_1 = "#debc12",
  col_2 = "#74b6d6",
  col_3 = "#ee2c2c"
)

Arguments

Value

NULL, returned invisibly. The function is called for its side effect of producing a decomposition plot.

Plot method for hf_estimation objects

Description

Plot method for hf_estimation objects

Usage

## S3 method for class 'hf_estimation'
plot(
  x,
  ...,
  col_bg = "#ffffe0",
  col_grid = "#777777",
  col_labels = "#777777",
  col_1 = "#debc12",
  col_2 = "#74b6d6"
)

Arguments

Value

x, invisibly.

Print method for hf_decomposition objects

Description

Print method for hf_decomposition objects

Usage

## S3 method for class 'hf_decomposition'
print(x, digits = 3L, ...)

Arguments

Value

x, invisibly.

Print method for hf_estimation objects

Description

Print method for hf_estimation objects

Usage

## S3 method for class 'hf_estimation'
print(x, digits = 3L, ...)

Arguments

Value

x, invisibly.

Seasonal decomposition using STL+

Description

Performs an STL-like seasonal decomposition. It can handle missing values and does allow a multiplicative decomposition.

Usage

stlplus(
  series,
  period,
  multiplicative = TRUE,
  swindow = 7,
  twindow = 0,
  lwindow = 0,
  sdegree = 0,
  tdegree = 1,
  ldegree = 1,
  sjump = 0,
  tjump = 0,
  ljump = 0,
  robust = NULL,
  ninnerloop = 1,
  nouterloop = 15,
  weight_threshold = 0.001,
  weight_function = c("biweight", "uniform", "triangular", "epanechnikov", "tricube",
    "triweight"),
  legacy = FALSE
)

Arguments

Details

This function provides an R interface to the JD+ Java implementation of STL decomposition. It decomposes a time series into trend, seasonal and irregular components and returns the result as an object of class "hf_decomposition".

The returned decomposition contains the following columns:

series

The original input series.

sa

The seasonally adjusted series (trend+irregular for additive, trend*irregular for multiplicative decomposition).

t

The trend component.

s

The seasonal component.

i

The irregular component.

fit

The fitted values from the decomposition (trend+seasonal(s) for additive, trend*seasonal(s) for multiplicative decomposition).

weights

The final robust weights.

If multiplicative = TRUE, the decomposition is interpreted as a multiplicative decomposition. If multiplicative = FALSE, it is interpreted as an additive decomposition.

If robust = TRUE, the parameters nouterloop and ninnerloop are overwritten, so that 15 iterations of the outer loop and one run of the inner loop are completed. If robust = FALSE, nouterloop is set to 0, and ninnerloop is set to 2.

Value

An object of class "hf_decomposition", consisting of a list with two elements:

decomposition

A data.frame containing the original series, the seasonally adjusted series, the trend, seasonal and irregular components, fitted values and robust weights (see details).

parameters

A list containing the main parameters used for the decomposition.

See Also

plot.hf_decomposition

Examples

decomp <- stlplus(
  series = rjd3toolkit::ABS$X0.2.09.10.M,
  period = 12
)

plot(decomp)

Summary method for hf_decomposition objects

Description

Summary method for hf_decomposition objects

Usage

## S3 method for class 'hf_decomposition'
summary(object, digits = 3L, ...)

Arguments

Value

object, invisibly.

Summary method for JDFractionalAirlineEstimation objects

Description

Summary method for JDFractionalAirlineEstimation objects

Usage

## S3 method for class 'hf_estimation'
summary(object, digits = 3L, ...)

Arguments

Value

object, invisibly.

Modified X-11 seasonal adjustment

Description

This function implements a modified version of the classical X-11 seasonal adjustment approach. The modified X-11 method is applicable to time series with arbitrary seasonal periodicity.

Usage

x11plus(
  series,
  period,
  multiplicative = TRUE,
  trend_horizon = 6,
  trend_degree = 3,
  trend_kernel = c("Henderson", "BiWeight", "TriWeight", "TriCube", "Uniform",
    "Triangular", "Epanechnikov", "Trapezoidal"),
  trend_asymmetric = c("CutAndNormalize", "Direct", "MMSRE"),
  trend_coefs,
  seas_s0 = c("S3X3", "S3X1", "S3X5", "S3X9", "S3X15"),
  seas_s1 = c("S3X5", "S3X3", "S3X1", "S3X9", "S3X15"),
  extreme_lsig = 1.5,
  extreme_usig = 2.5,
  user_defined = NULL
)

Arguments

Details

The main novelty of the modified X-11 method is the implementation of advanced options for refined and final trend-cycle estimation (B7, C7, D7, and D12), generalising the use of classical Henderson filters. The following logic applies, see also Webel (2026) and Webel and Smyk (2024) for technical details:

• If trend_coefs is unspecified (default), then the local polynomial regression filters suggested in Proietti and Luati (2008) are applied. The underlying regression model, from which the symmetric trend-cycle filter arises, is further specified through the trend_horizon, trend_degree, and trend_kernel parameters:

  • 2 * trend_horizon + 1 is the number of observations to be considered in the local trend approximation and, hence, the length of the resulting symmetric trend-cycle filter.

  • trend_degree is the order of the polynomial in the local trend approximation.

  • trend_kernel is a kernel function that defines the sequence of non-negative weights in the objective function, which is then minimised with respect to the regression parameters.

  In addition, trend_asymmetric defines the method to be used for deriving the requisite asymmetric local polynomial regression filters. Three methods are currently available: the cut-and-normalise approach of Gasser and Müller (1979) (CutAndNormalize), the direct asymmetric filters suggested in Proietti and Luati (2008) (Direct), and the minimum mean squared revision error approach developed in Grun-Rehomme et al. (2018) (MMSRE).

• If trend_coefs is specified, then all other parameters related to trend-cycle estimation are ignored, and the provided trend-cycle filter bank is applied. Note that the rjd3filters package can be used to create filters, e.g. by setting trend_coefs = rjd3filters::rkhs_filter().

Two final warnings regarding seasonal estimation.

1. Extremes in the seasonal-irregular component are currently corrected only in iterations B and C, where the moving irregular standard deviation is always calculated from 5-year moving windows. That is, no final replacement values (D9) are currently computed.

2. Users must specify seasonal filters seas_s0 and seas_s1 that match the length of series, as there is currently no automatic resetting of ill-specified seasonal filters. That is, any specification of seasonal filters that are too long for the given series will simply produce an error message.

Value

An object of class "hf_decomposition". It contains the specified parameters and a matrix that stores the input series and the final estimates of the seasonally adjusted series (D11), the trend-cyclical component (D12), the seasonal component (D10), and the irregular component (D13).

References

Dagum, E. B. and S. Bianconcini (2008). The Henderson Smoother in Reproducing Kernel Hilbert Space. Journal of Business and Economic Statistics 26 (4), 536–545. doi:10.1198/073500107000000322

Gasser, T. and H.-G. Müller (1979). Kernel Estimation of Regression Functions. In T. Gasser and M. Rosenblatt (Eds), Smoothing Techniques for Curve Estimation, 23–68. Heidelberg: Springer. doi:10.1007/BFb0098489

Grun-Rehomme, M., F. Guggemos and D. Ladiray (2018). Asymmetric Moving Averages Minimizing Phase Shift. In G. L. Mazzi, D. Ladiray and D. A. Riester (Eds), Handbook on Seasonal Adjustment, 391–413. Luxembourg: Publications Office of the European Union.

Proietti, T. and A. Luati (2008). Real Time Estimation in Local Polynomial Regression, with Application to Trend-Cycle Analysis. Annals of Applied Statistics 2 (4), 1523–1553. doi:10.1214/08-AOAS195

Webel, K. (2026). Some Thoughts on Modified X-11 Seasonal Adjustments for Time Series with Complex Seasonality. Deutsche Bundesbank Discussion Paper XX/2026. Forthcoming

Webel, K. and A. Smyk (2024). Seasonal Adjustment of Infra-Monthly Time Series with JDemetra+. Journal of Official Statistics 40 (4), 783–828. doi:10.1177/0282423X241277602

Examples

x11decomp  <- x11plus(
series = rjd3toolkit::ABS$X0.2.09.10.M,
period = 12,
trend_horizon = 99
)