Transition Risk & Score Evaluation
Relevant source files
The following files were used as context for generating this wiki page:
The Transition Risk & Score Evaluation system is responsible for calculating "transition pressure" within market regimes. It serves as a composer that aggregates normalized component scores from various market dimensions—such as volatility, breadth, and correlation—to produce a single, normalized 0.0 to 1.0 pressure score. This score, alongside dynamic rule-based overrides, determines the transition risk state (e.g., stable, weakening, high_transition_risk) for a given trading session.
The system is designed to be resilient to missing data by dynamically reweighting available components, provided a minimum weight coverage threshold is met. It bridges raw technical indicators and high-level strategy responses by categorizing market environments into risk bands and identifying primary drivers of instability.
Sources: src/regime_detection/transition_score.py:1-8, src/regime_detection/transition_risk_series.py:465-485
Core Score Composition
The system calculates a ComposedTransitionScore by normalizing multiple market signals into 0..1 stress components. These components are then weighted according to system configuration.
Component Normalization Logic
Each component is calculated using specific formulas and clipped between 0.0 and 1.0. The following table details the logic for key components:
| Component | Logic / Formula | Primary Scale Config |
|---|---|---|
| Volatility Acceleration | Ratio of short-term to long-term realized volatility. | vol_acc_full_stress_ratio |
| Breadth Deterioration | Percentage of stocks above their 50-day moving average. | breadth_zero_stress_pct |
| Trend Break | Maximum of recent drawdowns and price distance from 50-DMA. | drawdown_full_stress |
| Correlation Fragility | Max of pairwise correlation, eigenvalue share, and absorption ratio. | absorption_floor |
| Liquidity Stress | Max of volume Z-scores, gap frequency, and intraday range. | volume_zscore_floor |
Sources: src/regime_detection/transition_score.py:126-177, src/regime_detection/_config_evidence_strategy.py:11-45
Data Flow for Score Calculation
The flow below illustrates how raw inputs are transformed into a final transition score and interpretation.
Transition Risk States and Overrides
While the transition score provides a continuous metric, the system uses a set of hard-coded and configurable rules to determine the final state. These rules can override the score-based interpretation.
Logic Precedence
The system evaluates rules in a specific order of precedence. For example, a crisis signal or bear_stress override will take priority over a generic weakening interpretation derived from the score bands.
Rule Definitions
- Fragile Bull: Triggered when the market is in a
bulltrend but exhibits high correlation fragility or credit stress. - Bear Stress: Triggered in a
beartrend when combined with high volatility and breadth deterioration. - Event Transition Watch: A specialized state triggered when a
macro_event(e.g., Fed week, CPI release) is the dominant driver of an elevated score. - Post Switch Cooldown: A temporary "watch" state applied for a configurable number of days (default 5) following a change in the stable regime axis.
Sources: src/regime_detection/transition_risk_series.py:490-530, src/regime_detection/_config_evidence_strategy.py:75-78
State Debouncing and Confirmation
To prevent "flip-flopping" between states due to minor data fluctuations, the system implements a state confirmation mechanism.
Debounce Mechanism
Each state has a required number of consecutive days it must be observed before it becomes the "active" public state.
- Stable: Usually requires 1 day (immediate).
- High Transition Risk: May require multiple days (e.g., 2 or 3) for confirmation.
If a new state is detected but has not yet met thestate_confirmation_daysthreshold, the system continues to report the previousactive_statebut marks it with astate_confirmation_pendingflag in the triggered rules.
Sources: src/regime_detection/transition_risk_series.py:557-610, src/regime_detection/_config_evidence_strategy.py:80-82
Configuration and Calibration
The transition evaluation is highly configurable through the TransitionScoreConfig and TransitionOverrideThresholds classes.
Threshold Configuration
| Parameter | Default | Description |
|---|---|---|
credit_stress | 0.70 | Threshold for credit stress to trigger overrides. |
correlation_fragility | 0.70 | Threshold for correlation stress to trigger overrides. |
macro_event_min | 1.0 | Minimum macro component score to trigger a watch. |
score_elevated_min | 0.35 | The weighted score level considered "elevated". |
primary_driver_min | 0.35 | Minimum component score to be listed as a "primary driver". |
Sources: src/regime_detection/_config_evidence_strategy.py:54-71, tests/test_transition_overrides_and_band_validation.py:155-165
Band Validation
The system enforces strict monotonicity on the transition score bands via Pydantic validators. The bands (stable, weakening, transition_warning, high) must have strictly increasing lower bounds between 0.0 and 1.0.
Sources: src/regime_detection/_config_evidence_strategy.py:101-125
Summary of Key Components
The following table summarizes the primary classes used in the transition risk system:
| Class | File Path | Purpose |
|---|---|---|
ComposedTransitionScore | transition_score.py | Data structure holding the final score, interpretation, and component breakdown. |
TransitionRiskOutput | models.py | The final serialized model containing state, evidence, and drivers. |
TransitionRiskHistory | transition_risk_series.py | Tracks axis switches and prior bear markets for rule evaluation. |
TransitionScoreConfig | _config_evidence_strategy.py | Pydantic model for weights, bands, and debounce settings. |
Sources: src/regime_detection/transition_score.py:53-60, src/regime_detection/transition_risk_series.py:35-42, src/regime_detection/_config_evidence_strategy.py:73-100
Conclusion
Transition Risk & Score Evaluation provides a robust framework for detecting the early stages of regime shifts. By combining quantitative scoring with heuristic overrides and temporal debouncing, the system ensures that strategy responses are both timely and stable, minimizing false positives while capturing significant market stress events.
Sources: src/regime_detection/transition_score.py:1-6, src/regime_detection/transition_risk_series.py:465-470