Skip to content

models

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

models

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
standard
standard
 
 
README.md
README.md
 
 

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! 🚀