cat > README.md << 'EOF'

Market Regime Classification with Unsupervised Learning

This project identifies distinct market regimes in U.S. equities using historical data and unsupervised learning.
The goal is to segment market behavior into interpretable states based on trend, volatility, and risk conditions.

Rather than predicting prices, the model focuses on classifying the environment in which different strategies and risk profiles apply.

---

What is a Market Regime?

A market regime is a recurring state of market behavior characterized by consistent patterns in:

• Returns and trend
• Volatility
• Drawdowns and risk sentiment

Institutional investors and risk teams use regime analysis to adjust exposure, leverage, and strategy selection.

---

Data

Daily data is sourced from Yahoo Finance:

• SPY (S&P 500 ETF)
• VIX (CBOE Volatility Index)

Time period: 2015–present.

---

Feature Engineering

The following interpretable features are constructed:

• Short- and medium-term returns (5d, 20d)
• Distance from 50-day and 200-day moving averages
• 20-day realized volatility
• VIX level and 5-day VIX change
• Drawdown from 252-day rolling high

---

Modeling Approach

An unsupervised KMeans clustering model is used to group trading days into regimes.

• Features are standardized prior to clustering
• Number of clusters: 4
• Clusters are interpreted and labeled post hoc based on their statistical properties

---

Visualization

---

How to Run

python src/download.py
python src/features.py
python src/train.py
python src/label.py
python src/plot.py