扩展指标

2026-07-09 05:08:16 +08:00
commit 308c46ab9a
537 changed files with 152299 additions and 0 deletions
@@ -0,0 +1,168 @@
+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.
+
+.. contents::
+   :local:
+   :depth: 2
+
+
+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
+---------------
+
+.. list-table::
+   :header-rows: 1
+
+   * - 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
+-----------------------
+
+.. code-block:: python
+
+    # --- 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 :doc:`extended` for full API documentation.