regime_definition#

Back to L1 | Browse all axes | Browse all options

Axis regime_definition on sub-layer l1_g (layer l1).

Sub-layer#

l1_g

Axis metadata#

  • Default: 'none'

  • Sweepable: False

  • Status: operational

Operational status summary#

  • Operational: 6 option(s)

  • Future: 0 option(s)

Options#

none – operational#

No regime structure – the cell-loop sees a single time-invariant world.

Default. The L1 regime metadata sink is empty; downstream layers that conditionally reference regime info (L4 regime_wrapper, L5 by_regime decomposition, L6.C cpa conditioning) are inactive.

When to use

Default for any study without an explicit regime structure.

References

  • macroforecast design Part 1, L1: ‘data definition is the recipe layer that pins source, target, geography, and horizon – everything downstream branches off these choices.’

Related options: external_nber, external_user_provided, estimated_markov_switching

Last reviewed 2026-05-04 by macroforecast author.

external_nber – operational#

NBER recession dates loaded from the bundled USREC series.

Loads the NBER official recession indicator (USREC) and emits a two-state regime label (‘expansion’ / ‘recession’) per observation. No estimation – the labels come directly from NBER’s published business-cycle dates.

Pairs with L4 regime_wrapper = separate_fit for regime-conditional forecasting and with L5 by_regime decomposition for state-dependent metrics.

When to use

Standard recession-conditioning studies; comparing models’ performance during recessions vs expansions.

References

  • macroforecast design Part 1, L1: ‘data definition is the recipe layer that pins source, target, geography, and horizon – everything downstream branches off these choices.’

  • National Bureau of Economic Research, ‘US Business Cycle Expansions and Contractions’. https://www.nber.org/research/business-cycle-dating

Related options: none, external_user_provided

Examples

NBER-conditioned ridge

1_data:
  fixed_axes:
    regime_definition: external_nber

Last reviewed 2026-05-04 by macroforecast author.

external_user_provided – operational#

User-supplied regime label series.

Requires leaf_config.regime_indicator_path (CSV / Parquet with date + label columns) or leaf_config.regime_dates_list (inline date ranges per label). The L1 runtime aligns the labels to the panel index without estimation.

Useful for custom regime definitions: monetary-policy-stance labels, fiscal-stance labels, geographic-dummy regimes, etc.

When to use

Custom regime studies (monetary stance, fiscal stance, alternative recession-dating chronologies).

References

  • macroforecast design Part 1, L1: ‘data definition is the recipe layer that pins source, target, geography, and horizon – everything downstream branches off these choices.’

Related options: none, external_nber

Parameters

name

type

default

constraint

description

regime_indicator_path

`str

Path`

—

Exactly one of {regime_indicator_path, regime_dates_list} must be set when regime_definition=external_user_provided.

regime_dates_list

list[dict]

—

Exactly one of {regime_indicator_path, regime_dates_list} must be set when regime_definition=external_user_provided. Each dict must have keys: start (ISO date), end (ISO date), label (str).

Inline regime-date specification as a list of {start, end, label} dicts. Dates are interpreted as inclusive bounds. Gaps between ranges receive label None.

n_regimes

int

2

Positive integer. Informational only for external_user_provided.

Declared number of distinct regime labels in the user-supplied series. Used by downstream metrics and L5 by_regime decomposition.

Last reviewed 2026-05-04 by macroforecast author.

estimated_markov_switching – operational#

Hamilton (1989) Markov-switching regime estimated from the target.

Fits statsmodels.tsa.regime_switching.MarkovRegression with leaf_config.n_regimes (default 2) regimes and switching variance. Returns smoothed posterior probabilities, the argmax label per observation, and the estimated transition matrix.

The estimation is per-origin (no leakage) via regime_estimation_temporal_rule: expanding_window_per_origin (default) or rolling_window_per_origin / block_recompute.

When to use

Inflation-regime studies; recession-prediction; any study that wants endogenous regime estimation.

References

  • macroforecast design Part 1, L1: ‘data definition is the recipe layer that pins source, target, geography, and horizon – everything downstream branches off these choices.’

  • Hamilton (1989) ‘A new approach to the economic analysis of nonstationary time series and the business cycle’, Econometrica 57(2). (doi:10.2307/1912559)

Related options: estimated_threshold, estimated_structural_break, regime_estimation_temporal_rule, n_regimes

Parameters

name

type

default

constraint

description

n_regimes

int

2

Positive integer >= 2. Passed to statsmodels MarkovRegression as k_regimes.

Number of Markov-switching regimes. Defaults to 2 (expansion/recession). Higher values increase estimation cost quadratically.

Last reviewed 2026-05-04 by macroforecast author.

estimated_threshold – operational#

Tong (1990) SETAR threshold model – regime by threshold variable.

Estimates n_regimes regimes by grid-searching the threshold on a chosen threshold_variable (defaults to lagged target). The regime per observation is determined by which side of the threshold the variable falls on.

Tong’s original SETAR uses AR(p) per regime; macroforecast’s runtime fits AR(threshold_ar_p) per partition and selects the threshold minimising joint SSR.

When to use

Self-exciting threshold dynamics (e.g., interest-rate stance regimes); non-linear AR studies.

References

  • macroforecast design Part 1, L1: ‘data definition is the recipe layer that pins source, target, geography, and horizon – everything downstream branches off these choices.’

  • Tong (1990) ‘Non-linear Time Series: A Dynamical System Approach’, Oxford University Press.

Related options: estimated_markov_switching, estimated_structural_break

Parameters

name

type

default

constraint

description

threshold_variable

str

—

Required when regime_definition=estimated_threshold. Must be a column name present in the panel or ‘lagged_target’.

Series used to determine regime membership. Each observation is assigned to a regime based on whether threshold_variable exceeds the estimated threshold value.

n_thresholds

int

1

Optional. Positive integer; n_thresholds+1 regimes are created. Must be >= 1.

Number of threshold breakpoints to estimate. 1 threshold -> 2 regimes (low/high). 2 thresholds -> 3 regimes (low/mid/high), etc.

Last reviewed 2026-05-04 by macroforecast author.

estimated_structural_break – operational#

Bai-Perron (1998) global LSE break detection.

Detects up to leaf_config.max_breaks structural breaks via the Bai (1997) dynamic-programming exact recursion + BIC selection. Each segment between breaks becomes a regime.

When to use

Studies hypothesising structural change (e.g., pre/post Volcker, pre/post Great Moderation).

References

  • macroforecast design Part 1, L1: ‘data definition is the recipe layer that pins source, target, geography, and horizon – everything downstream branches off these choices.’

  • Bai & Perron (1998) ‘Estimating and testing linear models with multiple structural changes’, Econometrica 66(1). (doi:10.2307/2998540)

Related options: estimated_markov_switching, estimated_threshold, max_breaks

Parameters

name

type

default

constraint

description

max_breaks

int

5

Optional. Positive integer; upper bound on break count searched by the Bai-Perron dynamic program.

Maximum number of structural breaks to detect. BIC selects the final break count <= max_breaks. Larger values increase computation time.

break_ic_criterion

str

'bic'

Optional. One of {‘aic’, ‘bic’}. Controls model-selection criterion for break-count choice.

Information criterion used to select the number of breaks. ‘bic’ (default) penalises extra breaks more heavily; ‘aic’ is less conservative.

Last reviewed 2026-05-04 by macroforecast author.