Hyperparameter Tuning for the MacroBoost Hybrid Filter

In MacroFilters: Robust Trend-Cycle Decomposition for Macroeconomic Time Series

knitr::opts_chunk$set(
  collapse = TRUE, comment = "#>",
  fig.width = 8, fig.height = 4.5, out.width = "100%"
)
library(MacroFilters)
library(data.table)
library(ggplot2)
data("us_gdp_vintage", package = "MacroFilters")

1 Anatomy of the MBH Trifecta

mbh_filter() exposes three knobs that jointly govern fit quality, robustness, and computation time.

| Parameter | Default | Role | |---|---|---| | mstop | 500 | Gradient-descent iteration budget | | nu | 0.1 | Per-step shrinkage (learning rate) | | knots | min(max(20, floor(n/2)), 250) | P-spline interior knot count (capped at 250) |

1.1 mstop — iteration budget

Each boosting step adds a small, smooth update to the current trend estimate. More iterations allow finer approximation of the optimal solution, at the cost of linear wall time. The default mstop = 500 is calibrated to produce HP-comparable flexibility on quarterly macro series (~100–400 observations).

1.2 nu — shrinkage

nu scales the gradient contribution of each step. Lower nu requires more iterations to reach the same fit quality; higher nu converges faster but may overshoot. The key identity is:

$$\text{effective update} \approx \nu \times \text{mstop} \times \text{step size}$$

A practical equivalence: (mstop = 500, nu = 0.1) and (mstop = 1000, nu = 0.05) produce nearly identical trends.

y <- us_gdp_vintage$gdp_log

res_default <- mbh_filter(y, mstop = 500,  nu = 0.10)
res_equiv   <- mbh_filter(y, mstop = 1000, nu = 0.05)

max_diff <- max(abs(res_default$trend - res_equiv$trend))
cat(sprintf("Max trend difference (mstop×nu equivalence): %.2e\n", max_diff))

1.3 knots — spline flexibility

Knots control how many local basis functions the P-spline uses to represent the trend shape. The default heuristic min(max(20, floor(n/2)), 250) provides roughly one knot per two observations (capped at 250 for long series) — high density relative to classical smoothing spline recommendations — because Huber loss (not spline regularity) acts as the primary smoothness constraint.

Too few knots force an overly rigid polynomial-like trend; too many knots with low mstop may leave some basis functions unfitted.

---

2 Auto-calibration of Huber Delta d

The Huber loss function

$$L_\delta(r) = \begin{cases} \tfrac{1}{2}r^2 & |r| \le \delta \ \delta\,|r| - \tfrac{1}{2}\delta^2 & |r| > \delta \end{cases}$$

transitions between $L_2$ (quadratic) loss for small residuals and $L_1$ (absolute) loss for large ones. The threshold $\delta$ determines which residuals are treated as outliers.

When d = NULL, the threshold is set automatically via the MAD of first differences:

$$\hat{d} = \text{MAD}(\Delta y) = \frac{\text{median}(|\Delta y - \text{median}(\Delta y)|)}{0.6745}$$

The $0.6745$ scale factor makes MAD a consistent estimator of the standard deviation under normality.

2.1 Scale invariance

If $y \to a \cdot y$, then $\Delta y \to a \cdot \Delta y$ and $\hat{d} \to a \cdot \hat{d}$. The Huber threshold scales exactly with the data amplitude, so the filter behaves identically regardless of the measurement units.

y_level <- us_gdp_vintage$gdp_real   # billions USD (~20 000 scale)
y_log   <- us_gdp_vintage$gdp_log    # natural log (~10 scale)

d_level <- stats::mad(diff(y_level))
d_log   <- stats::mad(diff(y_log))

cat(sprintf("d (level series) : %.4f\n", d_level))
cat(sprintf("d (log series)   : %.6f\n", d_log))
cat(sprintf("Ratio d_level / mean(level): %.6f\n", d_level / mean(y_level)))
cat(sprintf("Ratio d_log   / mean(log)  : %.6f\n", d_log   / mean(y_log)))

2.2 Scale-mismatch warning for log-level input

For log-level GDP, diff(y) returns quarterly growth rates whose typical scale is 0.004–0.010. The output gap (the cycle the filter must explain) operates on a much larger scale, typically 0.01–0.05. Using d = mad(diff(y)) therefore sets the Huber threshold too tight: normal business-cycle oscillations are mis-classified as outliers, their gradient contributions are truncated, and the trend becomes a near-straight line.

The recommended override is:

d_cycle <- mad(hp_filter(y_log)$cycle)   # set d on the residual scale
res     <- mbh_filter(y_log, d = d_cycle)

---

3 Overriding d for High-Volatility Series

Quarterly GDP growth rates (diff(log(GDP))) are roughly 40× more volatile relative to trend than log levels. The COVID collapse of 2020 Q2 ($\approx -9\%$ q-o-q) represents an extreme outlier even by growth-rate standards. This makes growth rates an ideal stress test for d sensitivity.

y_growth <- diff(us_gdp_vintage$gdp_log)   # quarterly log-differences

res_auto   <- mbh_filter(y_growth)
res_strict <- mbh_filter(y_growth, d = 0.005)
res_lenient <- mbh_filter(y_growth, d = 0.02)

cat(sprintf("Auto d = %.6f\n", res_auto$meta$d))

dt_growth <- data.table(
  t        = us_gdp_vintage$date[-1],
  observed = y_growth,
  auto     = res_auto$trend,
  strict   = res_strict$trend,
  lenient  = res_lenient$trend
)

dt_long <- melt(dt_growth,
                id.vars      = "t",
                measure.vars = c("auto", "strict", "lenient"),
                variable.name = "delta",
                value.name    = "trend")

# Human-readable labels
auto_label <- sprintf("Auto (d=%.4f)", res_auto$meta$d)
# data.table::melt() returns variable.name as factor; fcase() returns character.
# Assigning character to a factor column via := raises a type mismatch error,
# so coerce to character first.
dt_long[, delta := as.character(delta)]
dt_long[, delta := fcase(
  delta == "auto",    auto_label,
  delta == "strict",  "Strict (d=0.005)",
  delta == "lenient", "Lenient (d=0.020)"
)]

colour_vals <- c("#0072B2", "#009E73", "#E69F00")
names(colour_vals) <- c("Strict (d=0.005)", auto_label, "Lenient (d=0.020)")

p_d <- ggplot() +
  geom_line(
    data = dt_growth,
    aes(x = t, y = observed),
    colour = "grey70", linewidth = 0.5
  ) +
  geom_line(
    data = dt_long,
    aes(x = t, y = trend, colour = delta),
    linewidth = 0.9
  ) +
  annotate("rect",
           xmin = as.Date("2020-01-01"), xmax = as.Date("2020-10-01"),
           ymin = -Inf, ymax = Inf, alpha = 0.1, fill = "firebrick") +
  annotate("text", x = as.Date("2020-04-01"), y = Inf,
           label = "COVID Q2\n-9% q-o-q", vjust = 1.4,
           size = 3.2, colour = "firebrick") +
  scale_colour_manual(values = colour_vals) +
  labs(
    title    = "MBH Trend Sensitivity to Huber Delta d",
    subtitle = "Data: US quarterly GDP growth rates (log-diff)",
    x        = NULL, y = "Log-difference", colour = "d setting"
  ) +
  theme_minimal(base_size = 12) +
  theme(legend.position = "top")

print(p_d)

Interpretation

• Strict d = 0.005 (blue): Huber threshold is tight; even modest growth rate swings are down-weighted. The trend is nearly flat, absorbing almost no cyclical signal.
• Auto d (green): threshold is calibrated to normal volatility. The COVID spike is substantially down-weighted but ordinary fluctuations are fitted.
• Lenient d = 0.020 (orange): threshold is loose; the filter behaves close to $L_2$ boosting and the trend responds to the COVID shock.

---

4 Computational Trade-off Benchmark

y          <- us_gdp_vintage$gdp_log
mstop_grid <- seq(100L, 1000L, by = 100L)   # 10 evenly-spaced points
n_rep      <- 5L                            # replicates per point

# Single-shot timings are dominated by GC pauses and OS scheduling, which
# produce spurious spikes. We warm up once, then time several runs with a
# clean heap (gc()) before each and report the MEDIAN, recovering the
# monotone wall-time vs mstop relationship.
bench_dt <- rbindlist(lapply(mstop_grid, function(m) {
  res  <- suppressMessages(mbh_filter(y, mstop = m))   # warm-up + cycle SD
  reps <- vapply(seq_len(n_rep), function(i) {
    gc(verbose = FALSE)
    t0 <- proc.time()
    suppressMessages(mbh_filter(y, mstop = m))
    (proc.time() - t0)[["elapsed"]]
  }, numeric(1))
  data.table(
    mstop       = m,
    elapsed_sec = round(median(reps), 3),
    cycle_sd    = round(sd(res$cycle), 6)
  )
}))

knitr::kable(
  bench_dt,
  col.names = c("mstop", "Wall time (s)", "Cycle SD"),
  caption   = sprintf("MBH computational benchmark — US log GDP (%d obs)", length(y))
)

# Dual-axis layout: wall time (left) + cycle_sd convergence (right)
# Use a secondary-axis trick by normalising cycle_sd to the time scale
time_range  <- range(bench_dt$elapsed_sec)
sd_range    <- range(bench_dt$cycle_sd)
# Guard against division by zero if cycle_sd converges to a flat line
if (diff(sd_range)   < 1e-10) sd_range   <- sd_range   + c(-1e-5,  1e-5)
if (diff(time_range) < 1e-10) time_range <- time_range + c(-1e-5,  1e-5)
sd_to_time  <- function(x) (x - sd_range[1]) / diff(sd_range) * diff(time_range) + time_range[1]
time_to_sd  <- function(x) (x - time_range[1]) / diff(time_range) * diff(sd_range) + sd_range[1]

p_bench <- ggplot(bench_dt, aes(x = mstop)) +
  geom_line(aes(y = elapsed_sec), colour = "#0072B2", linewidth = 1) +
  geom_point(aes(y = elapsed_sec), colour = "#CC0000", size = 3) +
  geom_line(aes(y = sd_to_time(cycle_sd)),
            colour = "#E69F00", linewidth = 0.9, linetype = "dashed") +
  geom_point(aes(y = sd_to_time(cycle_sd)),
             colour = "#E69F00", size = 2.5) +
  scale_x_continuous(breaks = mstop_grid) +
  scale_y_continuous(
    name     = "Wall time (s)  [blue / red points]",
    sec.axis = sec_axis(~ time_to_sd(.), name = "Cycle SD  [orange dashed]",
                        labels = scales::label_number(accuracy = 0.0001))
  ) +
  labs(
    title    = "Wall Time vs Boosting Iterations",
    subtitle = sprintf("US Real GDP log level (%d obs). Cycle SD plateaus well before mstop = 500.", length(y)),
    x        = "mstop"
  ) +
  theme_minimal(base_size = 12) +
  theme(
    axis.title.y.left  = element_text(colour = "#0072B2"),
    axis.title.y.right = element_text(colour = "#E69F00")
  )

print(p_bench)

Practical guidance

| Use case | Recommended settings | |---|---| | Interactive / exploratory | mstop = 100–200 | | Publication-quality output | mstop = 500 (default) | | Long daily series (n > 5 000) | mstop = 50, nu = 0.3 | | Cross-country batch estimation | mstop = 200, nu = 0.15 |

Gains in cycle standard deviation (a proxy for fit quality) diminish rapidly above mstop = 200 for a typical macro series. The default mstop = 500 provides a comfortable safety margin without being prohibitively slow.

---

5 Summary

summary_tbl <- data.table(
  Parameter = c("`mstop`", "`nu`", "`knots`", "`d`"),
  Default   = c("500", "0.1", "`min(max(20, n/2), 250)`", "auto via MAD"),
  `When to increase` = c(
    "Publication accuracy required",
    "Very long series; computational budget tight",
    "Highly nonlinear trend",
    "Series has frequent large spikes"
  ),
  `When to decrease` = c(
    "Exploratory / fast iteration",
    "Stability preferred over speed",
    "Short series or near-linear trend",
    "Series is log-level (use `mad(hp$cycle)` instead)"
  )
)
knitr::kable(summary_tbl, caption = "MBH hyperparameter quick-reference")

MacroFilters documentation built on June 12, 2026, 1:06 a.m.