105 lines
3.6 KiB
Markdown
105 lines
3.6 KiB
Markdown
|
# Compatibility: ferro-ta vs ta (Bukosabino)
|
|||
|
|
|
|||
|
|
ferro-ta provides indicators that match [ta](https://github.com/bukosabino/ta)
|
|||
|
|
(Bukosabino's library) results to within numerical tolerance. This guide
|
|||
|
|
explains how to migrate from `ta` and how to run the cross-library validation
|
|||
|
|
tests.
|
|||
|
|
|
|||
|
|
## Installation
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
pip install ferro-ta
|
|||
|
|
# Optional: install ta to run comparison tests
|
|||
|
|
pip install ta
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## API Comparison
|
|||
|
|
|
|||
|
|
### ta style
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
import pandas as pd
|
|||
|
|
from ta.momentum import RSIIndicator, StochasticOscillator
|
|||
|
|
from ta.volatility import AverageTrueRange, BollingerBands
|
|||
|
|
from ta.trend import SMAIndicator, EMAIndicator, MACD, CCIIndicator
|
|||
|
|
from ta.volume import OnBalanceVolumeIndicator
|
|||
|
|
from ta.others import DailyReturnIndicator
|
|||
|
|
|
|||
|
|
close = pd.Series([...])
|
|||
|
|
high = pd.Series([...])
|
|||
|
|
low = pd.Series([...])
|
|||
|
|
volume = pd.Series([...])
|
|||
|
|
|
|||
|
|
rsi = RSIIndicator(close, window=14).rsi()
|
|||
|
|
sma = SMAIndicator(close, window=20).sma_indicator()
|
|||
|
|
ema = EMAIndicator(close, window=14).ema_indicator()
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### ferro-ta equivalent
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
import numpy as np
|
|||
|
|
import ferro_ta as ft
|
|||
|
|
|
|||
|
|
close = np.array([...])
|
|||
|
|
high = np.array([...])
|
|||
|
|
low = np.array([...])
|
|||
|
|
volume = np.array([...])
|
|||
|
|
|
|||
|
|
rsi = ft.RSI(close, timeperiod=14)
|
|||
|
|
sma = ft.SMA(close, timeperiod=20)
|
|||
|
|
ema = ft.EMA(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
|
|||
|
|
|
|||
|
|
| ta | ferro-ta | Notes |
|
|||
|
|
|---|---|---|
|
|||
|
|
| `SMAIndicator(close, window=N).sma_indicator()` | `ft.SMA(close, timeperiod=N)` | Exact match |
|
|||
|
|
| `EMAIndicator(close, window=N).ema_indicator()` | `ft.EMA(close, timeperiod=N)` | Tail convergence |
|
|||
|
|
| `BollingerBands(close, window=N, window_dev=2)` | `ft.BBANDS(close, timeperiod=N, nbdevup=2, nbdevdn=2)` | Exact match |
|
|||
|
|
| `RSIIndicator(close, window=N).rsi()` | `ft.RSI(close, timeperiod=N)` | Tail convergence |
|
|||
|
|
| `MACD(close, window_slow, window_fast, window_sign)` | `ft.MACD(close, fastperiod, slowperiod, signalperiod)` | Tail convergence |
|
|||
|
|
| `StochasticOscillator(high, low, close, window, smooth_window)` | `ft.STOCH(high, low, close, ...)` | Tail convergence |
|
|||
|
|
| `AverageTrueRange(high, low, close, window=N)` | `ft.ATR(high, low, close, timeperiod=N)` | Tail convergence |
|
|||
|
|
| `WilliamsRIndicator(high, low, close, lbp=N)` | `ft.WILLR(high, low, close, timeperiod=N)` | Exact match |
|
|||
|
|
| `OnBalanceVolumeIndicator(close, volume)` | `ft.OBV(close, volume)` | Exact match |
|
|||
|
|
| `CCIIndicator(high, low, close, window=N)` | `ft.CCI(high, low, close, timeperiod=N)` | Exact match |
|
|||
|
|
|
|||
|
|
## Running the Cross-Library Tests
|
|||
|
|
|
|||
|
|
Cross-library comparison tests live in `tests/integration/test_vs_ta.py`.
|
|||
|
|
They are automatically **skipped** when `ta` is not installed.
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# Install ta first
|
|||
|
|
pip install ta
|
|||
|
|
|
|||
|
|
# Run comparison tests
|
|||
|
|
pytest tests/integration/test_vs_ta.py -v
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## Known Differences
|
|||
|
|
|
|||
|
|
- **EMA seeding**: `ta` uses pandas `ewm` with `adjust=True` by default, which
|
|||
|
|
produces different warm-up values. Results converge after `2 × timeperiod` bars.
|
|||
|
|
- **ATR**: `ta` uses a simple rolling mean for ATR by default; ferro-ta uses
|
|||
|
|
Wilder's smoothing (same as TA-Lib). Values converge after the warm-up window.
|
|||
|
|
- **STOCH**: `ta` and ferro-ta use different default smoothing periods. Pass
|
|||
|
|
matching `window` / `smooth_window` values to get tail convergence.
|
|||
|
|
|
|||
|
|
## Performance Comparison
|
|||
|
|
|
|||
|
|
ferro-ta is significantly faster than `ta` for large arrays because the core
|
|||
|
|
computation is written in Rust:
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
pytest benchmarks/test_speed.py --benchmark-only --benchmark-json=benchmarks/results.json
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
`ta` is a pure-Python/pandas library; ferro-ta processes 100k-bar arrays
|
|||
|
|
in microseconds vs milliseconds for pandas-based implementations.
|