Pratik Bhadane
436954138f
Update version numbers across Rust, Python, and documentation files to 1.1.0. Enhance the .gitignore to include macOS dSYM files and plans directory. Introduce new dependencies in the Rust core library and update the README to reflect recent performance benchmarks and backtesting engine capabilities. Add new artifacts to the benchmarks manifest and improve documentation for the backtesting engine API.
140 lines
5.2 KiB
Markdown
140 lines
5.2 KiB
Markdown
<div align="center">
|
||
|
||
# ⚡ ferro-ta
|
||
|
||
### Rust-powered Python technical analysis with a TA-Lib-compatible API
|
||
|
||
**Focused on one primary job: fast, reproducible technical analysis for Python users who want TA-Lib-style ergonomics without native build friction.**
|
||
|
||
[](https://mybinder.org/v2/gh/pratikbhadane24/ferro-ta/HEAD?labpath=examples%2Fquickstart.ipynb)
|
||
[](https://colab.research.google.com/github/pratikbhadane24/ferro-ta/blob/main/examples/quickstart.ipynb)
|
||
[](https://pratikbhadane24.github.io/ferro-ta/)
|
||
|
||
</div>
|
||
|
||
---
|
||
|
||
> `ferro-ta` is a Rust-backed Python technical analysis library for NumPy-first workloads. It keeps TA-Lib-style ergonomics, ships pre-built wheels on supported targets, and publishes reproducible benchmark artifacts instead of blanket speed claims.
|
||
|
||
## 🚀 What ferro-ta is
|
||
|
||
| | TA-Lib | ferro-ta |
|
||
|---|---|---|
|
||
| **Primary product** | C-backed Python TA library | Rust-backed Python TA library |
|
||
| **API shape** | `talib.SMA(close, 20)` | `ferro_ta.SMA(close, 20)` |
|
||
| **Installation** | Often requires native/system setup | Pre-built wheels on supported targets |
|
||
| **Scope** | Technical indicators | Technical indicators first; other tooling is optional and secondary |
|
||
|
||
## ⚡ Benchmark evidence
|
||
|
||
The latest checked-in TA-Lib comparison artifact uses contiguous `float64`
|
||
arrays at 10k and 100k bars on an `Apple M3 Max`, `CPython 3.13.5`, and `Rust
|
||
1.91.1`.
|
||
|
||
- `ferro-ta` achieves competitive parity with TA-Lib, winning on 7 of 12 tested indicators at 100k bars (5 of 12 at 10k bars).
|
||
- Strong performance wins at 100k bars include `MFI` (`3.25×`), `WMA` (`2.20×`), `BBANDS` (`1.97×`), and `SMA` (`1.93×`) vs TA-Lib.
|
||
- TA-Lib maintains performance advantages on `STOCH` and `ADX`; `EMA`, `ATR`, and `OBV` are statistical ties.
|
||
- Compared to pure-Python libraries like Tulipy, `ferro-ta` provides 150-350x speedups through Rust-optimized implementations.
|
||
|
||
See the benchmark methodology and artifacts:
|
||
|
||
- [benchmarks/README.md](benchmarks/README.md)
|
||
- [benchmarks/artifacts/latest/](benchmarks/artifacts/latest/)
|
||
- [docs/benchmarks.rst](docs/benchmarks.rst)
|
||
|
||
## 🎯 Core capabilities
|
||
|
||
- 160+ indicators with a TA-Lib-style public API.
|
||
- Batch and streaming APIs for multi-series and bar-by-bar workloads.
|
||
- NumPy-first execution with pandas and polars adapters.
|
||
- Pre-built wheels on the supported Python and OS matrix.
|
||
- Type stubs, error codes, examples, and reproducible benchmarks.
|
||
|
||
Adjacent and experimental surfaces such as derivatives analytics, MCP, GPU,
|
||
plugins, and WASM remain opt-in and secondary to the core TA library story.
|
||
|
||
## 📦 Installation
|
||
|
||
```bash
|
||
pip install ferro-ta
|
||
```
|
||
|
||
Optional extras:
|
||
|
||
```bash
|
||
pip install "ferro-ta[pandas]" # pandas.Series support
|
||
pip install "ferro-ta[polars]" # polars.Series support
|
||
pip install "ferro-ta[gpu]" # PyTorch-backed GPU helpers
|
||
pip install "ferro-ta[options]" # derivatives analytics helpers
|
||
pip install "ferro-ta[mcp]" # MCP server for agent/tool clients
|
||
pip install "ferro-ta[all]" # most optional extras (excluding gpu)
|
||
```
|
||
|
||
## ⚡ Quick start
|
||
|
||
```python
|
||
import numpy as np
|
||
from ferro_ta import SMA, EMA, RSI, MACD, BBANDS
|
||
|
||
close = np.array([44.34, 44.09, 44.15, 43.61, 44.33, 44.83, 45.10, 45.15,
|
||
43.61, 44.33, 44.83, 45.10, 45.15, 43.61, 44.33])
|
||
|
||
sma = SMA(close, timeperiod=5)
|
||
ema = EMA(close, timeperiod=5)
|
||
rsi = RSI(close, timeperiod=14)
|
||
macd_line, signal, histogram = MACD(close, fastperiod=12, slowperiod=26, signalperiod=9)
|
||
upper, middle, lower = BBANDS(close, timeperiod=5, nbdevup=2.0, nbdevdn=2.0)
|
||
```
|
||
|
||
## 📊 TA-Lib compatibility
|
||
|
||
- `ferro-ta` implements 100% of TA-Lib's function set (`162+` indicators).
|
||
- Most functions are marked `Exact` or `Close`; the remaining notable non-exact categories are the Hilbert cycle indicators plus `MAMA`, `SAR`, and `SAREXT`.
|
||
- The full parity matrix and coverage summary now live in [TA_LIB_COMPATIBILITY.md](TA_LIB_COMPATIBILITY.md).
|
||
|
||
Migration and compatibility references:
|
||
|
||
- [docs/migration_talib.rst](docs/migration_talib.rst)
|
||
- [docs/compatibility/talib.md](docs/compatibility/talib.md)
|
||
- [docs/support_matrix.rst](docs/support_matrix.rst)
|
||
|
||
## 🗺️ Docs map
|
||
|
||
Core guides:
|
||
|
||
- [docs/quickstart.rst](docs/quickstart.rst)
|
||
- [docs/migration_talib.rst](docs/migration_talib.rst)
|
||
- [docs/support_matrix.rst](docs/support_matrix.rst)
|
||
- [PLATFORMS.md](PLATFORMS.md)
|
||
|
||
Evidence and APIs:
|
||
|
||
- [benchmarks/README.md](benchmarks/README.md)
|
||
- [docs/batch.rst](docs/batch.rst)
|
||
- [docs/streaming.rst](docs/streaming.rst)
|
||
- [docs/derivatives.rst](docs/derivatives.rst)
|
||
|
||
Optional and experimental surfaces:
|
||
|
||
- [docs/mcp.md](docs/mcp.md)
|
||
- [docs/adjacent_tooling.rst](docs/adjacent_tooling.rst)
|
||
- [docs/plugins.rst](docs/plugins.rst)
|
||
- [wasm/README.md](wasm/README.md)
|
||
|
||
Project and release docs:
|
||
|
||
- [CONTRIBUTING.md](CONTRIBUTING.md)
|
||
- [CHANGELOG.md](CHANGELOG.md)
|
||
- [VERSIONING.md](VERSIONING.md)
|
||
- [RELEASE.md](RELEASE.md)
|
||
|
||
## 🛠️ Development
|
||
|
||
```bash
|
||
uv sync --extra dev
|
||
uv run pytest tests/unit tests/integration
|
||
uv run maturin build --release --out dist
|
||
```
|
||
|
||
More setup details live in [CONTRIBUTING.md](CONTRIBUTING.md).
|