Package 'publishTC'

Get Bandwidth

Description

Get the bandwidth of a "tc_estimates" object. The length of the filter is then equal to $2 \times \text{bandwidth}(x) + 1$.

Usage

bandwidth(x)

Arguments

x	a "tc_estimates" object.

---

Classical Moving Average

Description

Classical moving average for trend-cycle extraction.

Usage

henderson

CLF

CLF_CN

local_param_est

Format

henderson is list() of "moving_average".

CLF is a "finite_filters".

CLF_CN is a "finite_filters".

local_param_est is list() of "finite_filters".

Details

henderson contains the Henderson moving average of length 5, 7, 9, 13 and 23.

CLF contains the Cascade Linear Filter (CLF) of length 13 and the associated Asymmetric Linear Filters (ALF).

CLF_CN contains the Cascade Linear Filter (CLF) of length 13 and the associated cut and normalise asymetric filters.

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. https://doi.org/10.1080/07474930802387837.

Henderson, R. (1916). Note on graduation by adjusted average. Transactions of the actuarial society of America 17: 43‑48.

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. https://doi.org/10.1177/0282423X241283207.

---

Smoothing using the Cascade Linear Filter

Description

Smoothing using the Cascade Linear Filter

Usage

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

Arguments

x	input time-series.
endpoints	Method used for the asymmetric filter. If endpoints = "cut-and-normalize" (the default) the cut-and-normalise method is used, otherwise the Asymmetric Linear Filter (ALF) filters are used.
...	other unused parameters.

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. https://doi.org/10.1080/07474930802387837

---

Confidence Intervals plot

Description

Confidence Intervals plot

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

object	"tc_estimates". The confidence intervals are computed using the confint() function.
xlim, ylim	x and y limits of the plot. If xlim is defined and not ylim, then ylim is determined automatically.
col_sa, col_tc	color of the seasonally adjusted and trend-cycle components.
col_confint	color of the confidence interval.
xlab, ylab	x and y axis labels.
level	the confidence level required.
...	other parameters.
legend_tc, legend_sa, legend_confint	legend of the trend-cycle and seasonally adjusted components and for the confidence intervals.

Examples

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

---

Confidence Intervals for "tc_estimates"

Description

Confidence Intervals for "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

object	a "tc_estimates" object.
parm	unused parameter.
level	the confidence level required.
asymmetric_var	if asymmetric_var = TRUE then the variance is estimated for each asymmetric filters instead of using the variance associated the symmetric estimates.
...	other (unused) parameters.

---

Produce several plots

Description

Produce several plots

Usage

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

Arguments

object	"tc_estimates". The confidence intervals are computed using the confint() function.
plots	list of plots to use.
level	the confidence level required.
...	other unused parameters.

---

Growth plots

Description

Plots the growth rate of the trend-cycle (solid lines) and the seasonally adjusted series (bar-line).

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

object	"tc_estimates" object.
pct	logical. If TRUE (the default), the growth rate is expressed in percentage points.
xlim, ylim	x and y limits of the plot. If xlim is defined and not ylim, then ylim is determined automatically.
col_sa, col_tc	color of the seasonally adjusted and trend-cycle components.
xlab, ylab	x and y axis labels.
sa_bar_line	logical. If TRUE (the default), the growth rates of the seasonally adjusted series are presented as bar-lines, otherwise they are presented as lines.
...	other (unused) parameters.
lag	lag used for the growth rate. By default, lag = -1 (i.e. period-to-period growth rate).
col_sa_fill	fill color of the bar of the seasonally adjusted series.
legend_tc, legend_sa	legend of the trend-cycle and seasonally adjusted components.

Examples

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

---

Smoothing using the Henderson filter

Description

Smoothing using the Henderson filter

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

x	input time-series.
endpoints	Method used for the asymmetric filter. By default the Musgrave method is used
length	the length of the
ao	Dates of the Additive Outliers (AO) which effects are associated to the irregular component.
ao_tc	Dates of the Additive Outliers (AO) which effects are associated to the trend-cycle component.
ls	Dates of the Level Shifts (LS) which effects are associated to the trend-cycle component.
icr	I/C ratio used for the asymmetric filter.
local_icr	if TRUE, the I/C ratio is estimated locally (as described in Quartier-la-Tente, A. (2024)) instead of globally.
asymmetric_var	when local_icr = TRUE, if asymmetric_var = TRUE then the variance is estimated for each asymmetric filters instead of using the variance associated to the symmetric estimates.
degree	if local_icr = TRUE, degree of polynomial used to estimate the local bias parameter.
...	other parameters passed to rjd3filters::lp_filter().

---

Smoothing using the Henderson filter

Description

Smoothing using the Henderson filter

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

x	input time-series.
endpoints	Method used for the asymmetric filter. By default the Musgrave method is used
length	the length of the
icr	I/C ratio used for the asymmetric filter.
local_icr	if TRUE, the I/C ratio is estimated locally (as described in Quartier-la-Tente, A. (2024)) instead of globally.
asymmetric_var	when local_icr = TRUE, if asymmetric_var = TRUE then the variance is estimated for each asymmetric filters instead of using the variance associated to the symmetric estimates.
degree	if local_icr = TRUE, degree of polynomial used to estimate the local bias parameter.
...	other parameters passed to rjd3filters::lp_filter().

References

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. https://doi.org/10.1177/0282423X241283207.

---

Compute IC-Ratio

Description

icr() compute the overall I/C ratio, while icrs() compute the I/C ratios for each period.

Usage

icr(x, tc, mul = FALSE)

icrs(x, tc, mul = FALSE)

Arguments

x, tc	seasonally adjusted and trend-cycle components. If x is a "tc_estimates" object then tc is ignored.
mul	boolean indicating if the decomposition is multiplicative or additive.

Examples

x <- cars_registrations
tc <- henderson_smoothing(x)

---

Compute Implicit Forecasts

Description

Compute Implicit Forecasts

Usage

implicit_forecasts(x, ...)

Arguments

x	a "tc_estimates" object otherwise uses the rjd3filters::implicit_forecast() function.
...	other unused parameters.

---

Implicit Forecasts plot

Description

Implicit Forecasts plot

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

object	"tc_estimates" object.
xlim, ylim	x and y limits of the plot. If xlim is defined and not ylim, then ylim is determined automatically.
col_sa, col_tc	color of the seasonally adjusted and trend-cycle components.
col_i_f	color of the implicit forecasts.
xlab, ylab	x and y axis labels.
lty_last_tc, lty_i_f	line type of the last values of the trend-cycle component and for the implicit forecasts.
n_last_tc	number of last values of the trend-cycle component to be plotted with a different line type (to emphasize that there is higher variability for the last estimates). If NULL, then n_last_tc is equal to the MCD statistic.
...	other parameters.
legend_tc, legend_sa, legend_i_f	legend of the trend-cycle and seasonally adjusted components and for implicit forecasts.

Examples

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

---

Lollypop plot

Description

Lollypop plot

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

object	"tc_estimates" object.
xlim, ylim	x and y limits of the plot. If xlim is defined and not ylim, then ylim is determined automatically.
col_sa, col_tc	color of the seasonally adjusted and trend-cycle components.
color_points, cex_points	color and size of the points associated to the seasonnaly adjusted component.
pch_points	point type of the seasonally adjusted component.
xlab, ylab	x and y axis labels.
lty_last_tc	line type of the last values of the trend-cycle component.
n_last_tc	number of last values of the trend-cycle component to be plotted with a different line type (to emphasize that there is higher variability for the last estimates). If NULL, then n_last_tc is equal to the MCD statistic.
...	other parameters.
legend_tc, legend_sa	legend of the trend-cycle and seasonally adjusted components.

Examples

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

---

Month of Cyclical Dominance

Description

Month of Cyclical Dominance

Usage

mcd(x, tc, mul = FALSE)

Arguments

x, tc	seasonally adjusted and trend-cycle components. If x is a "tc_estimates" object then tc is ignored.
mul	boolean indicating if the decomposition is multiplicative or additive.

---

Default "tc_estimates" plot

Description

Default "tc_estimates" plot

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'
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,
  ...
)

Arguments

y	unused parameter.
xlim, ylim	x and y limits of the plot. If xlim is defined and not ylim, then ylim is determined automatically.
col_sa, col_tc	color of the seasonally adjusted and trend-cycle components.
xlab, ylab	x and y axis labels.
lty_last_tc	line type of the last values of the trend-cycle component.
n_last_tc	number of last values of the trend-cycle component to be plotted with a different line type (to emphasize that there is higher variability for the last estimates). If NULL, then n_last_tc is equal to the MCD statistic.
...	other (unused) parameters.
object, x	"tc_estimates" object.
legend_tc, legend_sa	legend of the trend-cycle and seasonally adjusted components.

Examples

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

---

Segmented Smoothing around Breakpoints

Description

Segmented Smoothing around Breakpoints

Usage

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

Arguments

x	input time-series.
breaks	A list of breakpoints (dates) where the series should be split for smoothing.
break_method	Method to split the series (see details).
smoothing_method	Smoothing method to use on each segment : henderson_smoothing() or clf_smoothing().
...	Other parameters passed to the smoothing method.

Details

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

1. "one-side": The trend-cycle is estimated on the all data and the estimates are overwritten after each breakpoint with the estimates obtained by smoothing only the data after the breakpoint.

2. "two-sides": The trend-cycle is estimated on each segment defined by the breakpoints and the 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 build confidence intervals and implicit forecasts).

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
)

---

Smoothing using several methods

Description

Smoothing using several methods

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

x	input time-series.
methods	list of methods to use.
endpoints	Method used for the asymmetric filter. By default the Musgrave method is used
length	the length of the
icr	I/C ratio used for the asymmetric filter.
asymmetric_var	when local_icr = TRUE, if asymmetric_var = TRUE then the variance is estimated for each asymmetric filters instead of using the variance associated to the symmetric estimates.
degree	if local_icr = TRUE, degree of polynomial used to estimate the local bias parameter.
ao	Dates of the Additive Outliers (AO) which effects are associated to the irregular component.
ao_tc	Dates of the Additive Outliers (AO) which effects are associated to the trend-cycle component.
ls	Dates of the Level Shifts (LS) which effects are associated to the trend-cycle component.
...	other unused parameters.

---

Get Smoothness of Trend-Cycle estimates

Description

Compute the smoothness of trend-cycle estimates using Picard and Matthews (2006) definition.

Usage

smoothness(x)

Arguments

x	a "tc_estimates" object.

Details

There are several definitions or criteria of smoothness. The measure of smoothness used here is defined as:

$100 \times \sqrt{ \frac{ \sum_t [(TC_t - TC_{t-1})/TC_{t-1}]^2 }{ \sum_t [(SA_t - SA_{t-1})/SA_{t-1}]^2 } }$

This represents a measure of the month-to-month percentage change in the trend-cycle. The smaller the smoothness number is, the smoother the trend-cycle.

References

Picard, Frédéric et Steve Matthews (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/p icard_ssc2016.pdf>.

---

Data set examples

Description

All data sets examples used in the paper 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 cars registrations in France, published in October 2024.

• french_ipi: monthly industrial production index 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 corresponds to the Expected trend in production (balance of opinion) in the French Manufacturing industry, published in May 2025 in the monthly business survey in goods-producing industries by the 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. https://doi.org/10.1080/07350015.2015.1086655.

---

Detect turning points in a time series

Description

turning_points() returns the number of downturns (downturn()) and upturns (upturn()) in a time series. unwanted_ripples() returns the number of unwanted ripples in a time series.

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

x	the input time series.
start, end	the interval where to find turning points.
digits	number of digits used for the comparison of the values.
k, m	number of observation before and after the turning point (see details).

Details

Zellner, Hong, et Min (1991) definition is used $k=3$, $m=1$:

• we have an upturn at date $t$ when

  $y_{t-k}\geq\cdots\geq y_{t-1}<y_t\leq y_{t+1}\leq\cdots y_{t+m}$

• we have a downturn at date $t$ when

$y_{t-k}\leq\cdots\leq y_{t-1}>y_t\geq y_{t+1}\geq\cdots y_{t+m}$

An unwanted ripple is defined whenever two downturns or upturns occur within a 10 month period (i.e.: small cycles of less than 11 months).

---

Export and Import time series object to/from CSV

Description

Export and Import time series object to/from CSV

Usage

write.ts(x, file)

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

Arguments

x	a time series object
file	a character string giving the name of the file to write to.
frequency	an integer giving the number of observations per unit of time. By default it is guessed from the data.
list	boolean, if TRUE, the function returns a list of time series objects.

---

X-11 Selection of Trend-Cycle Filter

Description

Perform X-11 selection of the length of Henderson (x11_trend_selection()) and compute the associated I/C ratio used to build Musgrave fuilters (find_icr()).

Usage

x11_trend_selection(x)

find_icr(length, freq = 12)

Arguments

x	a "ts" object.
length	length of the filter.
freq	frequency of the time series used to compute the I/C ratio.

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 an Henderson filter of length the frequency plus 1.

2. The length depends on the value or $icr$:

   • if $icr < 1$ then the selected length is 9 for monthly data and 5 otherwise;

   • if $1 \leq icr < 3.5$ then the selected length is $freq + 1$ where $freq$ is the frequency of data (12 for monthly data, 4 for quarterly data...).

   • if $icr \geq 3.5$ then the selected length is 23 for monthly data and 7 otherwise.

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

   • for quarterly data, if the length is 5 then $icr = 0.001$, otherwide $icr = 4.5$;

   • if the length if less or equal to 9 then $icr = 1$;

   • else if the length if less or equal to 13 then $icr = 3.5$;

   • else $icr = 4.5$.

---

Outlier detection with RegARIMA Model

Description

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

Usage

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

Arguments

y	A ts object.
order	Orders of the ARIMA model.
mean	Logical, if TRUE the model includes a constant term.
ao, ls	Boolean to indicate if additive outliers (AO) or level shifts (LS) should be detected.

Value

A list with two elements: ao and ls, which are vectors of time points where the respective outliers were detected. If no outliers were detected, the corresponding element will be NULL.

---