Liquidity & Credit Funding Axes
Relevant source files
The following files were used as context for generating this wiki page:
The Liquidity and Credit Funding axes are core components of the V2 regime detection engine, designed to identify market stress originating from volume anomalies, liquidity gaps, and credit market dislocations. These axes function as Layer 1 (Volume/Liquidity) and Layer 2 (Credit/Funding) classifiers that feed into the overall Transition Score to determine systemic risk levels.
The Volume/Liquidity axis specifically monitors panic-driven volume and price-gap behavior, while the Credit/Funding axis tracks Option-Adjusted Spreads (OAS) and total-return differentials across high-yield and investment-grade sectors. Together, they provide a multi-dimensional view of market plumbing and capital availability.
Sources: src/regime_detection/configs/core3-v2.0.0.yaml:302-315, src/regime_detection/volume_liquidity_rules.py:1-20
Volume & Liquidity Axis (V2 §1E)
The Volume/Liquidity axis implements a rule-based engine to classify market regimes based on trading activity and price action continuity. It utilizes z-scores of trading volume and percentile-based gap behavior to distinguish between normal market activity and panic states.
Classification Logic and Precedence
The engine evaluates rules in a strict hierarchy where higher-risk signals take precedence over lower-risk or neutral states. If required data is missing (e.g., during a cold-start period), the system defaults to an unknown status.
The precedence order is defined as: panic_volume > liquidity_gap_behavior > normal_volume > unknown.
Sources: src/regime_detection/volume_liquidity_rules.py:35-42, src/regime_detection/volume_liquidity_rules.py:162-171
Rule Predicates
Each label is triggered by specific quantitative conditions derived from market features:
| Label | Logic Description | Primary Thresholds |
|---|---|---|
panic_volume | High volume z-score combined with a sharp negative daily return. | Z-Score > 2.0 AND Return < -0.02 |
liquidity_gap_behavior | High frequency of price gaps and wide intraday ranges relative to historical percentiles. | Gap Freq Pctl > 0.75 AND Range Pctl > 0.75 |
normal_volume | Fall-through state when neither panic nor gap behavior is detected. | Negation of above |
Sources: src/regime_detection/volume_liquidity_rules.py:114-142, src/regime_detection/configs/core3-v2.0.0.yaml:283-290
Risk Ranking and Hysteresis
To prevent rapid "flip-flopping" between regimes, the axis applies asymmetric de-escalation days based on the risk rank of the current label.
| Label | Risk Rank | De-escalation Days |
|---|---|---|
panic_volume | 3 | 2 |
liquidity_gap_behavior | 2 | 2 |
unknown | 1 | 0 |
normal_volume | 0 | 0 |
Sources: src/regime_detection/volume_liquidity_rules.py:53-58, src/regime_detection/configs/core3-v2.0.0.yaml:296-300
Credit & Funding Axis (V2 §2C)
The Credit/Funding axis (Layer 2C) monitors systemic stress via credit spreads and dollar-funding liquidity. It employs a dual-metric approach, using both real Option-Adjusted Spreads (OAS) and total-return-differential proxies to ensure historical coverage.
Core Metrics and Data Sources
The axis tracks eight primary symbols, including High-Yield (HYG) and Investment-Grade (LQD) ETFs, Treasuries (TLT), and macro indicators like the Broad USD Index and the National Financial Conditions Index (NFCI).
The Effective State Resolver routes consumers to OAS labels when available, falling back to proxies when OAS data is unavailable (specifically for periods before May 2023 when FRED truncated certain OAS series).
Sources: src/regime_detection/configs/core3-v2.0.0.yaml:370-385, src/regime_detection/_config_layer2.py:255-265
Credit Stress Classification
The following regimes are identified by the Credit/Funding axis:
- Deleveraging: Triggered by severe volatility, high pairwise correlation, and falling equities/Treasuries.
- Funding Squeeze: Identified by sharp spikes in the Broad USD Index z-score.
- Credit Stress: Marked by High-Yield percentiles exceeding 0.80 and equity declines.
- Spread Widening: Detected via positive OLS slopes in both HY and IG OAS spreads.
- Credit Calm/Recovery: Baseline states indicating normalized credit market conditions.
Sources: src/regime_detection/_config_layer2.py:210-235, src/regime_detection/configs/core3-v2.0.0.yaml:387-400
Technical Implementation Details
Data Model and Output
Axis outputs are structured as Pydantic models to ensure type safety and consistent API responses. Each output includes the raw_label, stable_label (after hysteresis), and active_label.
# From src/regime_detection/models.py
class CreditFundingOutput(AxisOutput):
model_config = ConfigDict(extra="forbid")
raw_label: CreditFundingLabel
stable_label: CreditFundingLabel
active_label: CreditFundingLabel
Sources: src/regime_detection/models.py:246-258, src/regime_detection/models.py:302-315
Configuration Schemas
Thresholds for both axes are highly configurable to allow for recalibration without code changes.
# From src/regime_detection/configs/core3-v2.0.0.yaml
credit_funding:
rules:
hy_percentile_stress_min: 0.80
spy_drop_threshold: -0.05
broad_usd_zscore_funding_threshold: 1.5
realized_vol_percentile_threshold: 0.75
Sources: src/regime_detection/configs/core3-v2.0.0.yaml:387-395, src/regime_detection/_config_layer2.py:210-245
Summary
The Liquidity and Credit Funding axes provide critical infrastructure for detecting non-trend-based market risks. By combining high-frequency volume data with macro-level credit spreads, the engine can identify "plumbing" failures in the financial system that often precede broad market transitions. These modules ensure that the system remains robust even during data outages through the use of proxies and explicit unknown state handling.
Sources: src/regime_detection/volume_liquidity_rules.py:1-25, src/regime_detection/configs/core3-v2.0.0.yaml:370-380