109 lines
3.5 KiB
Markdown
109 lines
3.5 KiB
Markdown
# Compatibility: ferro-ta vs pandas-ta
|
||
|
||
ferro-ta provides indicators that match [pandas-ta](https://github.com/twopirllc/pandas-ta)
|
||
results to within numerical tolerance. This guide explains how to migrate from
|
||
pandas-ta and how to run the cross-library validation tests.
|
||
|
||
## Installation
|
||
|
||
```bash
|
||
pip install ferro-ta
|
||
# Optional: install pandas-ta to run comparison tests
|
||
pip install pandas-ta
|
||
```
|
||
|
||
## API Comparison
|
||
|
||
### pandas-ta style (accessor)
|
||
|
||
```python
|
||
import pandas as pd
|
||
import pandas_ta as ta
|
||
|
||
close = pd.Series([...])
|
||
sma = close.ta.sma(length=20)
|
||
ema = close.ta.ema(length=14)
|
||
rsi = close.ta.rsi(length=14)
|
||
```
|
||
|
||
### ferro-ta equivalent
|
||
|
||
```python
|
||
import numpy as np
|
||
import ferro_ta as ft
|
||
|
||
close = np.array([...])
|
||
sma = ft.SMA(close, timeperiod=20)
|
||
ema = ft.EMA(close, timeperiod=14)
|
||
rsi = ft.RSI(close, timeperiod=14)
|
||
```
|
||
|
||
> **Note**: ferro-ta operates on NumPy arrays. If you have a `pd.Series`, pass
|
||
> it directly — ferro-ta will convert it automatically.
|
||
|
||
## Indicator Mapping
|
||
|
||
| pandas-ta | ferro-ta | Notes |
|
||
|---|---|---|
|
||
| `ta.sma(length=N)` | `ft.SMA(close, timeperiod=N)` | Exact match |
|
||
| `ta.ema(length=N)` | `ft.EMA(close, timeperiod=N)` | Tail convergence within 1e-6 |
|
||
| `ta.wma(length=N)` | `ft.WMA(close, timeperiod=N)` | Exact match |
|
||
| `ta.rsi(length=N)` | `ft.RSI(close, timeperiod=N)` | Tail convergence |
|
||
| `ta.macd(fast, slow, signal)` | `ft.MACD(close, fastperiod, slowperiod, signalperiod)` | Tail convergence |
|
||
| `ta.bbands(length=N, std=2)` | `ft.BBANDS(close, timeperiod=N, nbdevup=2, nbdevdn=2)` | Exact match |
|
||
| `ta.stoch(high, low, close)` | `ft.STOCH(high, low, close, ...)` | Tail convergence |
|
||
| `ta.cci(high, low, close, length=N)` | `ft.CCI(high, low, close, timeperiod=N)` | Exact match |
|
||
| `ta.mom(length=N)` | `ft.MOM(close, timeperiod=N)` | Exact match |
|
||
| `ta.roc(length=N)` | `ft.ROC(close, timeperiod=N)` | Exact match |
|
||
| `ta.trima(length=N)` | `ft.TRIMA(close, timeperiod=N)` | Exact match |
|
||
| `ta.hma(length=N)` | `ft.HT_MA(close, timeperiod=N)` | Hull MA variant |
|
||
| `ta.ichimoku(...)` | `ft.ICHIMOKU(high, low, close)` | Tenkan/Kijun match |
|
||
| `ta.kc(high, low, close, ...)` | `ft.KELTNER(high, low, close, ...)` | Tail convergence |
|
||
|
||
## Batch Execution
|
||
|
||
ferro-ta supports running many indicators at once via the batch API:
|
||
|
||
```python
|
||
import numpy as np
|
||
import ferro_ta as ft
|
||
|
||
data = np.random.randn(1000, 50) # 50 instruments × 1000 bars
|
||
|
||
# Run SMA(20) across all 50 instruments in one call
|
||
results = ft.batch_compute(data, "SMA", timeperiod=20)
|
||
```
|
||
|
||
## Running the Cross-Library Tests
|
||
|
||
Cross-library comparison tests live in `tests/integration/test_vs_pandas_ta.py`.
|
||
They are automatically **skipped** when pandas-ta is not installed.
|
||
|
||
```bash
|
||
# Install pandas-ta first
|
||
pip install pandas-ta
|
||
|
||
# Run comparison tests
|
||
pytest tests/integration/test_vs_pandas_ta.py -v
|
||
```
|
||
|
||
## Known Differences
|
||
|
||
- **Seeding period**: EMA results during the first `timeperiod` bars may differ
|
||
due to different initialization strategies (SMA seed vs EMA seed). Results
|
||
converge after the seeding window.
|
||
- **MACD signal line**: The signal EMA is seeded from the first valid MACD value.
|
||
Exact match begins after 2× `slowperiod` bars.
|
||
- **STOCH smoothing**: ferro-ta defaults match TA-Lib (SMA slowk, SMA slowd).
|
||
pandas-ta uses different defaults; pass matching parameters explicitly.
|
||
|
||
## Performance Comparison
|
||
|
||
ferro-ta is 10–100× faster than pandas-ta for large arrays because the core
|
||
computation is written in Rust:
|
||
|
||
```bash
|
||
# Run the benchmark
|
||
pytest benchmarks/test_speed.py --benchmark-only --benchmark-json=benchmarks/results.json
|
||
```
|