Cryptocurrency Volatility Prediction

Predicts near-term cryptocurrency volatility from historical OHLCV and market-cap data to support risk management, portfolio allocation, and trading-strategy decisions.

Problem Statement

See docs/ for full design docs. In short: cryptocurrency markets are highly volatile; this project builds an ML model that forecasts volatility levels from historical price/volume/market-cap data so that traders and institutions can anticipate and manage risk proactively.

Project Structure

crypto-volatility-prediction/
├── data/
│   ├── raw/                # raw input CSV (place real dataset here, or auto-generated)
│   └── processed/          # cleaned & feature-engineered datasets
├── src/
│   ├── data_loader.py       # data ingestion (+ synthetic data fallback)
│   ├── preprocessing.py     # cleaning, missing values, scaling
│   ├── feature_engineering.py  # technical indicators, liquidity ratios, target
│   ├── eda.py                # exploratory data analysis (stats + plots)
│   └── train_model.py        # model selection, tuning, evaluation
├── app/
│   └── streamlit_app.py      # local deployment / testing UI
├── models/                   # saved model, scaler, metadata (generated)
├── reports/                  # EDA summary, model evaluation, final report, figures
├── docs/
│   ├── HLD.md                 # High-Level Design
│   ├── LLD.md                 # Low-Level Design
│   └── pipeline_architecture.md
├── requirements.txt
└── README.md

Dataset

Uses the real Cryptocurrency Historical Prices dataset: daily OHLCV + market-cap data for 55 cryptocurrencies (Bitcoin, Ethereum, Litecoin, XRP, Dogecoin, Solana, Cardano, and 48 others), 2013-05-05 to 2022-10-23 (~72,900 rows). It's already included at data/raw/crypto_data.csv.

Original columns (open, high, low, close, volume, marketCap, timestamp, crypto_name, date) are automatically mapped by src/data_loader.py onto the project's canonical schema (date, symbol, open, high, low, close, volume, market_cap) — no manual renaming needed.

Want to swap in a different/updated dataset? Just replace data/raw/crypto_data.csv with your CSV. The loader recognizes common column-name variants (crypto_name/name/coin → symbol, marketCap/market_capitalization → market_cap) automatically.

No dataset at all? If data/raw/crypto_data.csv is missing, src/data_loader.py falls back to generating a realistic synthetic multi-coin dataset (regime-switching volatility model) so the pipeline always runs out of the box.

Setup

python -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
pip install -r requirements.txt

Running the Pipeline (step by step)

# 1. Load data (auto-generates synthetic data if data/raw/crypto_data.csv is absent)
python src/data_loader.py

# 2. Clean & preprocess
python src/preprocessing.py

# 3. Feature engineering (technical indicators + target variable)
python src/feature_engineering.py

# 4. Exploratory Data Analysis (writes plots to reports/figures/)
python src/eda.py

# 5. Train, tune, and evaluate models (saves the best model to models/)
python src/train_model.py

Running the App (local deployment)

streamlit run app/streamlit_app.py

Opens a local browser UI to pick a coin/date and see the predicted vs. actual volatility, current price, and a risk-level flag.

Deliverables

1. Machine Learning Model — models/best_model.joblib (+ scaler, metadata)
2. Data Processing & Feature Engineering — data/processed/, src/preprocessing.py, src/feature_engineering.py
3. EDA Report — reports/eda_summary.md, reports/descriptive_stats.csv, reports/figures/
4. Project Documentation — docs/HLD.md, docs/LLD.md, docs/pipeline_architecture.md, reports/final_report.md

Methodology Summary

Data is cleaned (missing-value interpolation, OHLC consistency checks), enriched with 14 engineered features (moving averages, Bollinger Bands, ATR, RSI, liquidity ratios, rolling volatility), then used to train and hyperparameter-tune three regressors — Linear Regression, Random Forest, and Gradient Boosting — using time-series-aware cross-validation to avoid lookahead bias. The best model (by RMSE on a chronological holdout) is selected and served through a Streamlit app. Full results are in reports/final_report.md.

License

MIT