NexQuant/models/README.md

NexQuant Models

This directory contains all ML model definitions for NexQuant trading factors.

---

📁 Directory Structure

models/
├── standard/               # Default models (committed to Git)
│   ├── xgboost_factor.py   # XGBoost for tabular data
│   ├── lightgbm_factor.py  # LightGBM (faster than XGBoost)
│   └── randomforest_factor.py  # Baseline model
│
├── local/                  # YOUR IMPROVED MODELS (not in Git!)
│   ├── transformer_factor.py   # Your Transformer
│   ├── tcn_factor.py           # Your TCN
│   ├── patchtst_factor.py      # Your PatchTST
│   ├── cnn_lstm_hybrid.py      # Your Hybrid model
│   └── optimized_xgboost.py    # Your optimized XGBoost
│
└── README.md               # This file

---

🎯 How It Works

Model Loading Priority:

1. models/local/*.py ← Your improved models (loaded first!)
2. models/standard/*.py ← Default models (fallback)

Example:

from rdagent.components.model_loader import load_model

# Load XGBoost model
# If models/local/xgboost_factor*.py exists → loads that
# Otherwise → loads from models/standard/
model_factory = load_model("xgboost_factor")

# Create model instance
model = model_factory(max_depth=8, learning_rate=0.1)

# Train
model.fit(X_train, y_train)

# Predict
predictions = model.predict(X_test)

---

📝 Available Standard Models

Model	File	Use Case
XGBoost	xgboost_factor.py	Tabular factors, fast training
LightGBM	lightgbm_factor.py	Large datasets, faster than XGBoost
RandomForest	randomforest_factor.py	Baseline, robust

---

🚀 Creating Your Improved Models

Step 1: Create Local Model File

# Create local directory (if not exists)
mkdir -p models/local

# Copy standard model as template
cp models/standard/xgboost_factor.py models/local/optimized_xgboost.py

Step 2: Improve Your Model

# models/local/optimized_xgboost.py

class XGBoostFactorModel:
    """Your optimized version with better hyperparameters."""
    
    def __init__(self, **params):
        self.params = {
            'objective': 'reg:squarederror',
            'max_depth': 8,  # Deeper trees
            'learning_rate': 0.03,  # Slower learning
            'n_estimators': 1000,  # More estimators
            'subsample': 0.9,  # Less dropout
            'colsample_bytree': 0.9,
            'random_state': 42,
            # Your custom params
            'gamma': 0.1,  # Regularization
            'min_child_weight': 3,
            **params
        }
        # ... rest of implementation

Step 3: Use in Trading

Your improved models are automatically used when running:

from rdagent.components.model_loader import load_model

# Auto-loads your optimized version!
model_factory = load_model("xgboost_factor")

---

🔐 Security

What to keep in models/local/:

✅ Your proprietary model architectures ✅ Optimized hyperparameters ✅ Custom feature engineering ✅ Ensemble methods ✅ Trade secrets & alpha-generating logic

What NOT to commit to Git:

❌ Anything in models/local/ (already in .gitignore) ❌ Files with .local.py suffix ❌ Files with _private.py suffix

---

📊 Best Practices

1. Version Your Models

# Good naming:
models/local/
├── xgboost_v2.py          # Version 2
├── xgboost_v3_optimized.py  # Version 3 optimized
└── lightgbm_lstm_hybrid_v1.py  # Hybrid v1

2. Document Changes

# models/local/optimized_xgboost_v2.py
"""
XGBoost Factor Model v2.0

Changes from v1:
- Increased max_depth from 6 to 8
- Added gamma regularization
- Increased n_estimators from 500 to 1000
- Target: +2% ARR, +0.2 Sharpe

Author: Your Name
Date: 2026-04-02
"""

3. Test Performance

# Compare model versions
from rdagent.components.model_loader import load_model

# Load standard
std_model = load_model("xgboost_factor", local_only=False)

# Load local (if exists)
local_model = load_model("xgboost_factor", local_only=True)

# Backtest both and compare
# ...

---

🔧 Advanced Usage

Load All Models

from rdagent.components.model_loader import list_available_models

all_models = list_available_models()
print(f"Standard: {all_models['standard']}")
print(f"Local: {all_models['local']}")

Force Local Model

# Raise error if local model not found
model = load_model("transformer_factor", local_only=True)

Custom Model Path

from rdagent.components.model_loader import load_module_from_path
from pathlib import Path

# Load from custom location
module = load_module_from_path(
    Path("/path/to/my/custom_model.py"),
    "custom_model"
)

---

📈 Model Selection Guide

Scenario	Recommended Model	Why
Tabular Factors	XGBoost / LightGBM	Fast, interpretable
Large Dataset	LightGBM	Lower memory, faster
Baseline	RandomForest	Robust, no tuning needed
Time-Series Patterns	LSTM / GRU (local)	Sequential dependencies
Multi-Scale	TCN (local)	Different time horizons
Long-Range	Transformer (local)	Attention mechanism
Best Performance	Ensemble (local)	Combine multiple models

---

🎯 Next Steps

1. Review standard models: cat models/standard/*.py
2. Create your improved version: mkdir -p models/local
3. Test: python rdagent/components/model_loader.py
4. Run trading: rdagent fin_quant

---

Your improved models in models/local/ are your competitive edge! 🚀