{"id":28089282,"url":"https://github.com/youhuipang/fx-risk-forecasting-system","last_synced_at":"2026-03-02T14:32:41.802Z","repository":{"id":289726245,"uuid":"972196633","full_name":"YouhuiPang/FX-Risk-Forecasting-System","owner":"YouhuiPang","description":"An intuitive end-to-end web-app system that forecasts FX risk over the next 3 days, powered by explainable AI and real market data.","archived":false,"fork":false,"pushed_at":"2025-05-01T06:35:56.000Z","size":3421,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-01T07:31:27.138Z","etag":null,"topics":["dashboard","explainable-ai","finance","flask","machine-learning","prediction","prediction-model","risk-analysis","risk-forecasting","risk-modelling","shap","xgboost"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/YouhuiPang.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-24T17:27:01.000Z","updated_at":"2025-05-01T06:49:32.000Z","dependencies_parsed_at":"2025-05-01T07:41:53.259Z","dependency_job_id":null,"html_url":"https://github.com/YouhuiPang/FX-Risk-Forecasting-System","commit_stats":null,"previous_names":["youhuipang/exchange_risk_project","youhuipang/fx-risk-forecasting-system-ml-based-volatility-modeling"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YouhuiPang%2FFX-Risk-Forecasting-System","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YouhuiPang%2FFX-Risk-Forecasting-System/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YouhuiPang%2FFX-Risk-Forecasting-System/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YouhuiPang%2FFX-Risk-Forecasting-System/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/YouhuiPang","download_url":"https://codeload.github.com/YouhuiPang/FX-Risk-Forecasting-System/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253948335,"owners_count":21988953,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dashboard","explainable-ai","finance","flask","machine-learning","prediction","prediction-model","risk-analysis","risk-forecasting","risk-modelling","shap","xgboost"],"created_at":"2025-05-13T12:55:53.714Z","updated_at":"2026-03-02T14:32:41.735Z","avatar_url":"https://github.com/YouhuiPang.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# Quantitative FX Risk Forecasting System \n## ML-Based Volatility Modeling\n\nThis project is a web-based FX risk prediction system designed to help users intuitively understand short-term currency volatility. It uses historical exchange rate data and macroeconomic indicators to predict the next 3-day risk level of currency pairs (e.g., USD/CNY) using a machine learning model. The final product is a visual dashboard that requires no financial background to interpret. \n\n---\n\n## ⚙️ Features\n\n- Real-time risk predictions (Low, Medium, High)\n- SHAP-based explanation of key influencing factors\n- Past 20-day risk forecast chart\n- Optional sentiment analyzer (Beta Not Functioning)\n- Fully functional Flask + Tailwind CSS frontend\n\n---\n\n## 🚀 Live Demo\n\n[![Visit Site](https://img.shields.io/badge/View-Live%20App-blue?style=for-the-badge)](https://fx-risk-forecasting-system.onrender.com)\n\nExplore the Quantitative FX Risk Forecasting System here:  \n🔗 https://fx-risk-forecasting-system.onrender.com\n\n---\n\n## 🏗️ System Architecture\n\nThis project follows a modular structure that separates data processing, model training, prediction logic, and frontend dashboard into clear components. Below is an overview of the system architecture:\n\n### 📁 `scripts/` – Core Logic Modules\n\n- `data_fetcher.py`: Merges raw exchange rate and macroeconomic data into engineered features.\n- `feature_engineer.py`: Creates time-series and macro interaction features (e.g. volatility, drawdown).\n- `model_trainer.py`: Trains XGBoost models (one per currency pair) with SMOTE+ENN for class balancing.\n- `predictor.py`: Loads the latest features and trained model to output risk level predictions and SHAP values.\n- `scheduler.py`: Automates daily data update and prediction via `schedule` library.\n- `get_exchange_data.py` / `get_macro_data.py`: Fetches raw data from Yahoo Finance and FRED.\n\n### 📁 `models/` – Saved Models\n\nContains trained models and selected feature sets for each currency pair (`.pkl` files).\n\n### 📁 `data/` – All Data Files\n\n- Raw data: `usd_cny.csv`, `macro.csv`\n- Engineered features: `features_*.csv`\n- Prediction outputs: `predictions_*.csv`\n- SHAP inputs and values: `shap_input_*.csv`, `shap_values_*.npy`\n\n### 📁 `frontend/` – Web Dashboard (Flask + Tailwind CSS)\n\n- `app.py`: Flask backend serving the dashboard and API.\n- `templates/index.html`: Main HTML structure styled with Tailwind CSS.\n- `static/js/main.js`: Handles real-time rendering of risk levels, forecasts, and sentiment analysis.\n- `static/css/style.css`: Optional custom styles.\n\n### 📁 `plots/` and `figures/` – Visualization Assets\n\n- `shap_summary_*.png`: SHAP visualizations for global feature importance.\n- `roc_curve.png`, `precision_recall_curve.png`: Performance metrics visualizations.\n\n### 🔁 Workflow Summary\n\n1. **Data Update**: `scheduler.py` triggers data fetching daily.\n2. **Data Fetching \u0026 Feature Engineering**: `data_fetcher.py` processes new raw data and update latest features.\n3. **Prediction**: `predictor.py` loads the latest features and model to generate risk predictions.\n4. **Web Display**: `app.py` serves the dashboard at `/`, and `/data` API responds with live predictions and SHAP-based key factor explanations.\n5. **Frontend Rendering**: `main.js` dynamically updates charts, risk level indicators, and sentiment fields.\n\n---\n\n## 🔧 Prerequisites\n\nBefore installing and running this project, make sure you have Python installed:\n\n- **Python 3.8 or higher**  \n  Download from: [https://www.python.org/downloads/](https://www.python.org/downloads/)\n\n- **(Recommended) Virtual Environment**  \n  It's best to isolate project dependencies using a virtual environment:\n  ```bash\n  python -m venv venv\n  source venv/bin/activate      # macOS / Linux\n  venv\\Scripts\\activate       # Windows\n  ```\n\n---\n\n## 🚀 Installation\n\n```bash\ngit clone https://github.com/YouhuiPang/FX-Risk-Forecasting-System.git\ncd FX-Risk-Forecasting-System\npip install -r requirements.txt\n```\n\n---\n\n## 🔧 Local Usage\n\n### To start the web dashboard:\n```bash\npython app.py\n```\nThen open your browser at [http://127.0.0.1:5000](http://127.0.0.1:5000)\n\n#### To manually update and predict:\n```bash\n# Step 1: Fetch the latest exchange rate + macroeconomic data\npython scripts/data_fetcher.py\n\n# Step 2: Run prediction using the latest features\npython scripts/predictor.py\n```\n\n## ⏰ Scheduled Prediction (Optional)\n\nTo enable scheduled daily automatic forecast and data updates (This is set to update at 00:00):\n```bash\npython scripts/scheduler.py\n```\n\nOr run in the background:\n```bash\nnohup python scripts/scheduler.py \u0026\n```\n\n---\n\n## 💡 Credits\n\n- Exchange rate data from Yahoo Finance (`yfinance`)\n- Macroeconomic data from FRED (Federal Reserve API)\n- Model: XGBoost classifier with SMOTE + ENN for class imbalance\n- Feature explanations via SHAP\n- Dashboard styled with Tailwind CSS and Chart.js\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyouhuipang%2Ffx-risk-forecasting-system","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyouhuipang%2Ffx-risk-forecasting-system","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyouhuipang%2Ffx-risk-forecasting-system/lists"}