greeks-package

Black-Scholes option Greeks made easy

A comprehensive Python package for calculating first-, second-, and third-order Greeks for European options using pure NumPy/SciPy implementations. No external Greeks library required – just clean, fast calculations with integrated option chain downloading from Yahoo Finance.

Features

• Complete Greeks Suite: Delta, Gamma, Vega, Theta, Rho, Vanna, Volga, Charm, Veta, Color, Speed, Ultima, Zomma
• Multi-Ticker Download: Download options for multiple stocks simultaneously with multi_download()
• Enhanced Data Integration: Download calls, puts, or both together from Yahoo Finance
• Flexible Usage: Calculate individual Greeks or all at once with convenient wrapper functions
• Interactive Visualization: 3D plotting of Greeks surfaces using Plotly
• Strategy Analysis: Multi-leg options strategy builder and analyzer
• American Option Pricing (FDM): Crank–Nicolson + PSOR finite difference pricing for American calls and puts — scalar (gp.FDM) and vectorized row-level (gp.fdm_row) interfaces. Supports explicit FDM and European mode via cn / psor flags
• Delta-Hedge Backtesting: Simulate delta hedging on a GBM path with full P&L decomposition, transaction costs, and built-in visualizations (gp.run_backtest, gp.plot_backtest, gp.plot_greeks)
• Production Ready: Comprehensive error handling, type hints, and full documentation

Quick Start

import greeks_package as gp

# Download Apple call options within 30 days, ±5% moneyness
opts = gp.download_options("AAPL", opt_type="c", max_days=30)

# Calculate all Greeks in one line
all_greeks = opts.apply(gp.greeks, axis=1, ticker="AAPL")

# Combine with original data
full_data = opts.join(all_greeks)
print(full_data[['strike', 'lastPrice', 'Delta', 'Gamma', 'Vega', 'Theta']].head())

Installation

# From PyPI (when published)
pip install greeks-package

# From source (development)
git clone https://github.com/JRCon1/greeks-package.git
cd greeks-package
pip install -e .

Requirements: Python ≥ 3.9, NumPy, Pandas, SciPy, yfinance, Plotly, Matplotlib

Usage Examples

Multi-Ticker Download

import greeks_package as gp

# Download options for multiple tickers at once
tickers = ['AAPL', 'MSFT', 'GOOGL', 'TSLA']
multi_opts = gp.multi_download(
    ticker_symbols=tickers,
    opt_type="c",
    max_days=30,
    price=True  # Include stock prices
)

print(f"Downloaded {len(multi_opts)} options across {len(tickers)} tickers")

Calls and Puts Together

# Download both calls and puts simultaneously
opts = gp.download_options("TSLA", opt_type="all", max_days=60)

# Separate calls and puts using the option_type column (always present in v1.2.1+)
calls = opts[opts['option_type'] == 'call']
puts  = opts[opts['option_type'] == 'put']

print(f"Downloaded {len(calls)} calls and {len(puts)} puts")

Individual Greeks Calculation

opts = gp.download_options("MSFT", max_days=45)

# Calculate specific Greeks
opts['Delta'] = opts.apply(gp.delta, axis=1, ticker="MSFT")
opts['Gamma'] = opts.apply(gp.gamma, axis=1, ticker="MSFT")
opts['Vanna'] = opts.apply(gp.vanna, axis=1, ticker="MSFT")

Interactive Visualization

# 3D plots
gp.surf_scatter(opts, "AAPL", z="delta")      # Delta scatter plot
gp.surface_plot(opts, "AAPL", z="gamma")      # Gamma surface plot

gp.greek_plot(opts, greek_col="Delta")        # Greek vs time with strike selection
gp.iv_plot(opts, "AAPL")                      # Implied volatility term structure
gp.oi_plot(opts, "AAPL")                      # Open interest analysis
gp.vol_curve(opts, "AAPL")                    # Volatility smile/skew curves

Greek Orders Analysis

# Calculate Greeks by order
first_order = opts.apply(gp.first_order, axis=1, ticker="NVDA")    # Δ, Vega, Θ, Rho
second_order = opts.apply(gp.second_order, axis=1, ticker="NVDA")  # Γ, Vanna, Volga, Veta, Charm
third_order = opts.apply(gp.third_order, axis=1, ticker="NVDA")    # Color, Speed, Ultima, Zomma

# Combine all data
full_analysis = gp.comb(opts, first_order, second_order, third_order)

American Option Pricing (FDM)

# Scalar solver — one option per call, full result object
res = gp.FDM(685.74, 685.0, 0.1743, 0.0402, 321/365)                    # call (default)
res = gp.FDM(685.74, 685.0, 0.1743, 0.0402, 321/365, option_type="put")  # put
print(res.price, res.delta, res.gamma, res.theta_day)

# With Black–Scholes benchmark
res = gp.FDM(685.74, 685.0, 0.1743, 0.0402, 321/365, bs=True)

# Solver modes via cn / psor flags (default: cn=True, psor=True)
res = gp.FDM(..., cn=True,  psor=True)   # Crank–Nicolson + PSOR  (American, default)
res = gp.FDM(..., cn=True,  psor=False)  # Crank–Nicolson + Thomas (European FDM)
res = gp.FDM(..., cn=False, psor=True)   # Explicit + projection   (American explicit)
res = gp.FDM(..., cn=False, psor=False)  # Pure explicit            (European explicit)

# Row-level wrapper — price a DataFrame of options with FDM
fdm_cols = opts.apply(gp.fdm_row, axis=1, ticker="AAPL")
# Returns columns: FDM_Price, FDM_Delta, FDM_Gamma, FDM_Theta
full_data = gp.comb(opts, fdm_cols)

Delta-Hedge Backtesting

# Simulate a delta-hedge strategy on a GBM path
res = gp.run_backtest(
    S0=685.74,      # initial stock price
    K=685.0,        # strike
    sigma=0.1743,   # implied vol (used for FDM repricing)
    r=0.0402,       # risk-free rate
    T=321/365,      # time to expiry (years)
    sigma_real=0.20,  # realized vol for GBM path (optional; tests vol mismatch)
    dt=1/365,         # time step (daily)
    rebal_freq=1,     # rebalance every N steps
    seed=42,
)

print(f"Final P&L: ${res['final_pnl']:.2f}")
print(f"Total transaction costs: ${res['total_costs']:.2f}")

# Visualize results
gp.plot_backtest(res)   # stock price path + repriced option value
gp.plot_greeks(res)     # delta, gamma, theta, hedge shares over time

API Reference

Core Functions

American Option Pricing (FDM)

FDM result attributes: price, delta, gamma, theta_day, S / S_grid, V / V_grid

Delta-Hedge Backtesting

Individual Greeks

First Order: delta, vega, theta, rho
Second Order: gamma, vanna, volga, veta, charm
Third Order: color, speed, ultima, zomma

Submodules

Utilities & Visualization

Function Signatures

All Greek functions follow the same pattern:

function_name(row: pd.Series, ticker: str, option_type: str = 'c', 
              r: float = 0.05, eps: float = 1e-9) -> float

Multi-download signature:

multi_download(ticker_symbols: List[str], opt_type: str = 'c', 
               max_days: int = 60, lower_moneyness: float = 0.95,
               upper_moneyness: float = 1.05, price: bool = False) -> pd.DataFrame

FDM scalar solver signature:

FDM(S0, K, sigma, r, T,
    NAS=200, NTS=2000, S_max_mult=4.0, rannacher=4,
    omega=1.2, tol=1e-8, max_iter=5000,
    bs=False, option_type="call", silent=False,
    cn=True, psor=True)

fdm_row (DataFrame row-level) signature:

fdm_row(row: pd.Series, ticker: str, option_type: str = 'call',
        r: float = 0.05, NAS: int = 200, NTS: int = 500,
        cn: bool = True, psor: bool = True) -> pd.Series
# Returns: FDM_Price, FDM_Delta, FDM_Gamma, FDM_Theta

run_backtest signature:

run_backtest(S0, K, sigma, r, T,
             sigma_real=None, dt=1/365, rebal_freq=1,
             cost_per_share=0.00003, seed=42,
             cn=True, psor=True,
             fdm_nas=200, fdm_nts=1000,
             verbose=True) -> dict

Comprehensive Examples

See examples.py for complete usage demonstrations including:

1. Basic Options Greeks Calculation
2. Calls and Puts Together - Using opt_type="all"
3. Multi-Ticker Download - Using multi_download()
4. Multi-Download with Calls & Puts
5. Individual Greeks Selection
6. 3D Visualization
7. Strategy Analysis

Run examples:

python examples.py           # Run all examples
python examples.py 3         # Run multi-download example
python examples.py 2         # Run calls/puts example

Documentation

• USAGE.md: Detailed function reference and advanced usage patterns
• examples.py: Complete working examples for all major features
• Interactive Help: Use gp.help() for in-package documentation

Greek Formulas

This package implements standard Black-Scholes Greeks:

• Delta (Δ): ∂V/∂S - Price sensitivity to underlying
• Gamma (Γ): ∂²V/∂S² - Delta sensitivity to underlying
• Vega (ν): ∂V/∂σ - Price sensitivity to volatility
• Theta (Θ): ∂V/∂t - Time decay
• Rho (ρ): ∂V/∂r - Interest rate sensitivity

Plus advanced second and third-order Greeks for sophisticated risk management.

Performance

• Vectorized Operations: Efficient NumPy/SciPy implementations
• Minimal Dependencies: No external Greeks libraries required
• Memory Efficient: Designed for large option chains
• Fast Execution: Optimized for production use

Contributing

Contributions welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

JR Concepcion

Built using NumPy, Pandas, SciPy, yfinance, Plotly, and Matplotlib.

Quick Reference

import greeks_package as gp

# Basic workflow
opts = gp.download_options("AAPL", opt_type="c", max_days=30)
greeks_data = opts.apply(gp.greeks, axis=1, ticker="AAPL")
full_data = opts.join(greeks_data)

# Individual Greeks
opts['Delta'] = opts.apply(gp.delta, axis=1, ticker="AAPL")
opts['Vanna'] = opts.apply(gp.vanna, axis=1, ticker="AAPL")

# Visualization
gp.surf_scatter(opts, "AAPL", z="delta")
gp.surface_plot(opts, "AAPL", z="impliedVolatility")

# American option pricing (FDM – scalar)
res = gp.FDM(685.74, 685.0, 0.1743, 0.0402, 321/365)
print(res.price, res.delta, res.gamma, res.theta_day)

# FDM on a DataFrame (row-level)
fdm_cols = opts.apply(gp.fdm_row, axis=1, ticker="AAPL")
full_data = gp.comb(opts, fdm_cols)

# Delta-hedge backtest
res = gp.run_backtest(685.74, 685.0, 0.1743, 0.0402, 321/365)
gp.plot_backtest(res)
gp.plot_greeks(res)