Package {publishTC}

Type:	Package
Title:	Tools to Help to Publish the Trend-Cycle Component
Version:	0.2.3
Description:	Tools to facilitate the computation of the trend-cycle component of time series. In particular, the computation can be performed using: the Cascade Linear Filter ('CLF', Dagum and Luati, 2008), classical Henderson symmetric filters with surrogate Musgrave asymmetric filters, local parameterizations of Musgrave filters (Quartier-la-Tente, 2024), and robust extensions taking into account additive outliers and level shifts (Quartier-la-Tente, 2025). Computes confidence intervals and provides specialized plotting functions for publication.
LazyData:	true
Depends:	R (≥ 4.1.0)
Imports:	rJava, rjd3filters (≥ 2.4.0), rjd3x13 (≥ 3.3.0), ggplot2, zoo, rjd3jars (≥ 0.0.5)
URL:	https://github.com/AQLT/publishTC, https://aqlt.github.io/publishTC/
BugReports:	https://github.com/AQLT/publishTC/issues
SystemRequirements:	Java (>= 17)
License:	EUPL version 1.1 | EUPL version 1.2 [expanded from: EUPL]
Encoding:	UTF-8
Config/roxygen2/version:	8.1.0
NeedsCompilation:	no
Packaged:	2026-10-12 20:08:27 UTC; alainquartierlatente
Author:	Alain Quartier-la-Tente [aut, cre, cph]
Maintainer:	Alain Quartier-la-Tente <alain.quartier@yahoo.fr>
Repository:	CRAN
Date/Publication:	2026-10-21 17:30:02 UTC

Get Filter Bandwidth

Description

Retrieves the bandwidth of the filter used in a "tc_estimates" object.

Usage

bandwidth(x)

Arguments

Details

The bandwidth corresponds to the number of observations on each side of the central value for a symmetric trend-cycle filter. The total filter length is equal to 2 \times \text{bandwidth}(x) + 1.

Value

An integer representing the bandwidth of the trend-cycle filter.

Examples

x <- french_ipi[, "manufacturing"]
tc_clf <- henderson_smoothing(x)
bandwidth(tc_clf)

Classical Moving Averages

Description

Datasets containing coefficients of classical moving averages used for trend-cycle extraction.

Usage

henderson

CLF

CLF_CN

local_param_est

Format

henderson is a list of objects of class "moving_average".

CLF is an object of class "finite_filters".

CLF_CN is an object of class "finite_filters".

local_param_est is a nested list of objects of class "finite_filters". The first level corresponds to the length of the filter; the second level corresponds to the degree of the local polynomial model used for the trend-cycle; and the third level corresponds to the target component (1 for bias, 2 for slope, and 3 for curvature).

Details

• henderson: Henderson moving averages of lengths 5, 7, 9, 13, and 23.

• CLF: Cascade Linear Filter (CLF) of length 13 and associated Asymmetric Linear Filters (ALF).

• CLF_CN: Cascade Linear Filter (CLF) of length 13 and associated cut-and-normalize asymmetric filters.

• local_param_est: Moving averages used to locally estimate the bias, slope, or curvature associated with trend-cycle estimation (via local polynomial approximation).

References

Dagum, E. B., & Luati, A. (2008). A Cascade Linear Filter to Reduce Revisions and False Turning Points for Real Time Trend-Cycle Estimation. Econometric Reviews, 28(1-3), 40–59. doi:10.1080/07474930802387837

Henderson, R. (1916). Note on graduation by adjusted average. Transactions of the Actuarial Society of America, 17, 43–48.

Musgrave, J. (1964). A Set of End Weights to End All End Weights. US Census Bureau [Custodian]. https://www.census.gov/library/working-papers/1964/adrm/musgrave-01.html

Quartier-la-Tente, A. (2024). Improving Real-Time Trend Estimates Using Local Parametrization of Polynomial Regression Filters. Journal of Official Statistics, 40(4), 685–715. doi:10.1177/0282423X241283207

Trend-Cycle Estimation using the Cascade Linear Filter

Description

Estimates the trend-cycle component using the Cascade Linear Filter (CLF) of length 13.

Usage

clf_smoothing(x, endpoints = c("cut-and-normalize", "ALF"), ...)

Arguments

Value

An object of class c("tc_estimates", "clf"). See tc_estimates() for a full description of the returned object.

References

Dagum, E. B., & Luati, A. (2008). A Cascade Linear Filter to Reduce Revisions and False Turning Points for Real Time Trend-Cycle Estimation. Econometric Reviews 28(1-3), 40–59. doi:10.1080/07474930802387837

Examples

tc <- clf_smoothing(cars_registrations)
plot(tc, xlim = c(2022, 2025))

Plot Confidence Intervals for Trend-Cycle Estimates

Description

Base R (confint_plot()) and ggplot2 (ggconfint_plot()) graphics for plotting trend-cycle estimates alongside their confidence intervals.

Usage

confint_plot(
  object,
  xlim = NULL,
  ylim = NULL,
  col_tc = "#E69F00",
  col_sa = "black",
  col_confint = "grey",
  xlab = "",
  ylab = "",
  level = 0.95,
  ...
)

ggconfint_plot(
  object,
  xlim = NULL,
  ylim = NULL,
  col_tc = "#E69F00",
  col_sa = "black",
  col_confint = "grey",
  legend_tc = "Trend-cycle",
  legend_sa = "Seasonally adjusted",
  legend_confint = "Confidence interval",
  level = 0.95,
  ...
)

Arguments

Details

confint_plot() produces a base R graphic, whereas ggconfint_plot() creates a ggplot2 object that can be further customized. The confidence intervals are computed internally using confint().

Value

• confint_plot() returns NULL invisibly and is called for its side effect (drawing a plot).

• ggconfint_plot() returns a ggplot object.

Examples

tc_mod <- henderson_smoothing(french_ipi[, "manufacturing"])
confint_plot(tc_mod, xlim = c(2022, 2024.5))

Confidence Intervals for Trend-Cycle Estimates

Description

Computes confidence intervals for trend-cycle estimates of class "tc_estimates".

Usage

## S3 method for class 'henderson'
confint(object, parm, level = 0.95, asymmetric_var = TRUE, ...)

## S3 method for class 'clf'
confint(object, parm, level = 0.95, asymmetric_var = TRUE, ...)

## S3 method for class 'robust_henderson'
confint(object, parm, level = 0.95, asymmetric_var = TRUE, ...)

Arguments

Details

See rjd3filters::confint_filter() for details on the computation of confidence intervals.

Value

A matrix or mts object with the filtered series and the lower and upper bounds of the confidence interval.

Examples

x <- cars_registrations
tc <- henderson_smoothing(x)
confint <- confint(tc)

plot(confint, plot.type = "single",
	 col = c("red", "black", "black"),
	 lty = c(1, 2, 2), xlab = NULL, ylab = NULL)
lines(x, col = "grey")
legend("topleft", legend = c("x", "Smoothed", "CI (95%)"),
	   col= c("grey", "red", "black"), lty = c(1, 1, 2))

Plot Multiple Trend-Cycle Visualizations

Description

Generates a list of ggplot2 graphics displaying various diagnostic and comparative plots for a "tc_estimates" object.

Usage

ggsmoothing_plot(
  object,
  plots = c("normal", "confint", "lollypop", "implicit_forecasts",
    "underlying_forecasts"),
  level = 0.95,
  ...
)

Arguments

Details

The following plot types can be produced:

• "normal": Standard plot showing trend-cycle and seasonally adjusted series via autoplot.tc_estimates().

• "confint": Confidence interval plot via ggconfint_plot().

• "lollypop": Lollipop chart comparing estimates via gglollypop().

• "implicit_forecasts": Implicit forecasts plot via ggimplicit_forecasts_plot().

• "underlying_forecasts": Underlying forecasts plot via ggunderlying_forecasts_plot().

Value

A list of ggplot objects corresponding to the requested plots.

Examples

x <- cars_registrations
tc <- henderson_smoothing(x)
ggsmoothing_plot(tc)

Plot Growth Rates for Trend-Cycle Estimates

Description

Base R (growthplot()) and ggplot2 (gggrowthplot()) graphics for plotting the growth rates of the trend-cycle estimates (solid lines) and the seasonally adjusted series (bar-lines or lines).

Usage

growthplot(
  object,
  pct = TRUE,
  xlim = NULL,
  ylim = NULL,
  col_tc = "#E69F00",
  col_sa = "black",
  xlab = "",
  ylab = "",
  sa_bar_line = TRUE,
  ...,
  lag = -1
)

gggrowthplot(
  object,
  pct = TRUE,
  xlim = NULL,
  ylim = NULL,
  sa_bar_line = TRUE,
  col_tc = "#E69F00",
  col_sa = "black",
  col_sa_fill = "grey",
  legend_tc = "Trend-cycle",
  legend_sa = "Seasonally adjusted",
  ...,
  lag = -1
)

Arguments

Details

growthplot() produces a base R graphic, whereas gggrowthplot() creates a ggplot2 object that can be further customized.

Value

• growthplot() returns NULL invisibly and is called for its side effect (drawing a plot).

• gggrowthplot() returns a ggplot object.

Examples

tc_mod <- henderson_smoothing(french_ipi[, "manufacturing"])
growthplot(tc_mod, xlim = c(2022, 2024.5))

Robust Trend-Cycle Estimation using the Henderson Filter

Description

Estimates the trend-cycle component using Henderson moving averages robust to outliers (additive outliers and level shifts).

Usage

henderson_robust_smoothing(
  x,
  endpoints = c("Musgrave", "QL", "CQ", "DAF"),
  length = NULL,
  ao = NULL,
  ao_tc = NULL,
  ls = NULL,
  icr = NULL,
  local_icr = FALSE,
  asymmetric_var = FALSE,
  degree = 3,
  ...
)

Arguments

Details

When outliers are present in a time series, standard linear filters like the Henderson moving average can spread their impact across adjacent trend estimates. This function explicitly accounts for specified Additive Outliers (AO) and Level Shifts (LS) during the filtering process to prevent distortion of the trend-cycle estimates as described in Quartier-la-Tente (2025).

In a nutshell, Henderson smoothing is equivalent to a local polynomial regression of degree 3 (or equivalently 2) estimated with weighted least squares, using specific weights to obtain the Henderson coefficients. Adding regressors to this local regression to account for outliers allows removing their influence on the estimation of polynomial coefficients and thus on the trend-cycle estimates.

Value

An object of class c("tc_estimates", "robust_henderson"). See tc_estimates() for a full description of the returned object.

References

Quartier-la-Tente, A. (2025). Estimation de la tendance-cycle avec des méthodes robustes aux points atypiques. https://github.com/AQLT/robustMA.

Examples

x <- cars_registrations
outliers <- x13_regarima_outliers(x)
tc <- henderson_robust_smoothing(x, ao = outliers$ao, ls = outliers$ls, local_icr = TRUE)

tc_henderson <- henderson_smoothing(x)
plot(tc, xlim = c(2019, 2022))
lines(tc_henderson$tc, col = "blue")

Trend-Cycle Estimation using the Henderson Filter

Description

Estimates the trend-cycle component using Henderson moving averages.

Usage

henderson_smoothing(
  x,
  endpoints = c("Musgrave", "QL", "CQ", "CC", "DAF", "CN"),
  length = NULL,
  icr = NULL,
  local_icr = FALSE,
  asymmetric_var = FALSE,
  degree = 3,
  ...
)

Arguments

Value

An object of class c("tc_estimates", "henderson"). See tc_estimates() for a full description of the returned object.

References

Henderson, R. (1916). Note on Graduation by Adjusted Average. Transactions of the Actuarial Society of America 17: 43-48.

Musgrave, J. (1964). A Set of End Weights to End All End Weights. US Census Bureau [Custodian]. https://www.census.gov/library/working-papers/1964/adrm/musgrave-01.html.

Quartier-la-Tente, A. (2024). Improving Real-Time Trend Estimates Using Local Parametrization of Polynomial Regression Filters. Journal of Official Statistics, 40(4), 685-715. doi:10.1177/0282423X241283207.

Examples

x <- cars_registrations
tc <- henderson_smoothing(x)
plot(tc, xlim = c(2022, 2025))

Compute Irregular-to-Trend-Cycle (I/C) Ratios

Description

icr() computes the overall I/C ratio, while icrs() computes the I/C ratios for each lag up to the series frequency.

Usage

icr(x, tc, mul = FALSE)

icrs(x, tc, mul = FALSE)

Arguments

Details

The I/C ratio measures the relative importance of the irregular component compared to the trend-cycle component in a time series decomposition.

For a time series of frequency p, when the decomposition is additive (mul = FALSE), the irregular component is defined as I_t = X_t - TC_t. icrs() returns a vector containing the ratio of the mean absolute variation of the irregular component to that of the trend-cycle component for each lag k:

\frac{\bar{I}_k}{\bar{C}_k} = \frac{\sum |I_t - I_{t-k}|}{\sum |TC_t - TC_{t-k}|} \quad \text{for } k \in \{1, 2, \dots, p\}.

If the decomposition is multiplicative (mul = TRUE), the irregular component is defined as I_t = X_t / TC_t, and the ratio of relative variations is computed as:

\frac{\bar{I}_k}{\bar{C}_k} = \frac{\sum |(I_t - I_{t-k}) / I_{t-k}|}{\sum |(TC_t - TC_{t-k}) / TC_{t-k}|} \quad \text{for } k \in \{1, 2, \dots, p\}.

icr() returns the overall I/C ratio, which corresponds to the first lag ratio \bar{I}_1 / \bar{C}_1.

Value

icr() returns a single numeric value representing the overall I/C ratio, while icrs() returns a named numeric vector of I/C ratios for lags 1 to p.

Examples

x <- cars_registrations
tc <- henderson_smoothing(x)
icr(tc)
icrs(tc)

Implicit Forecasts Methods

Description

S3 method of rjd3filters::implicit_forecasts() for "tc_estimates" objects.

Usage

## S3 method for class 'henderson'
implicit_forecasts(x, ...)

## S3 method for class 'clf'
implicit_forecasts(x, ...)

## S3 method for class 'robust_henderson'
implicit_forecasts(x, ...)

Arguments

Details

See rjd3filters::implicit_forecasts() for details on the computation of implicit forecasts.

Value

A matrix or mts object containing the implicit forecasts for the series.

Examples

tc_mod <- henderson_smoothing(french_ipi[, "manufacturing"])
implicit_forecasts(tc_mod)

Plot Implicit Forecasts for Trend-Cycle Estimates

Description

Base R (implicit_forecasts_plot()) and ggplot2 (ggimplicit_forecasts_plot()) graphics for plotting trend-cycle estimates alongside their implicit forecasts.

Usage

implicit_forecasts_plot(
  object,
  xlim = NULL,
  ylim = NULL,
  col_tc = "#E69F00",
  col_sa = "black",
  col_i_f = col_sa,
  xlab = "",
  ylab = "",
  lty_last_tc = 2,
  lty_i_f = 3,
  n_last_tc = 4,
  ...
)

ggimplicit_forecasts_plot(
  object,
  xlim = NULL,
  ylim = NULL,
  col_tc = "#E69F00",
  col_sa = "black",
  col_i_f = col_sa,
  lty_last_tc = 2,
  lty_i_f = 3,
  n_last_tc = 4,
  legend_tc = "Trend-cycle",
  legend_sa = "Seasonally adjusted",
  legend_i_f = "Implicit forecasts",
  ...
)

Arguments

Details

implicit_forecasts_plot() produces a base R graphic, whereas ggimplicit_forecasts_plot() creates a ggplot2 object that can be further customized.

Value

• implicit_forecasts_plot() returns NULL invisibly and is called for its side effect (drawing a plot).

• ggimplicit_forecasts_plot() returns a ggplot object.

Examples

tc_mod <- henderson_smoothing(french_ipi[, "manufacturing"])
implicit_forecasts_plot(tc_mod, xlim = c(2022, 2025))

Lollipop Plot for Trend-Cycle Estimates

Description

Base R (lollypop()) and ggplot2 (gglollypop()) graphics for creating lollipop plots of trend-cycle estimates alongside seasonally adjusted series.

Usage

lollypop(
  object,
  xlim = NULL,
  ylim = NULL,
  col_tc = "#E69F00",
  col_sa = "black",
  color_points = col_sa,
  cex_points = 1,
  pch_points = 16,
  xlab = "",
  ylab = "",
  lty_last_tc = 2,
  n_last_tc = 4,
  ...
)

gglollypop(
  object,
  xlim = NULL,
  ylim = NULL,
  col_tc = "#E69F00",
  col_sa = "black",
  color_points = col_sa,
  cex_points = 1,
  pch_points = 16,
  legend_tc = "Trend-cycle",
  legend_sa = "Seasonally adjusted",
  lty_last_tc = 2,
  n_last_tc = 4,
  ...
)

Arguments

Details

lollypop() produces a base R graphic, whereas gglollypop() creates a ggplot2 object that can be further customized.

Value

• lollypop() returns NULL invisibly and is called for its side effect (drawing a plot).

• gglollypop() returns a ggplot object.

Examples

tc_mod <- henderson_smoothing(french_ipi[, "manufacturing"])
lollypop(tc_mod, xlim = c(2022, 2024.5))

Month of Cyclical Dominance (MCD)

Description

Computes the Month of Cyclical Dominance (MCD) for a time series decomposition.

Usage

mcd(x, tc, mul = FALSE)

Arguments

Details

The Month of Cyclical Dominance (MCD) represents the minimum number of months required for the average absolute variation of the trend-cycle component to dominate that of the irregular component. In other words, it indicates the shortest time span needed on average for the cyclical signal to outweigh irregular fluctuations.

It is computed as the smallest integer k (where k \ge 1) such that the I/C ratio remains less than or equal to 1 for all lags j \ge k:

k = \min \left\{ k \in \{1, \dots, p\} : \frac{\bar{I}_j}{\bar{C}_j} \le 1 \text{ for all } j \ge k \right\}

If the I/C ratio never falls below or equal to 1 within the frequency p, the MCD is set to p.

Value

An integer specifying the Month of Cyclical Dominance (MCD).

Examples

x <- cars_registrations
tc <- henderson_smoothing(x)
mcd(tc)
icrs(tc)

Plotting Methods for Trend-Cycle Estimates

Description

Plotting methods for objects of class "tc_estimates". plot() and lines() produce base R graphics, whereas autoplot() creates a ggplot2 object.

Usage

## S3 method for class 'tc_estimates'
plot(
  x,
  y = NULL,
  xlim = NULL,
  ylim = NULL,
  col_tc = "#E69F00",
  col_sa = "black",
  xlab = "",
  ylab = "",
  lty_last_tc = 2,
  n_last_tc = 4,
  ...
)

## S3 method for class 'tc_estimates'
lines(x, col_tc = "#E69F00", lty_last_tc = 2, n_last_tc = 4, ...)

## S3 method for class 'tc_estimates'
autoplot(
  object,
  xlim = NULL,
  ylim = NULL,
  col_tc = "#E69F00",
  col_sa = "black",
  legend_tc = "Trend-cycle",
  legend_sa = "Seasonally adjusted",
  lty_last_tc = 2,
  n_last_tc = 4,
  ...
)

## S3 method for class 'ts'
autoplot(object, xlim = NULL, ylim = NULL, ...)

Arguments

Details

plot.tc_estimates() and autoplot.tc_estimates() produce a plot showing both the seasonally adjusted series and the estimated trend-cycle component. lines.tc_estimates() adds only the trend-cycle component to an existing base R plot.

Value

• plot() and lines() return NULL invisibly and are called for their side effect (drawing a plot).

• autoplot() returns a ggplot object.

Examples

tc_mod <- henderson_smoothing(french_ipi[, "manufacturing"])
plot(tc_mod, xlim = c(2022, 2024.5))

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

ggplot2

autoplot()

rjd3filters

implicit_forecasts(), underlying_forecasts()

Segmented Smoothing around Breakpoints

Description

Estimates the trend-cycle component by segmenting a time series around known structural breakpoints.

Usage

segmented_smoothing(
  x,
  breaks = NULL,
  break_method = c("one-side", "two-sides"),
  smoothing_method = c("henderson_smoothing", "clf_smoothing"),
  ...
)

Arguments

Details

Two methods are available to estimate the trend-cycle around breakpoints:

1. "one-side": The trend-cycle is estimated across the entire dataset, and the estimates after each breakpoint are overwritten with the estimates obtained by smoothing only the data following that breakpoint.

2. "two-sides": The trend-cycle is estimated independently on each segment defined by the breakpoints, and the resulting estimates are combined to form the final trend-cycle.

The parameters field of the returned object corresponds to the parameters of the last segment (used to compute confidence intervals and implicit forecasts).

Value

An object of class c("tc_estimates", "henderson") if smoothing_method is henderson_smoothing(), or c("tc_estimates", "clf") if smoothing_method is clf_smoothing().

Examples

x <- window(publishTC::french_ipi[, "manufacturing"], start = 2015)
tc_h <- henderson_smoothing(x, length = 13)$tc
breaks <- list(c(2020, 3))
tc_h_2s <- segmented_smoothing(x, breaks = breaks, break_method = "two-sides", length = 13)$tc
tc_h_rob <- henderson_robust_smoothing(x, ls = c(2020 + (3 - 1) / 12, 2020 + (4 - 1) / 12))$tc

plot(window(x, start = 2019.5, end = 2021),
  main = "Smoothing around COVID-19",
  xlab = NULL, ylab = NULL,
  lty = 3
)
lines(tc_h, col = "purple")
lines(tc_h_2s, col = "lightblue")
lines(tc_h_rob, col = "orange")
legend(
  "bottomright",
  legend = c("y", "Henderson", "Two-Sides Segmented", "Robust H. (2 LS)"),
  col = c("black", "purple", "lightblue", "orange"),
  lty = c(3, 1, 1, 1, 1),
  cex = 0.7
)

Multi-Method Trend-Cycle Estimation

Description

Computes trend-cycle estimates using multiple smoothing methods simultaneously and returns a list of "tc_estimates" objects.

Usage

smoothing(
  x,
  methods = c("henderson", "henderson_localic", "henderson_robust",
    "henderson_robust_localic", "clf_cn", "clf_alf"),
  endpoints = "Musgrave",
  length = NULL,
  icr = NULL,
  asymmetric_var = FALSE,
  degree = 3,
  ao = NULL,
  ao_tc = NULL,
  ls = NULL,
  ...
)

Arguments

Details

This convenience function applies multiple trend-cycle estimation algorithms to the same input series, facilitating direct comparison between different filtering approaches (e.g., standard Henderson, Henderson with local I/C ratio, or CLF smoothing).

Value

A named list of objects of class "tc_estimates", where each element corresponds to one of the specified methods in methods.

Examples

x <- french_ipi[, "manufacturing"]
outliers <- x13_regarima_outliers(x)
all_methods <- smoothing(x, ao = outliers$ao, ao_tc = outliers$ao_tc, ls = outliers$ls)

plot(all_methods$henderson, xlim = c(2023, 2025))
lines(all_methods$henderson_localic, col_tc = "blue")

Measure Smoothness of Trend-Cycle Estimates

Description

Computes the smoothness ratio of trend-cycle estimates relative to the seasonally adjusted series following Picard and Matthews (2016).

Usage

smoothness(x)

Arguments

Details

Smoothness is evaluated as the ratio of month-to-month growth rate variances:

100 \times \sqrt{ \frac{ \sum_t \left( \frac{TC_t - TC_{t-1}}{TC_{t-1}} \right)^2 }{ \sum_t \left( \frac{SA_t - SA_{t-1}}{SA_{t-1}} \right)^2 } }

This metric quantifies the relative variability of the trend-cycle compared to the seasonally adjusted series. A lower value indicates a smoother trend-cycle.

Value

A numeric value representing the smoothness index of the trend-cycle estimates.

References

Picard, F., & Matthews, S. (2016). The Addition of Trend-Cycle Estimates to Selected Publications at Statistics Canada. Proceedings of the Survey Methods Section, Statistical Society of Canada (SSC) Annual Meeting. https://ssc.ca/sites/default/files/imce/pdf/picard_ssc2016.pdf

Examples

x <- french_ipi[, "manufacturing"]
tc_clf <- clf_smoothing(x)
tc_henderson <- henderson_smoothing(x)
smoothness(tc_clf)
smoothness(tc_henderson)

Trend-Cycle Estimates Class

Description

Constructor and S3 methods for objects of class "tc_estimates".

Usage

tc_estimates(tc, sa, parameters = NULL, extra_class = NULL, ...)

is_tc_estimates(x)

## S3 method for class 'tc_estimates'
summary(object, ...)

Arguments

Details

Objects of class "tc_estimates" store trend-cycle estimates along with the original series and metadata required for summary statistics, confidence intervals, and implicit forecasts.

Value

tc_estimates() returns an object of class c("tc_estimates", extra_class), which is a list containing the following components:

• tc: The estimated trend-cycle time series.

• x: The original (seasonally adjusted) time series.

• parameters: A list of parameters used during estimation.

The summary() method returns a list of class "summary.tc_estimates" containing:

• ⁠I/C ratio⁠: The overall Irregular-to-Trend-Cycle ratio (see icr()).

• ⁠I/C ratios⁠: The I/C ratio per period (see icrs()).

• MCD: The Month of Cyclical Dominance statistic (see mcd()).

• Length: The length of the symmetric trend-cycle filter.

Examples

x <- cars_registrations
tc <- henderson_smoothing(x)
summary(tc)
print(tc)

Example Datasets

Description

Example datasets used in Quartier-la-Tente (2025).

Usage

cars_registrations

french_ipi

fred

simulated_data

etip

Format

An object of class ts of length 177.

An object of class mts (inherits from ts, matrix, array) with 416 rows and 3 columns.

An object of class mts (inherits from ts, matrix, array) with 766 rows and 2 columns.

An object of class mts (inherits from ts, matrix, array) with 84 rows and 6 columns.

An object of class ts of length 590.

Details

• cars_registrations: Monthly new passenger car registrations in France, published in October 2024.

• french_ipi: Monthly Industrial Production Index (IPI) in France for crude petroleum, motor vehicles, and manufacturing, published in October 2024.

• fred: The series CE16OV (Civilian Employment Level) and RETAILx (Retail and Food Services Sales) from the FRED-MD database, published in November 2022.

• simulated_data: Simulated trends of degree 0, 1, and 2 with an Additive Outlier (AO) or Level Shift (LS) in January 2022.

• etip: Expected trend in production (balance of opinion) in the French manufacturing industry, published in May 2024 in the monthly business survey in goods-producing industries by INSEE.

References

Quartier-la-Tente, A. (2025). Estimation de la tendance-cycle avec des méthodes robustes aux points atypiques. https://github.com/AQLT/robustMA. McCracken, Michael W., et Serena Ng. 2016. FRED-MD: A Monthly Database for Macroeconomic Research. Journal of Business & Economic Statistics 34 (4): 574‑89. doi:10.1080/07350015.2015.1086655.

Detect Turning Points and Unwanted Ripples in a Time Series

Description

Identifies turning points (upturns and downturns) and unwanted short-term ripples in a time series object using local extremum criteria.

Usage

turning_points(x, start = NULL, end = NULL, digits = 6, k = 3, m = 1)

upturn(x, start = NULL, end = NULL, digits = 6, k = 3, m = 1)

downturn(x, start = NULL, end = NULL, digits = 6, k = 3, m = 1)

unwanted_ripples(x, start = NULL, end = NULL, digits = 6, k = 3, m = 1)

Arguments

Details

Turning points are identified following the operational definition adapted from Zellner, Hong, and Min (1991), typically with k = 3 and m = 1:

• An upturn occurs at time t if:

  y_{t-k} \ge \dots \ge y_{t-1} < y_t \le y_{t+1} \le \dots \le y_{t+m}

• A downturn occurs at time t if:

  y_{t-k} \le \dots \le y_{t-1} > y_t \ge y_{t+1} \ge \dots \ge y_{t+m}

An unwanted ripple is defined as any occurrence where two turning points of the same type (two upturns or two downturns) occur within a 10-month window (i.e., short cycles lasting less than 11 months).

Value

• turning_points() returns a named list with two components: "upturn" and "downturn", each containing a vector of dates (or empty vectors if none found).

• upturn() and downturn() return a vector of dates corresponding to the detected upturns or downturns, respectively.

• unwanted_ripples() returns an integer representing the number of unwanted ripples detected in the series.

References

Zellner, A., Hong, C., & Min, C. (1991). Forecasting Turning Points in International Growth Rates using Bayesian Exponential Smoothing Methods. Journal of Econometrics, 49(1–2), 275–304. doi:10.1016/0304-4076(91)90016-7

Examples

tc <- henderson_smoothing(french_ipi[, "manufacturing"])
turning_points(tc)
unwanted_ripples(tc)

Underlying Forecasts Methods

Description

S3 method of rjd3filters::underlying_forecasts() for "tc_estimates" objects.

Usage

## S3 method for class 'henderson'
underlying_forecasts(x, ...)

## S3 method for class 'clf'
underlying_forecasts(x, ...)

## S3 method for class 'robust_henderson'
underlying_forecasts(x, ...)

Arguments

Details

See rjd3filters::underlying_forecasts() for details on the computation of underlying forecasts.

Value

A matrix or mts object containing the underlying forecasts for the series.

Examples

tc_mod <- henderson_smoothing(french_ipi[, "manufacturing"])
underlying_forecasts(tc_mod)

Plot Underlying Forecasts for Trend-Cycle Estimates

Description

Base R (underlying_forecasts_plot()) and ggplot2 (ggunderlying_forecasts_plot()) graphics for plotting trend-cycle estimates alongside their underlying forecasts.

Usage

underlying_forecasts_plot(
  object,
  xlim = NULL,
  ylim = NULL,
  col_tc = "#E69F00",
  col_sa = "black",
  col_i_f = col_sa,
  xlab = "",
  ylab = "",
  lty_last_tc = 2,
  lty_i_f = 3,
  n_last_tc = 4,
  ...
)

ggunderlying_forecasts_plot(
  object,
  xlim = NULL,
  ylim = NULL,
  col_tc = "#E69F00",
  col_sa = "black",
  col_i_f = col_sa,
  lty_last_tc = 2,
  lty_i_f = 3,
  n_last_tc = 4,
  legend_tc = "Trend-cycle",
  legend_sa = "Seasonally adjusted",
  legend_i_f = "Implicit forecasts",
  ...
)

Arguments

Details

underlying_forecasts_plot() produces a base R graphic, whereas ggunderlying_forecasts_plot() creates a ggplot2 object that can be further customized.

Value

• underlying_forecasts_plot() returns NULL invisibly and is called for its side effect (drawing a plot).

• ggunderlying_forecasts_plot() returns a ggplot object.

Examples

tc_mod <- henderson_smoothing(french_ipi[, "manufacturing"])
underlying_forecasts_plot(tc_mod, xlim = c(2022, 2025))

Export and Import Time Series to and from CSV

Description

write.ts() exports a time series object ("ts") or a list of time series to a CSV file, adding a "time" column. read.ts() imports a CSV file whose first column contains dates and reconstructs the corresponding ts object.

Usage

write.ts(x, file, ...)

read.ts(file, frequency = NULL, list = FALSE)

Arguments

Details

write.ts() formats the time index into a dedicated date column (e.g., YYYY-MM-DD or fractional years) alongside the data series. When reading back with read.ts(), the time index is parsed to reconstruct regular R time series objects.

Value

• write.ts() returns NULL invisibly and is called for its side effect (writing a CSV file).

• read.ts() returns a "ts" object, a multiple time series ("mts"), or a list of "ts" objects depending on list.

Examples

file <- tempfile(fileext = ".csv")
write.ts(AirPassengers, file)
read.ts(file)

X-11 Selection of Trend-Cycle Filter

Description

Performs X-11 selection for the length of the Henderson filter (x11_trend_selection()) and computes the associated I/C ratio used to build Musgrave filters (find_icr()).

Usage

x11_trend_selection(x)

find_icr(length, freq = 12)

Arguments

Details

The following procedure is used in X-11 to select the length of the trend filter:

1. Computes the I/C ratio, icr, with a Henderson filter of length equal to the series frequency plus 1.

2. The selected length depends on the value of icr:

   • If icr < 1, the selected length is 9 for monthly data and 5 otherwise.

   • If 1 \le icr < 3.5, the selected length is freq + 1 (i.e., 13 for monthly data, 5 for quarterly data).

   • If icr \ge 3.5, the selected length is 23 for monthly data and 7 otherwise.

3. The value of icr is then mapped to build Musgrave filters (find_icr()):

   • For quarterly data, if the length is 5, then icr = 0.001; otherwise, icr = 4.5.

   • For other frequencies, if the length is less than or equal to 9, then icr = 1.0.

   • Else, if the length is less than or equal to 13, then icr = 3.5.

   • Else, icr = 4.5.

Value

• x11_trend_selection() returns a named numeric vector containing the selected length and the associated I/C ratio.

• find_icr() returns a single numeric value corresponding to the I/C ratio associated with the specified filter length and frequency in the X-11 algorithm.

Examples

x11_trend_selection(cars_registrations)
find_icr(length = 13, freq = 12)

Outlier Detection with RegARIMA Model

Description

Wrapper around rjd3x13::regarima_outliers() to detect Additive Outliers (AO) or Level Shifts (LS) in a seasonally adjusted series.

Usage

x13_regarima_outliers(
  y,
  order = c(0, 1, 1),
  mean = FALSE,
  ao = TRUE,
  ls = TRUE
)

Arguments

Details

This function uses an underlying RegARIMA model via rjd3x13 to automatically identify structural breaks and temporary shocks in the input series, returning their locations for downstream robust trend-cycle estimation.

Value

A list with two components:

• ao: A vector of dates where Additive Outliers were detected (or NULL if none).

• ls: A vector of dates where Level Shifts were detected (or NULL if none).

Examples

x13_regarima_outliers(cars_registrations)