RainbowStats™ · Command reference

Threshold Regression

Explore how a linear relationship changes when an explanatory variable crosses a threshold.

THRESHOLD_REGRESSION searches for the split that produces the best two-regime linear fit. FIXED_THRESHOLD_REGRESSION uses a threshold you supply. Both compare separate regime regressions with a pooled model and share the same results and extracts, apart from the searched threshold’s SSR profile.

Quick start: two labor-market regimes

tr = THRESHOLD_REGRESSION(LIST(SERIES_SINCE(UNRATE,20010101),SERIES_SINCE(U6RATE,20010101)),1,36)
EXTRACT(tr,"slideshow")

Run this example in RainbowStats

This example models the unemployment rate using U-6 and searches for a threshold in U-6. The sample begins in January 2001, and each regime must contain at least 36 observations. Both series are monthly rates.

Column numbers start at zero. In LIST(UNRATE,U6RATE), column 0 is the dependent variable and column 1 is the explanatory variable used to divide the sample. The threshold is a value of U-6, not a date.

Choose a searched or fixed threshold

Search for the best threshold

THRESHOLD_REGRESSION(seriesList,splitColumn)
THRESHOLD_REGRESSION(seriesList,splitColumn,minSideObservations)

Use a specified threshold

FIXED_THRESHOLD_REGRESSION(seriesList,splitColumn,threshold)

Argument	Meaning
`seriesList`	A list of time series. The first series is the dependent variable; all remaining series are explanatory variables. A constant is included in the regime and pooled regressions.
`splitColumn`	Zero-based position of the explanatory variable that defines the regimes: `1` selects the first explanatory series, `2` the second, and so on.
`minSideObservations`	Optional minimum observations required in each regime during the search. If omitted, the underlying fitting routine chooses the default. The summary reports the effective minimum.
`threshold`	Finite numeric cutoff in the selected split variable’s units, used only by `FIXED_THRESHOLD_REGRESSION`.

The third argument has a different meaning in each command. THRESHOLD_REGRESSION(list,1,36) sets a minimum of 36 observations per regime. FIXED_THRESHOLD_REGRESSION(list,1,10) fixes the split at a value of 10. The fixed command has no minimum-side argument in the supplied operator interface.

The split variable remains an explanatory variable in each regression. Other explanatory variables are also included, and their coefficients can differ between regimes.

How threshold regression works

For a threshold c in the selected explanatory variable z, observations enter one of two regimes:

Regime	Rule
Lower / at or below	`z ≤ c`
Upper / above	`z > c`

Separate ordinary least squares regressions estimate the intercept and explanatory-variable slopes in each regime:

y[t] = alpha_lower + beta_lower′ X[t] + error[t]     when z[t] ≤ c
y[t] = alpha_upper + beta_upper′ X[t] + error[t]     when z[t] > c

combined_SSR(c) = SSR_lower(c) + SSR_upper(c)

In searched mode, the chosen threshold minimizes combined SSR over admissible candidate splits, subject to the minimum-side requirement. The existing command methodology evaluates thresholds between distinct observed values of the split variable. In fixed mode, the supplied cutoff is used without searching.

The pooled model fits one set of coefficients across the full estimation sample. Comparing pooled and split SSR measures the in-sample improvement from allowing separate regimes.

State-dependent, not a chronological split. An observation belongs to a regime because of its split-variable value. Dates from different years can belong to the same regime, and neighboring dates can fall on opposite sides. Separate intercepts allow a discontinuity at the threshold; the two fitted relationships need not meet.

What the results show

The optimal or fixed threshold and its units.
Observation counts for the two regimes.
The split variable’s slope and t-statistic in each regime.
Pooled SSR, combined split SSR, and the absolute and percentage reduction in SSR.
An F-style diagnostic with numerator and denominator degrees of freedom.
Actual-versus-fitted regime charts and detailed coefficient results in the diagnostic slideshow.
An SSR profile across candidate thresholds in searched mode.

The summary’s slope fields refer to the selected split variable. For other explanatory variables, use the full below_model, above_model and pooled_model tables.

EXTRACT — Tables, charts, residuals and statistics

EXTRACT(tr,"extract_name")

Extract names are case-insensitive, and surrounding whitespace is trimmed. Both modes support the following results, except for the searched-only profile.

Primary name	Aliases	Returns and meaning
`model`	`summary`, `threshold_model`	Threshold summary table; threshold and units, regime counts, split-variable slopes and t-statistics, SSR comparisons and F diagnostic.
`slideshow`	—	Complete diagnostic slideshow for the selected mode.
`ssr_profile`	`threshold_profile`	Combined SSR across candidate thresholds, with the selected optimum annotated. Searched mode only.
`below_model`	`below`	Lower-regime coefficient table: intercept and all explanatory variables, standard errors, t-statistics, R², adjusted R², Durbin–Watson and observation count.
`above_model`	`above`	Upper-regime coefficient table with the same statistics.
`pooled_model`	`pooled`	Single-regime regression table fitted to the pooled estimation sample.
`pooled_residuals`	—	Data series of residuals from the pooled regression, retaining the dependent series’ dates, frequency and units for complete estimation rows.
`threshold`	—	Number: the selected threshold, or the supplied fixed threshold.
`below_slope`	—	Number: slope of the selected split variable in the lower regime.
`above_slope`	—	Number: slope of the selected split variable in the upper regime.
`below_tstat`	—	Number: t-statistic for that lower-regime slope.
`above_tstat`	—	Number: t-statistic for that upper-regime slope.
`pooled_ssr`	—	Number: pooled regression’s residual sum of squares.
`split_ssr`	—	Number: sum of the two regime residual sums of squares.
`ssr_improvement`	—	Number: pooled SSR minus split SSR.
`ssr_improvement_pct`	—	Number: percentage reduction in SSR relative to pooled SSR.
`f_stat`	`f_statistic`	Number: F-style diagnostic comparing pooled and split fits.
`below_observations`	—	Number: lower-regime estimation observations.
`above_observations`	—	Number: upper-regime estimation observations.

The profile requires a search. Extracting ssr_profile or threshold_profile from a fixed-threshold model returns an error. The fixed model has no candidate-search curve.

pooled_residuals returns a reusable data series, not a chart and not the residuals of the two-regime model. The supplied operator has no residuals, fitted, hac or p-value extract. Use the names in this table rather than assuming all linear-regression extracts also apply here.

Examples: search, compare and inspect

Search and inspect the SSR profile

l = LIST(SERIES_SINCE(UNRATE,20010101),SERIES_SINCE(U6RATE,20010101))
tr = THRESHOLD_REGRESSION(l,1,36)
SLIDESHOW(EXTRACT(tr,"model"),EXTRACT(tr,"ssr_profile"),EXTRACT(tr,"below_model"),EXTRACT(tr,"above_model"),EXTRACT(tr,"pooled_model"))

Use an economic cutoff chosen in advance

l = LIST(SERIES_SINCE(UNRATE,20010101),SERIES_SINCE(U6RATE,20010101))
fixed = FIXED_THRESHOLD_REGRESSION(l,1,10)
EXTRACT(fixed,"slideshow")

This divides the model at a U-6 rate of 10%: observations at or below 10 belong to the lower regime; values above 10 belong to the upper regime. Fixing a threshold chosen after repeatedly inspecting the same data does not remove the effects of that search.

Add another explanatory variable

l = LIST(SERIES_SINCE(UNRATE,20010101),SERIES_SINCE(U6RATE,20010101),SERIES_SINCE(TCU,20010101))
tr = THRESHOLD_REGRESSION(l,1,36)
EXTRACT(tr,"slideshow")

This retains U-6 as the threshold variable and adds capacity utilization as another predictor. Both predictors and the intercept are estimated separately in each regime. Use splitColumn = 2 if you want capacity utilization to define the regimes instead.

Chart pooled-model residuals

tr = THRESHOLD_REGRESSION(LIST(SERIES_SINCE(UNRATE,20010101),SERIES_SINCE(U6RATE,20010101)),1,36)
LINE_CHART(EXTRACT(tr,"pooled_residuals"))

The residual series preserves dates for complete estimation rows and inherits the dependent series’ frequency and units. This is useful for examining what the single-regime model leaves unexplained.

Retrieve individual statistics

tr = THRESHOLD_REGRESSION(LIST(SERIES_SINCE(UNRATE,20010101),SERIES_SINCE(U6RATE,20010101)),1,36)
cutoff = EXTRACT(tr,"threshold")
lower_slope = EXTRACT(tr,"below_slope")
upper_slope = EXTRACT(tr,"above_slope")
improvement = EXTRACT(tr,"ssr_improvement_pct")
f = EXTRACT(tr,"f_stat")

Reserve abundance and the federal funds spread

r = SET_UNITS(toWeekly(WRESBAL)/1000,"Billions of Dollars")
s = (toWeekly(DFF)-toWeekly(IORB))*100
l = same_Date_Range(LIST(s,r))
THRESHOLD_REGRESSION(l,1)

This retains the original command-page example. It searches for a reserve-balances threshold that separates the relationship between reserve abundance and the effective federal funds rate relative to IORB. The reserve series is scaled to billions of dollars, and the rate spread is converted from percentage points to basis points.

Interpret the threshold and fit improvement

Result	How to read it
Threshold	The selected or supplied boundary in the split variable’s units. Its economic meaning depends on the variable and sample.
Regime coefficients	Compare signs, magnitudes and uncertainty across the lower and upper models. The reported slope t-statistics test individual coefficients against zero; they do not directly test equality of the two slopes.
SSR improvement	`pooled_ssr − split_ssr`. The percentage measure is `100 × improvement / pooled_ssr` when the pooled denominator is positive.
SSR profile	A sharp minimum suggests the sample fit favors a localized threshold; a flat profile suggests nearby cutoffs fit similarly. The curve is not a threshold confidence interval.
F statistic	A fit-comparison diagnostic. In searched mode, the threshold was selected from the same data, so conventional fixed-break significance rules do not automatically apply.
Durbin–Watson	Residual-dependence diagnostic in each regression table. Regime observations can be irregularly spaced in calendar time, which matters when interpreting dependence.

A large SSR reduction and materially different coefficients can indicate that a pooled linear model hides a state-dependent relationship. Additional flexibility also improves in-sample fit, so inspect the size of each regime, economic plausibility and stability across samples.

Search affects inference. A searched threshold needs threshold-specific inference, such as an appropriate bootstrap, for a formal significance claim. The operator does not supply a threshold confidence interval, a search-adjusted p-value or HAC inference. A fixed threshold avoids the command’s search step, but conventional inference still depends on its statistical assumptions.

Working with the data

Align frequency and timing. The constructor uses getSameDateRange(). Prepare compatible series frequencies, inspect gaps and verify that variables refer to the intended economic periods.
Use enough data in each regime. Select a minimum-side count that supports all estimated coefficients. More predictors require more information, and a fixed cutoff must leave estimable observations on both sides.
Check variation and redundancy. A constant predictor, duplicate series or exact collinearity within a regime can prevent estimation even if the pooled sample appears usable.
Control the sample. Use SERIES_SINCE or SERIES_BETWEEN before fitting. Differing source coverage and missing values can reduce the estimation sample.
Consider transformations. Trending levels can create misleading fit. Match the specification to the economic question and consider changes or log changes where appropriate.
Inspect stability. A threshold can move as observations, data revisions or predictor choices change. In-sample fit does not establish causality or out-of-sample forecast performance.