diff --git a/README.md b/README.md index 56bb940..dea994d 100644 --- a/README.md +++ b/README.md @@ -44,10 +44,10 @@ This is the **classic/community maintained version** of the popular pandas-ta li ### Key Features -- **253 Unique Indicators & Patterns**: 193 Category indicators + 62 CDL patterns via `cdl_pattern()` = 253 unique (doji and inside appear in both counts; all CDL patterns use native Python — no TA-Lib required) +- **284 Unique Indicators & Patterns**: 224 Category indicators + 62 CDL patterns via `cdl_pattern()` = 284 unique (doji and inside appear in both counts; all CDL patterns use native Python — no TA-Lib required) - **All-Native Candlestick Patterns**: All 62 CDL patterns have native Python implementations — TA-Lib is never used for CDL patterns -- **Optional TA-Lib Acceleration**: 59 core indicators (EMA, SMA, RSI, MACD, OBV, ATR, etc.) use native implementations by default; pass `talib=True` to use TA-Lib -- **Compatibility Scope Is Explicit**: Not every TA-Lib/tulipy function has a pandas-ta-classic counterpart. Current mapping includes 67 indicators with TA-Lib counterparts, 71 with tulipy counterparts, and 44 covered by both. Full per-indicator matrix: `docs/indicator_support_matrix.rst` +- **Optional TA-Lib Acceleration**: Core indicators (EMA, SMA, RSI, MACD, OBV, ATR, etc.) use native implementations by default; pass `talib=True` to use TA-Lib +- **Compatibility Scope Is Explicit**: Not every TA-Lib/tulipy function has a pandas-ta-classic counterpart. See the full per‑indicator matrix for current coverage: `docs/indicator_support_matrix.rst` - **Optional Performance Boost**: Install `numba` for 6–230× speedups on hot-loop indicators (QQE, RSX, HWMA, SSF, PSAR, Supertrend, MCGD) - **Automatic Versioning**: Version management via git tags using setuptools-scm - **Modern Package Management**: Full support for both `uv` and `pip` @@ -142,15 +142,15 @@ df.ta.strategy("CommonStrategy") # Runs commonly used indicators ## Features -- **193 Technical Indicators & Utilities** across 9 categories (Candles, Cycles, Momentum, Overlap, Trend, Volume, etc.) +- **224 Technical Indicators & Utilities** across 10 categories (Candles, Cycles, Math, Momentum, Overlap, Trend, Volume, etc.) - **62 Native Candlestick Patterns** — all patterns natively implemented, no TA-Lib required -- **253 Unique Indicators & Patterns** - 193 category indicators plus 62 CDL patterns via `cdl_pattern()` +- **284 Unique Indicators & Patterns** - 224 category indicators plus 62 CDL patterns via `cdl_pattern()` - **Dynamic Category Discovery** - automatically detects all available indicators from the filesystem - **Optional Numba Acceleration** - 6–230× speedups via `pip install pandas-ta-classic[performance]` - **Strategy System** with multiprocessing support for bulk indicator processing - **Fluent API Chaining**: ``df.ta.chain().sma(20).ta.rsi(14).ta.macd().ta.bbands(20)`` — chain multiple indicators in a single expression - **Pandas DataFrame Extension** for seamless integration (`df.ta.indicator()`) -- **TA-Lib Integration (dual-role)** - **(1) acceleration backend**: 59 core indicators use native implementations by default; pass `talib=True` to use TA-Lib's C implementation. **(2) oracle**: `test_oracle_talib.py` verifies parity against TA-Lib +- **TA-Lib Integration (dual-role)** - **(1) acceleration backend**: core indicators use native implementations by default; pass `talib=True` to use TA-Lib's C implementation. **(2) oracle**: `test_oracle_talib.py` verifies parity against TA-Lib - **tulipy Integration (oracle only)** - parity test oracle; `test_oracle_tulipy.py` verifies native output against tulipy; never used as computation backend - **Backtesting.py Integration** — bridge function and runnable SMA crossover example in ``examples/backtesting_py_strategy.py`` - **backtrader Integration** — precompute-then-feed pattern with dynamic `PandasData` subclass; runnable example in ``examples/backtrader_strategy.py`` @@ -171,7 +171,7 @@ df.ta.strategy("CommonStrategy") # Runs commonly used indicators **Reference Documentation:** - [**Usage Guide**](https://xgboosted.github.io/pandas-ta-classic/usage.html) - Programming conventions and basic usage - [**Strategy System**](https://xgboosted.github.io/pandas-ta-classic/strategies.html) - Multiprocessing and bulk indicator processing -- [**Indicators Reference**](https://xgboosted.github.io/pandas-ta-classic/indicators.html) - Complete list of 193 indicators plus 62 CDL patterns (253 unique total) +- [**Indicators Reference**](https://xgboosted.github.io/pandas-ta-classic/indicators.html) - Complete list of 224 indicators plus 62 CDL patterns (284 unique total) - [**DataFrame API**](https://xgboosted.github.io/pandas-ta-classic/dataframe_api.html) - Properties and methods reference - [**Performance Metrics**](https://xgboosted.github.io/pandas-ta-classic/performance.html) - Backtesting and performance analysis @@ -185,7 +185,7 @@ df.ta.strategy("CommonStrategy") # Runs commonly used indicators | Library | Role | Effect when installed | |---------|------|-----------------------| -| TA-Lib | **Acceleration backend + oracle** | 59 core indicators — native by default, opt-in via `talib=True`; also used in `test_oracle_talib.py` for parity checks | +| TA-Lib | **Acceleration backend + oracle** | Core indicators — native by default, opt-in via `talib=True`; also used in `test_oracle_talib.py` for parity checks | | tulipy | **Oracle only** | Never used as computation backend; only `test_oracle_tulipy.py` uses it to verify native output | | Area | Behaviour without TA-Lib | Behaviour with TA-Lib | @@ -215,7 +215,7 @@ pip install TA-Lib # TA-Lib only (also enables acceleration backend) pip install tulipy # tulipy only (oracle test use only) ``` -> **Note:** Both oracle test suites (`test_oracle_talib.py`, `test_oracle_tulipy.py`) are guarded with `@unittest.skipUnless` and skip automatically when the respective library is not installed. Neither is required for normal use. Installing TA-Lib additionally enables C-library acceleration for 59 indicators via `talib=True`. +> **Note:** Both oracle test suites (`test_oracle_talib.py`, `test_oracle_tulipy.py`) are guarded with `@unittest.skipUnless` and skip automatically when the respective library is not installed. Neither is required for normal use. Installing TA-Lib additionally enables C-library acceleration for core indicators via `talib=True`. **Performance boost:** Install `numba` for 6–230× speedups on computation-heavy indicators: - Using `uv`: `uv pip install pandas-ta-classic[performance]` diff --git a/docs/index.rst b/docs/index.rst index f755bba..5b07a4a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,7 +1,7 @@ Pandas TA Classic Documentation =============================== -**Pandas TA Classic** is an easy to use library that leverages the Pandas package with **193 indicators and utility functions** plus **62 native candlestick patterns** (**253 unique total**; ``cdl_doji`` and ``cdl_inside`` are counted in both sets). All CDL patterns are natively implemented — no TA-Lib required. This is the **community maintained version** of the popular pandas-ta library. +**Pandas TA Classic** is an easy to use library that leverages the Pandas package with **224 indicators and utility functions** plus **62 native candlestick patterns** (**284 unique total**; ``cdl_doji`` and ``cdl_inside`` are counted in both sets). All CDL patterns are natively implemented — no TA-Lib required. This is the **community maintained version** of the popular pandas-ta library. .. note:: The library features **dynamic configuration management**: diff --git a/docs/indicator_support_matrix.rst b/docs/indicator_support_matrix.rst index ea0e63a..1085bd9 100644 --- a/docs/indicator_support_matrix.rst +++ b/docs/indicator_support_matrix.rst @@ -1,6 +1,8 @@ Indicator Compatibility Matrix ============================== +The full per-indicator compatibility table (Native / TA-Lib / tulipy) is maintained here: + Legend: ``yes`` = indicator has corresponding implementation in that library by direct name or maintained alias mapping. .. list-table:: pandas-ta-classic indicator support vs TA-Lib and tulipy diff --git a/docs/indicators.rst b/docs/indicators.rst index 15664ee..f88bafb 100644 --- a/docs/indicators.rst +++ b/docs/indicators.rst @@ -381,9 +381,4 @@ Utility / signal functions (accessible directly or via ``df.ta``): * *Crossany*: **crossany** (returns Boolean Series that is True on any bar where ``a`` and ``b`` cross in either direction) * *Lag*: **lag** (returns a Series offset by ``n`` periods; equivalent to tulipy ``lag``) -Compatibility Matrix --------------------- - -The full per-indicator compatibility table (Native / TA-Lib / tulipy) is maintained here: - .. include:: indicator_support_matrix.rst \ No newline at end of file diff --git a/docs/installation.rst b/docs/installation.rst index a6594a5..643fe94 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -19,6 +19,7 @@ Optional Dependencies For enhanced functionality, consider installing: - **TA-Lib**: Optional — all 62 CDL patterns work natively without it (see :ref:`Installing TA-Lib` below) +- **tulipy**: Optional — oracle-only; used by ``test_oracle_tulipy.py`` for parity verification, never as a computation backend - **yfinance**: For downloading stock data with ``df.ta.ticker()`` - **vectorbt**: For backtesting integration - **pytest + Hypothesis**: For running the test suite and property-based tests (``pip install pandas-ta-classic[test]``) @@ -123,7 +124,7 @@ Both TA-Lib and tulipy are **fully optional**. They serve different roles: - Effect when installed * - TA-Lib - **Acceleration backend + oracle** - - 59 core indicators — native by default, opt-in via ``talib=True``; also used by ``test_oracle_talib.py`` for parity checks + - Core indicators — native by default, opt-in via ``talib=True``; also used by ``test_oracle_talib.py`` for parity checks * - tulipy - **Oracle only** - Never used as computation backend; only ``test_oracle_tulipy.py`` uses it to verify native output @@ -133,12 +134,12 @@ Both TA-Lib and tulipy are **fully optional**. They serve different roles: Installing TA-Lib ~~~~~~~~~~~~~~~~~ -TA-Lib has a **dual role**: acceleration backend for 59 core indicators (opt-in via ``talib=True``), and parity oracle. The two behavioural areas affected are: +TA-Lib has a **dual role**: acceleration backend for core indicators (opt-in via ``talib=True``), and parity oracle. The two behavioural areas affected are: **Candlestick patterns (CDL family)** All 62 CDL patterns have native Python implementations that are always used. TA-Lib is **never** invoked for CDL patterns — the TA-Lib fallback code path in ``cdl_pattern()`` is only retained for hypothetical future patterns without a native implementation. -**59 core indicators** (``ema``, ``sma``, ``rsi``, ``macd``, ``obv``, ``atr``, etc.) +**Core indicators** (``ema``, ``sma``, ``rsi``, ``macd``, ``obv``, ``atr``, etc.) The native implementation is used by default. TA-Lib is opt-in — pass ``talib=True`` to any call to use TA-Lib's implementation instead. .. code-block:: python @@ -151,25 +152,38 @@ TA-Lib has a **dual role**: acceleration backend for 59 core indicators (opt-in # Use TA-Lib implementation if installed ema = df.ta.ema(length=20, talib=True) - # CDL patterns — always native, talib= kwarg has no effect here - df = df.ta.cdl_pattern(name="engulfing") # native - result = df.ta.cdl_pattern(name="hammer") # native + # CDL patterns — always native, talib= kwarg has no effect here + df = df.ta.cdl_pattern(name="engulfing") # native + result = df.ta.cdl_pattern(name="hammer") # native -Installing TA-Lib: +Installation +^^^^^^^^^^^^ + +Binary wheels (v0.6.5+) bundle the TA-Lib C library — no separate C library +setup needed. Versions before 0.6.5 lack binary wheels and require manual C library +installation. We require ``>=0.6.8`` so ``pip install ta-lib`` works out of +the box on Linux, macOS, and Windows (x86\_64, arm64): Using ``uv``: .. code-block:: bash - uv pip install TA-Lib + uv pip install "ta-lib>=0.6.8" Using ``pip``: .. code-block:: bash - pip install TA-Lib + pip install "ta-lib>=0.6.8" -**Note**: If you encounter installation issues with TA-Lib, refer to the `TA-Lib installation guide `_. +If your platform is not covered by binary wheels, or you prefer a source build, install the `TA-Lib C library `_ first. For Conda users: + +.. code-block:: bash + + conda install -c conda-forge libta-lib + conda install -c conda-forge ta-lib + +See the `TA-Lib Python README `_ for platform-specific instructions and troubleshooting. Installing tulipy ~~~~~~~~~~~~~~~~~ diff --git a/docs/quickstart.md b/docs/quickstart.md index 7e4d0ae..92b44cf 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -420,14 +420,11 @@ pip install --upgrade pandas-ta-classic **Solution:** TA-Lib is optional and only used for supported core indicators (candlestick patterns are native). Install TA-Lib separately: ```bash -# On Linux/Mac -pip install TA-Lib - -# On Windows, download wheel from: -# https://www.lfd.uci.edu/~gohlke/pythonlibs/#ta-lib -pip install TA_Lib-0.4.XX-cpXX-cpXX-win_amd64.whl +pip install "ta-lib>=0.6.8" ``` +Binary wheels (v0.6.5+) bundle the C library — no separate TA-Lib C installation needed on any platform. Versions before 0.6.5 lack binary wheels and require manual C library setup. + (next-steps)= ## Next Steps @@ -435,7 +432,7 @@ Now that you've got the basics, explore more: 1. **[Full Documentation](https://xgboosted.github.io/pandas-ta-classic/)** - Complete API reference 2. **[Tutorials](https://xgboosted.github.io/pandas-ta-classic/tutorials.html)** - Step-by-step guides for common tasks -3. **[Indicator Reference](https://xgboosted.github.io/pandas-ta-classic/indicators.html)** - 192 indicators plus 62 CDL patterns (252 unique total) +3. **[Indicator Reference](https://xgboosted.github.io/pandas-ta-classic/indicators.html)** - 224 indicators plus 62 CDL patterns (284 unique total) 4. **[Strategy Guide](https://xgboosted.github.io/pandas-ta-classic/strategies.html)** - Advanced strategy system 5. **[Examples](https://github.com/xgboosted/pandas-ta-classic/tree/main/examples)** - Jupyter notebooks with real examples diff --git a/docs/testing.rst b/docs/testing.rst index de1e362..e10b20c 100644 --- a/docs/testing.rst +++ b/docs/testing.rst @@ -68,7 +68,7 @@ Requires ``ta-lib`` and ``tulipy`` installed. Native Indicator Tests ---------------------- -**Why:** Cover ~45 indicators that have no TA-Lib alternative, validating +**Why:** Cover indicators that have no TA-Lib alternative, validating return type, non-NaN row count, value finiteness, and mathematical bounds. **Files:** ``test_native_indicators.py``. @@ -164,7 +164,7 @@ boundary violations. * **Mathematical invariants** — Bollinger Band ordering, ATR/STDEV non-negativity, MOM/ROC relationship. * **Core utilities** — ``verify_series``, ``apply_offset``, ``apply_fill``. -* **None-guard safety** — 7 indicators return ``None`` for ``None`` input. +* **None-guard safety** — Indicators return ``None`` for ``None`` input. * **NaN propagation** — All-NaN input → all-NaN output, no crash. * **Idempotence** — Same args twice → identical result. * **Category discovery** — Dynamic discovery stays consistent. diff --git a/index.md b/index.md index bae4606..9178419 100644 --- a/index.md +++ b/index.md @@ -5,17 +5,17 @@ title: Pandas TA Classic - Technical Analysis Library # Pandas TA Classic -**Pandas Technical Analysis (Pandas TA Classic)** is an easy to use library that leverages the Pandas package with **193 indicators and utility functions** plus **62 native candlestick patterns** (**253 total unique** — no TA-Lib required). This is the **community maintained version** of the popular pandas-ta library. +**Pandas Technical Analysis (Pandas TA Classic)** is an easy to use library that leverages the Pandas package with **224 indicators and utility functions** plus **62 native candlestick patterns** (**284 total unique** — no TA-Lib required). This is the **community maintained version** of the popular pandas-ta library. ![Example Chart](https://raw.githubusercontent.com/xgboosted/pandas-ta-classic/main/docs/images/TA_Chart.png) ## Features -* **193 indicators and utility functions** across 9 categories +* **224 indicators and utility functions** across 10 categories * **62 native candlestick patterns** — all natively implemented, no TA-Lib required -* **253 total unique indicators and patterns** +* **284 total unique indicators and patterns** * Dynamic category discovery - automatically detects available indicators -* **Optional TA-Lib Acceleration**: 34 core indicators auto-use TA-Lib when installed; pass `talib=False` to force native +* **Optional TA-Lib Acceleration**: Core indicators auto-use TA-Lib when installed; pass `talib=False` to force native * **Optional Oracle Libraries**: TA-Lib (acceleration backend + oracle) and tulipy (oracle only) are optional and skip gracefully when not installed * Supports both standalone and DataFrame extension usage * **Fluent API chaining**: ``df.ta.chain().sma(20).ta.rsi(14).ta.macd()`` diff --git a/pyproject.toml b/pyproject.toml index aafae70..ca057f3 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -53,8 +53,8 @@ optional = [ # External oracle libraries for parity tests oracle = [ - "ta-lib", - "tulipy", + "ta-lib>=0.6.8", + "tulipy>=0.4.0", ] # CI code quality tools