Regimes Replication

Step-by-Step Instructions

1. Run State Variables

python cli.py state-variables

This calculates the 7 economic state variables:

• Market level (log S&P 500)
• Yield curve (10Y - 3M spread)
• Oil price (WTI)
• Copper price
• Monetary policy (3M T-bill)
• Volatility (realized vol / VIX)
• Stock-bond correlation

Output: Raw data, z-scores, and winsorized data saved to cache/ directory.

2. Run Factor Returns

python cli.py factor-returns

This downloads and processes factor return data from various sources.

Output: Factor return data saved to cache/ directory.

3. Run Similarity Score

python cli.py similarity-score

This calculates similarity scores between different time periods based on the state variables.

Output: Similarity scores saved to cache/ directory.

4. Run Backtest

python cli.py backtest

This runs the main backtesting engine for the regime-based factor strategy.

Output: Backtest results and performance metrics saved to cache/ directory.

5. Find Similar Periods (Optional)

To analyze similar periods to a specific date:

1. Edit the configuration:

   • Open config.yaml
   • Change similarity_score.mask_horizon from 36 to 0
   • Change similar_periods.target_month to your desired date (e.g., "2022-01")

2. Re-run similarity score:

   python cli.py similarity-score

3. Run similar periods analysis:

   python cli.py similar-periods

Output: Visualization of similar periods saved to reports/ directory.

Configuration Options

You can customize parameters by editing config.yaml or using command-line arguments:

# Example: Run backtest with custom parameters
python cli.py backtest --start-date 1990-01-31 --vol-target 0.12 --n-buckets 5

# Example: Find similar periods for a specific month
python cli.py similar-periods --target-month 2008-10

# Example: Save configuration snapshots
python cli.py state-variables --save-config my_config

Output Files

• Cache Directory (cache/): Contains processed data files (.pkl format)
• Reports Directory (reports/): Contains generated visualizations and charts
• Data Directory (data/): Contains raw input data files

Troubleshooting

• Ensure all required data files are present in the data/ directory
• Verify internet connection for downloading FRED and yfinance data
• If you encounter memory issues, consider reducing the date range in config.yaml