Migration from TA-Lib

ferro-ta is designed as a drop-in replacement for ta-lib (the Python talib package) for the most-commonly used indicators. This guide explains the differences so you can migrate existing code with confidence.

Import changes 

TA-Lib uses a single flat namespace:

import talib
result = talib.SMA(close, timeperiod=14)

ferro-ta exposes the same names at the top level and in sub-modules:

# Option A — top-level (most concise, mirrors talib)
from ferro_ta import SMA, EMA, RSI
result = SMA(close, timeperiod=14)

# Option B — sub-modules
from ferro_ta.overlap import SMA
from ferro_ta.momentum import RSI

Multi-output functions return a tuple in both libraries:

# talib
upper, middle, lower = talib.BBANDS(close)

# ferro_ta
upper, middle, lower = ferro_ta.BBANDS(close)

Input / output conventions 

Both libraries accept NumPy float64 arrays. ferro-ta also accepts any array-like (Python list, float32, pandas Series) and converts automatically.

Leading NaN values — both libraries emit NaN for the “warm-up” period at the start of an array. The number of NaN values is identical for all indicators marked Exact or Close in the accuracy table.
Output length — always equal to input length, matching TA-Lib.
Pandas Series — ferro-ta transparently preserves the original index when a pd.Series is passed as input.

Accuracy levels 

Symbol	Meaning
✅ Exact	Values match TA-Lib to floating-point precision.
✅ Close	Values converge to TA-Lib after the warm-up window (EMA-seed differences resolve within ~50 bars for typical periods).
⚠️ Corr	Strong correlation (> 0.95) but not numerically identical (e.g. MAMA uses the same algorithm but slightly different initialization).
⚠️ Shape	Same output shape and NaN structure; absolute values differ (e.g. SAR reversal history can diverge due to floating-point accumulation).

All overlap, momentum, volume, volatility, statistic, and price-transform functions are Exact or Close. The only remaining Corr / Shape functions are MAMA, SAR, SAREXT, and the six HT_* cycle indicators — see the roadmap for details.

Known behavioural differences 

EMA / DEMA / TEMA / T3 / MACD 

TA-Lib seeds the first EMA value with a simple moving average. ferro-ta uses the same seeding, so values converge after the warm-up period. For a 14-period EMA on typical market data, convergence is complete by bar ~60.

RSI 

ferro-ta uses the same Wilder smoothing seed as TA-Lib (SMA seed for the first timeperiod bars) and produces Exact results.

SAR / SAREXT 

Parabolic SAR reversal history can diverge in rare edge-cases due to floating-point accumulation differences. Output shapes (NaN count, length) match exactly.

HT_* cycle indicators 

The Hilbert Transform cycle indicators (HT_DCPERIOD, HT_DCPHASE, HT_PHASOR, HT_SINE, HT_TRENDLINE, HT_TRENDMODE) use the same Ehlers algorithm as TA-Lib but may differ slightly in floating-point accumulation. All six share a 63-bar lookback matching TA-Lib.

OBV 

ferro-ta OBV starts accumulation from zero at bar 0 (same as TA-Lib for most data sets). If your TA-Lib OBV shows an offset this is usually due to a starting volume difference in the input data.

Before / after example 

# --- Before (ta-lib) ---
import numpy as np
import talib

close = np.random.rand(200).cumsum() + 100.0
high  = close + 0.5
low   = close - 0.5

sma   = talib.SMA(close, timeperiod=14)
ema   = talib.EMA(close, timeperiod=14)
rsi   = talib.RSI(close, timeperiod=14)
upper, mid, lower = talib.BBANDS(close, timeperiod=20)
macd, signal, hist = talib.MACD(close)
atr   = talib.ATR(high, low, close, timeperiod=14)

# --- After (ferro_ta) ---
import numpy as np
from ferro_ta import SMA, EMA, RSI, BBANDS, MACD, ATR

close = np.random.rand(200).cumsum() + 100.0
high  = close + 0.5
low   = close - 0.5

sma   = SMA(close, timeperiod=14)
ema   = EMA(close, timeperiod=14)
rsi   = RSI(close, timeperiod=14)
upper, mid, lower = BBANDS(close, timeperiod=20)
macd, signal, hist = MACD(close)
atr   = ATR(high, low, close, timeperiod=14)

Only the import line changes for the most common indicators.

Extended (non-TA-Lib) indicators 

ferro-ta additionally provides indicators not in TA-Lib:

from ferro_ta import (
    VWAP, SUPERTREND, ICHIMOKU, DONCHIAN, PIVOT_POINTS,
    KELTNER_CHANNELS, HULL_MA, CHANDELIER_EXIT, VWMA, CHOPPINESS_INDEX,
)

See Extended Indicators for full API documentation.