Metadata-Version: 2.4
Name: greeks-package
Version: 1.2.1
Summary: Black-Scholes option Greeks made easy - comprehensive Greek calculations for European options
Author-email: JR Concepcion <jr1concepcion@gmail.com>
Maintainer-email: JR Concepcion <jr1concepcion@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/JRCon1/greeks-package
Project-URL: Documentation, https://github.com/JRCon1/greeks-package/blob/main/README.md
Project-URL: Repository, https://github.com/JRCon1/greeks-package
Project-URL: Tutorial (v0.1.0), https://youtu.be/geyCTGodXQk?si=zT3s4Gf2bMmGQk4I
Keywords: options,greeks,black-scholes,finance,derivatives,quantitative,trading,risk-management,delta,gamma,vega,theta,volatility,options-pricing
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23
Requires-Dist: pandas>=1.5
Requires-Dist: scipy>=1.10
Requires-Dist: yfinance>=0.2
Requires-Dist: plotly>=5.19
Requires-Dist: matplotlib>=3.5
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=22.0; extra == "dev"
Requires-Dist: flake8>=5.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: jupyter>=1.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=5.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0; extra == "docs"
Requires-Dist: sphinx-autoapi>=2.0; extra == "docs"
Dynamic: license-file

# greeks-package

**Black-Scholes option Greeks made easy**

[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

```python
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

```bash
# 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
```python
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
```python
# 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
```python
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
```python
# 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
```python
# 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)
```python
# 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
```python
# 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

| Function | Description | Returns |
|----------|-------------|---------|
| `download_options()` | Fetch & filter option chain from Yahoo Finance | DataFrame |
| `multi_download()` | Download options for multiple tickers | DataFrame |
| `greeks()` | Calculate all 13 Greeks at once | Series |
| `first_order()` | Calculate Δ, Vega, Θ, Rho | Series |
| `second_order()` | Calculate Γ, Vanna, Volga, Veta, Charm | Series |
| `third_order()` | Calculate Color, Speed, Ultima, Zomma | Series |

### American Option Pricing (FDM)

| Function | Description | Returns |
|----------|-------------|---------|
| `FDM()` | Scalar American/European option solver (Crank–Nicolson + PSOR) | Result object |
| `fdm_row()` | Row-level FDM wrapper for use with `DataFrame.apply(axis=1)` | Series |

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

### Delta-Hedge Backtesting

| Function | Description | Returns |
|----------|-------------|---------|
| `simulate_gbm()` | Generate a single GBM stock-price path | ndarray |
| `run_backtest()` | Delta-hedge backtest with FDM repricing and P&L decomposition | dict |
| `plot_backtest()` | Plot stock price path and repriced option value | Figure |
| `plot_greeks()` | Plot delta, gamma, theta, and hedge shares over time | Figure |

### Individual Greeks

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

### Submodules

| Submodule | Description |
|-----------|-------------|
| `gp.pricing` | Black–Scholes and Monte Carlo pricing (`bsm_price`, `monte_carlo_price`) |
| `gp.plotting` | All visualization helpers (`surf_scatter`, `surface_plot`, `greek_plot`, `iv_plot`, etc.) |
| `gp.fdm` | American/European FDM pricing – `gp.FDM` (scalar) and `gp.fdm_row` (row-level) |
| `gp.backtest` | Delta-hedge backtesting – `run_backtest`, `plot_backtest`, `plot_greeks` |

### Utilities & Visualization

| Function | Description |
|----------|-------------|
| `comb()` | Combine multiple DataFrames with automatic column handling |
| `surf_scatter()` | Interactive 3D scatter plots |
| `surface_plot()` | Smooth 3D surface plots |
| `greek_plot()` | Greek values vs time with strike selection |
| `iv_plot()` | Implied volatility term structure |
| `oi_plot()` | Open interest distribution analysis |
| `vol_curve()` | Volatility smile/skew curves |
| `bsm_price()` | Black-Scholes theoretical pricing |
| `monte_carlo_price()` | Monte Carlo option pricing |
| `strategy_builder()` | Multi-leg options strategy analysis |

### Function Signatures

All Greek functions follow the same pattern:
```python
function_name(row: pd.Series, ticker: str, option_type: str = 'c', 
              r: float = 0.05, eps: float = 1e-9) -> float
```

**Multi-download signature:**
```python
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:**
```python
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:**
```python
fdm_row(row: pd.Series, ticker: str, option_type: str = 'call',
        r: float = 0.05, NAS: int = 200, NTS: int = 2000,
        cn: bool = True, psor: bool = True) -> pd.Series
# Returns: FDM_Price, FDM_Delta, FDM_Gamma, FDM_Theta
```

**run_backtest signature:**
```python
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`](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:
```bash
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](USAGE.md)**: Detailed function reference and advanced usage patterns
- **[examples.py](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](LICENSE) file for details.

## Author

**JR Concepcion**

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

---

### Quick Reference

```python
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)
``` 
