gavindiaz/ferro-ta
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: init the repo

Browse Source
This commit is contained in:
Pratik Bhadane
2026-03-23 23:34:28 +05:30
commit 7a5a220dfe
344 changed files with 75728 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/compatibility/finta.md
+145
View File
@@ -0,0 +1,145 @@
# ferro-ta ↔ finta Compatibility
[finta](https://github.com/peerchemist/finta) implements over 80 financial
technical indicators as class methods on a single `TA` class, operating
entirely on Pandas DataFrames.
---
## Key architectural differences
| Aspect | ferro-ta | finta |
|--------|---------|-------|
| **Backend** | Rust/C + SIMD | Pure Pandas |
| **Input type** | NumPy array or list | OHLCV Pandas DataFrame (required) |
| **DatetimeIndex** | Not required | **Required** |
| **Column names** | Separate arrays | `open/high/low/close/volume` |
| **Output type** | NumPy array | Pandas Series or DataFrame |
| **NaN handling** | Pads warmup with NaN | Pads warmup with NaN |
| **Streaming** | Yes (StreamingXxx classes) | No |
| **Speed** | ~700× faster on ATR | Baseline (pure Pandas) |
---
## Required DataFrame format
finta requires a **Pandas DataFrame with a DatetimeIndex** and lowercase
column names:
```python
import pandas as pd
import numpy as np
df = pd.DataFrame({
"open": open_prices,
"high": high_prices,
"low": low_prices,
"close": close_prices,
"volume": volume_data, # required for volume indicators
}, index=pd.date_range("2020-01-01", periods=len(close_prices), freq="D"))
```
ferro-ta accepts raw NumPy arrays or Python lists — no DataFrame needed.
---
## Function signature mapping
finta uses a class-method API: `TA.INDICATOR(ohlcv_df, period, ...)`.
| Indicator | ferro-ta | finta |
|-----------|---------|-------|
| SMA | `SMA(close, timeperiod=20)` | `TA.SMA(df, 20)` |
| EMA | `EMA(close, timeperiod=20)` | `TA.EMA(df, 20)` |
| WMA | `WMA(close, timeperiod=14)` | `TA.WMA(df, 14)` |
| DEMA | `DEMA(close, timeperiod=30)` | `TA.DEMA(df, 30)` |
| TEMA | `TEMA(close, timeperiod=30)` | `TA.TEMA(df, 30)` |
| HMA | Not supported | `TA.HMA(df, 16)` |
| RSI | `RSI(close, timeperiod=14)` | `TA.RSI(df, 14)` |
| MACD | `MACD(close, 12, 26, 9)` → (macd, signal, hist) | `TA.MACD(df, 12, 26, 9)` → DataFrame with `MACD`/`SIGNAL` columns |
| BBANDS | `BBANDS(close, 20, 2.0, 2.0)` → (upper, mid, lower) | `TA.BBANDS(df, 20)` → DataFrame with `BB_UPPER`/`BB_MIDDLE`/`BB_LOWER` |
| ATR | `ATR(high, low, close, timeperiod=14)` | `TA.ATR(df, 14)` |
| TRUE RANGE | `TRANGE(high, low, close)` | `TA.TR(df)` |
| OBV | `OBV(close, volume)` | `TA.OBV(df)` |
| MFI | `MFI(high, low, close, volume, timeperiod=14)` | `TA.MFI(df, 14)` |
| CCI | `CCI(high, low, close, timeperiod=14)` | `TA.CCI(df, 14)` |
| STOCH | `STOCH(high, low, close, 5, 3, 3)` | `TA.STOCH(df, 14)` |
| WILLR | `WILLR(high, low, close, timeperiod=14)` | `TA.WILLIAMS(df, 14)` |
| ADX | `ADX(high, low, close, timeperiod=14)` | `TA.ADX(df, 14)` |
| AROON | `AROON(high, low, timeperiod=14)` → (up, down) | `TA.AROON(df, 14)` → DataFrame |
---
## Numerical accuracy
finta uses sample standard deviation (ddof=1) for Bollinger Bands while
ferro-ta follows the TA-Lib convention (population std, ddof=0). For a
window of 20 bars this creates a ~0.5% difference in band width.
For EMA-based indicators, finta seeds with the first data point while ferro-ta
follows TA-Lib (SMA of first `timeperiod` bars). Values converge after
~3× the period.
Cross-library correlation between ferro-ta and finta is ≥ 0.95 for all
indicators after discarding the warm-up period.
---
## Speed comparison
On 10,000 bars (median µs, Apple M-series):
| Indicator | ferro-ta | finta | ferro-ta speedup |
|-----------|--------:|-------:|----------------:|
| SMA | 16.7 | 178.1 | **10.7×** |
| MACD | 70.4 | 383.9 | **5.5×** |
| ATR | 51.4 | 1,247 | **24×** |
On 100,000 bars:
| Indicator | ferro-ta | finta | ferro-ta speedup |
|-----------|--------:|--------:|----------------:|
| SMA | 126.2 | 699.7 | **5.6×** |
| MACD | 465.9 | 1,470.8 | **3.2×** |
| ATR | 478.5 | 6,782 | **14×** |
finta's ATR scales especially poorly because it relies on Pandas `.apply()`
with a lambda, which cannot be vectorised.
---
## Migration guide
```python
# FROM finta
import pandas as pd
from finta import TA
ohlcv = pd.DataFrame(...) # must have DatetimeIndex + open/high/low/close/volume
sma = TA.SMA(ohlcv, 20) # returns Pandas Series
macd_df = TA.MACD(ohlcv, 12, 26, 9) # returns DataFrame with MACD/SIGNAL cols
bb_df = TA.BBANDS(ohlcv, 20) # returns DataFrame with BB_UPPER/MIDDLE/LOWER
# TO ferro-ta (NumPy arrays — no DataFrame required)
import ferro_ta
import numpy as np
close = ohlcv["close"].values
sma = ferro_ta.SMA(close, timeperiod=20)
macd, signal, hist = ferro_ta.MACD(close, fastperiod=12, slowperiod=26, signalperiod=9)
upper, middle, lower = ferro_ta.BBANDS(close, timeperiod=20, nbdevup=2.0, nbdevdn=2.0)
```
---
## Known limitations
- finta cannot process raw NumPy arrays — a properly formatted DataFrame with
DatetimeIndex is always required.
- `TA.MACD` only returns `MACD` and `SIGNAL` columns; the histogram must be
computed manually as `MACD - SIGNAL`.
- Several finta indicators use non-standard formulas that may not match TA-Lib
conventions (e.g. STOCH uses a fixed 14-period window regardless of the
`fastk_period` argument).
docs/compatibility/pandas_ta.md
+108
View File
@@ -0,0 +1,108 @@
# 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
```
docs/compatibility/ta.md
+104
View File
@@ -0,0 +1,104 @@
# 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.
docs/compatibility/talib.md
+27
View File
@@ -0,0 +1,27 @@
# Compatibility: ferro-ta vs TA-Lib
See the full migration guide at [docs/migration_talib.rst](../migration_talib.rst).
ferro-ta is designed as a **drop-in replacement** for TA-Lib (`talib` Python package) for the most commonly used indicators.
## Quick Reference
```python
# TA-Lib
import talib
result = talib.SMA(close, timeperiod=14)
# ferro-ta (identical API)
import ferro_ta
result = ferro_ta.SMA(close, timeperiod=14)
```
Full migration guide including all indicator mappings, known differences, and step-by-step migration: [migration_talib.rst](../migration_talib.rst)
## Running Cross-Library Tests
```bash
# Requires TA-Lib C library + talib Python package
pip install TA-Lib
pytest tests/integration/test_vs_talib.py -v
```
docs/compatibility/tulipy.md
+140
View File
@@ -0,0 +1,140 @@
# ferro-ta ↔ Tulipy Compatibility
[Tulipy](https://github.com/cirla/tulipy) is the Python binding for
[Tulip Indicators](https://tulipindicators.org/) — 104 technical analysis
functions written in pure ANSI C99, designed for absolute speed with zero
external dependencies.
---
## Key architectural differences
| Aspect | ferro-ta | Tulipy |
|--------|---------|--------|
| **Backend** | Rust/C + SIMD | ANSI C99 |
| **Input type** | NumPy array or list | `np.float64` contiguous array |
| **Output length** | Same as input (NaN-padded) | Truncated (lookback bars shorter) |
| **NaN handling** | Pads warmup with NaN | Strips warmup entirely |
| **Multi-output** | Returns tuple | Returns tuple |
| **Pandas support** | Yes (via `ArrayLike`) | No |
| **Streaming** | Yes (StreamingXxx classes) | No |
---
## Output length difference
Tulipy **truncates** output instead of NaN-padding. When comparing results
you must align by the **trailing** elements:
```python
import tulipy as ti
import ferro_ta
import numpy as np
close = np.ascontiguousarray(np.random.randn(100).cumsum() + 100, dtype=np.float64)
ti_sma = ti.sma(close, period=20) # len = 81
ft_sma = ferro_ta.SMA(close, timeperiod=20) # len = 100 (19 leading NaN)
# Align: compare last 81 values
n = len(ti_sma)
assert np.allclose(ti_sma, ft_sma[-n:][np.isfinite(ft_sma[-n:])], atol=1e-8)
```
---
## Function signature mapping
Tulipy uses lowercase function names. The `period` argument is always a
positional-or-keyword integer.
| Indicator | ferro-ta | Tulipy |
|-----------|---------|--------|
| SMA | `SMA(close, timeperiod=20)` | `sma(close, period=20)` |
| EMA | `EMA(close, timeperiod=20)` | `ema(close, period=20)` |
| WMA | `WMA(close, timeperiod=14)` | `wma(close, period=14)` |
| RSI | `RSI(close, timeperiod=14)` | `rsi(close, period=14)` |
| MACD | `MACD(close, 12, 26, 9)` | `macd(close, short_period=12, long_period=26, signal_period=9)` |
| BBANDS | `BBANDS(close, timeperiod=20, nbdevup=2.0, nbdevdn=2.0)` → (upper, mid, lower) | `bbands(close, period=20, stddev=2.0)` → (lower, mid, upper) ⚠️ reversed! |
| ATR | `ATR(high, low, close, timeperiod=14)` | `atr(high, low, close, period=14)` |
| OBV | `OBV(close, volume)` | `obv(close, volume)` |
| CCI | `CCI(high, low, close, timeperiod=14)` | `cci(high, low, close, period=14)` |
| WILLR | `WILLR(high, low, close, timeperiod=14)` | `willr(high, low, close, period=14)` |
| STOCH | `STOCH(high, low, close, 5, 3, 3)` | `stoch(high, low, close, ...)` |
| HMA | Not supported | `hma(close, period=14)` |
| DEMA | `DEMA(close, timeperiod=30)` | `dema(close, period=30)` |
| TEMA | `TEMA(close, timeperiod=30)` | `tema(close, period=30)` |
| AROON | `AROONOSC(high, low, timeperiod=14)` | `aroonosc(high, low, period=14)` |
| MFI | `MFI(high, low, close, volume, timeperiod=14)` | `mfi(high, low, close, volume, period=14)` |
| TRANGE | `TRANGE(high, low, close)` | `tr(high, low, close)` |
⚠️ **BBANDS tuple order**: Tulipy returns `(lower, middle, upper)`;
ferro-ta and TA-Lib return `(upper, middle, lower)`.
---
## Memory requirements
Tulipy requires **strictly contiguous** `np.float64` arrays. Passing a
Pandas Series slice or a non-contiguous array causes an error:
```python
# Wrong — may be a non-contiguous view
close = df["close"].values
ti.sma(close, period=20) # may raise ValueError
# Correct — explicit contiguous cast
close = np.ascontiguousarray(df["close"].values, dtype=np.float64)
ti.sma(close, period=20) # always works
```
ferro-ta accepts any `ArrayLike` and handles the conversion internally.
---
## Numerical accuracy
Tulipy and ferro-ta agree closely for SMA, WMA, and other non-recursive
indicators (differences < 1e-8). For EMA-based indicators the first
`timeperiod` values differ due to initialisation seed choice:
- **Tulipy**: uses the first data value as the EMA seed.
- **ferro-ta**: follows TA-Lib convention (SMA of first `timeperiod` bars).
Values converge after approximately 2–3× the `timeperiod`.
---
## Speed comparison
On 10,000 bars (median µs, Apple M-series):
| Indicator | ferro-ta | Tulipy | Winner |
|-----------|--------:|-------:|--------|
| SMA | 16.7 | 21.2 | ferro-ta |
| MACD | 70.4 | 30.2 | Tulipy |
| ATR | 51.4 | 27.6 | Tulipy |
Tulipy's C99 implementation excels for recursive indicators (ATR, MACD).
ferro-ta is faster for sliding-window indicators (SMA) thanks to SIMD
vectorisation.
---
## Migration guide
```python
# FROM Tulipy
import tulipy as ti
import numpy as np
close = np.ascontiguousarray(close_series.values, dtype=np.float64)
sma_values = ti.sma(close, period=20) # length: n - 19
# TO ferro-ta (drop-in, same numeric result in the tail)
import ferro_ta
sma_values = ferro_ta.SMA(close, timeperiod=20) # length: n (19 leading NaN)
# Strip warmup if needed:
sma_values = sma_values[~np.isnan(sma_values)]
```