Skip to content

README.md

Latest commit

 

History

History
368 lines (275 loc) · 11.1 KB

README.md

File metadata and controls

368 lines (275 loc) · 11.1 KB

FinLearner Logo
State-of-the-art Financial Analysis & Deep Learning Library

Tests PyPI version Downloads License Python 3.8+ GitHub stars

Installation | Quick Start | 📖 Theory | Documentation | Contributing

🔥 What is FinLearner?

FinLearner is a comprehensive Python library designed for quantitative researchers, algorithmic traders, and data scientists. It provides production-ready tools for:

  • 📈 Deep Learning Forecasting — LSTM, GRU, Transformer, CNN-LSTM, Ensemble models
  • 💼 Portfolio Optimization — Markowitz, Black-Litterman, Risk Parity
  • 📊 Technical Analysis — 20+ indicators including RSI, MACD, Bollinger Bands, Ichimoku Cloud
  • 🎯 Options Pricing — Black-Scholes-Merton model with Greeks calculation
  • 🧠 Physics-Informed Neural Networks — PINN for solving Black-Scholes PDE
  • 📉 Risk Metrics — VaR (Historical, Parametric, Monte Carlo), CVaR, Max Drawdown
  • 🔍 Anomaly Detection — VAE for price pattern anomalies
  • 🤖 Gradient Boosting — XGBoost/LightGBM with auto feature engineering
  • 📊 Interactive Visualization — Beautiful Plotly-powered financial charts

Philosophy: One library. All the tools you need. From data fetching to model deployment.

📰 News

Date News
2026-02 02/2026
02/2026 v0.1.0 Major Release
2025-12 📊 Added Ichimoku Cloud and advanced technical indicators
2025-12 🚀 FinLearner is now available on PyPI!

📦 Installation

Install with pip (recommended)

pip install finlearner

Install from source

git clone https://github.com/ankitdutta428/finlearner.git
cd finlearner
pip install -e .

Requirements

  • Python 3.8+
  • TensorFlow 2.10+
  • NumPy, Pandas, SciPy, Scikit-learn
  • Plotly, Matplotlib, Seaborn
  • yfinance

⚡ Quick Start

🔮 Stock Price Prediction with LSTM

Train a deep learning model to predict stock prices with just a few lines of code:

from finlearner import DataLoader, TimeSeriesPredictor, Plotter

# 1. Fetch and preprocess data
df = DataLoader.download_data('AAPL', start='2020-01-01', end='2024-01-01')

# 2. Initialize and train the LSTM predictor
predictor = TimeSeriesPredictor(lookback_days=60)
predictor.fit(df, epochs=25, batch_size=32)

# 3. Generate predictions
predictions = predictor.predict(df)

# 4. Visualize results
Plotter.plot_prediction(df, predictions, title="Apple Stock Prediction")

💼 Portfolio Optimization (Markowitz)

Find the optimal asset allocation using Modern Portfolio Theory:

from finlearner import PortfolioOptimizer

# Define your portfolio
tickers = ['AAPL', 'GOOG', 'MSFT', 'AMZN', 'TSLA']

# Run optimization with Monte Carlo simulation
optimizer = PortfolioOptimizer(tickers=tickers, start='2023-01-01', end='2024-01-01')
results, optimal_allocation, metrics = optimizer.optimize(num_portfolios=10000)

print("📊 Optimal Allocation (Max Sharpe Ratio):")
print(optimal_allocation)
print(f"\n📈 Expected Return: {metrics[1]:.2%}")
print(f"📉 Volatility: {metrics[0]:.2%}")

📊 Technical Analysis

Apply comprehensive technical indicators to your data:

from finlearner import DataLoader, TechnicalIndicators, Plotter

# Load data
df = DataLoader.download_data('NVDA', start='2023-01-01', end='2024-01-01')

# Add all technical indicators at once
ti = TechnicalIndicators(df)
df_enriched = ti.add_all()  # Adds RSI, MACD, Bollinger Bands, ATR, Ichimoku, etc.

# Or add specific indicators
df = ti.rsi(window=14)
df = ti.macd(fast=12, slow=26, signal=9)
df = ti.bollinger_bands(window=20, num_std=2)

# Interactive candlestick chart
Plotter.candlestick(df_enriched, title="NVIDIA Technical Analysis")

🎯 Options Pricing (Black-Scholes-Merton)

Price European options and calculate Greeks:

from finlearner.options import BlackScholesMerton

# Create option pricer
option = BlackScholesMerton(
    S=100,      # Spot price
    K=100,      # Strike price
    T=1,        # Time to maturity (years)
    r=0.05,     # Risk-free rate
    sigma=0.2,  # Volatility
    q=0.02      # Dividend yield
)

# Calculate prices
call_price = option.price('call')
put_price = option.price('put')

# Calculate Greeks
greeks = option.greeks('call')
print(f"Call Price: ${call_price:.2f}")
print(f"Delta: {greeks['delta']:.4f}")
print(f"Gamma: {greeks['gamma']:.4f}")
print(f"Vega: {greeks['vega']:.4f}")

🏗️ Architecture

graph TB
    subgraph Data Layer
        A[DataLoader] --> |yfinance| B[Raw OHLCV Data]
    end
    
    subgraph Analysis Layer
        B --> C[TechnicalIndicators]
        B --> D[PortfolioOptimizer]
        B --> E[TimeSeriesPredictor]
    end
    
    subgraph Pricing Layer
        F[BlackScholesMerton] --> G[Option Prices + Greeks]
        H[BlackScholesPINN] --> I[PDE Solutions]
    end
    
    subgraph Visualization Layer
        C --> J[Plotter]
        D --> J
        E --> J
        J --> K[Interactive Charts]
    end
    
    style A fill:#4CAF50,color:#fff
    style E fill:#2196F3,color:#fff
    style F fill:#FF9800,color:#fff
    style J fill:#9C27B0,color:#fff
Loading

📚 Module Reference

Module Class Description
finlearner.data DataLoader Unified data fetching wrapper for Yahoo Finance
finlearner.models TimeSeriesPredictor LSTM-based time series forecasting
finlearner.models GRUPredictor GRU-based predictor (faster than LSTM)
finlearner.models CNNLSTMPredictor CNN-LSTM hybrid for pattern extraction
finlearner.models TransformerPredictor Transformer with self-attention
finlearner.models EnsemblePredictor LSTM + GRU + Attention ensemble
finlearner.ml_models GradientBoostPredictor XGBoost/LightGBM for tabular data
finlearner.anomaly VAEAnomalyDetector VAE for price anomaly detection
finlearner.risk RiskMetrics VaR, CVaR, Max Drawdown calculations
finlearner.portfolio PortfolioOptimizer Markowitz Mean-Variance optimization
finlearner.portfolio BlackLittermanOptimizer Black-Litterman with investor views
finlearner.portfolio RiskParityOptimizer Equal risk contribution portfolio
finlearner.technical TechnicalIndicators 20+ technical analysis indicators
finlearner.options BlackScholesMerton European option pricing with Greeks
finlearner.pinn BlackScholesPINN Physics-Informed Neural Network for Black-Scholes
finlearner.plotting Plotter Interactive visualization with Plotly
finlearner.utils check_val Model validation utilities

📊 Technical Indicators Available

Category Indicators
Trend SMA, EMA, MACD, Ichimoku Cloud
Momentum RSI, Stochastic Oscillator, CCI
Volatility Bollinger Bands, ATR
Volume OBV (On-Balance Volume)

🧪 Testing

Run the test suite:

# Run all tests
pytest tests/ -v

# Run with coverage report
pytest tests/ --cov=finlearner --cov-report=term-missing

# Run specific test module
pytest tests/test_options.py -v

🤝 Contributing

We welcome contributions from the community! Here's how to get started:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/AmazingFeature)
  3. Write tests for your changes
  4. Commit your changes (git commit -m 'Add AmazingFeature')
  5. Push to the branch (git push origin feature/AmazingFeature)
  6. Open a Pull Request

Development Setup

# Clone your fork
git clone https://github.com/YOUR_USERNAME/finlearner.git
cd finlearner

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

📖 Documentation

🗺️ Roadmap

  • Risk metrics — VaR (Historical, Parametric, Monte Carlo), CVaR, Maximum Drawdown ✅
  • Transformer-based forecasting — TransformerPredictor with self-attention ✅
  • Advanced ML models — GRU, CNN-LSTM, Ensemble, XGBoost/LightGBM ✅
  • Anomaly detection — VAE for price pattern anomalies ✅
  • Advanced portfolio optimization — Black-Litterman, Risk Parity ✅
  • Backtesting engine for strategy testing
  • Sentiment analysis integration
  • Additional data sources (Alpha Vantage, Polygon.io)
  • CLI interface for quick analysis

📝 Citation

If you use FinLearner in your research, please cite:

@software{finlearner2024,
  author = {Dutta, Ankit},
  title = {FinLearner: A Comprehensive Financial Analysis and Deep Learning Library},
  year = {2025},
  publisher = {GitHub},
  url = {https://github.com/ankitdutta428/finlearner}
}

📄 License

Distributed under the Apache 2.0 License. See LICENSE for more information.

🙏 Acknowledgments

  • yfinance for financial data
  • TensorFlow for deep learning infrastructure
  • Plotly for interactive visualizations
  • The open-source quantitative finance community

Built with ❤️ by Ankit Dutta

Star on GitHub