quantjourney-ti 0.3.2

Comprehensive technical indicators for financial data.

QuantJourney Technical Indicators

A high-performance Python library for calculating technical indicators, optimized with Numba for speed and designed for financial data analysis. This project is part of the Quantitative Infrastructure initiative by QuantJourney, providing robust tools for traders and researchers.

License: MIT License - see LICENSE for details.
Author: Jakub Polec ([e-mail])
Repository: github.com/QuantJourneyOrg/qj_technical_indicators

Overview

The QuantJourney Technical Indicators library offers a comprehensive set of technical indicators for analyzing financial time series data. Key features include:

• Numba-Optimized Calculations: Fast, JIT-compiled functions for performance-critical computations.
• Flexible API: Supports both standalone functions and a TechnicalIndicators class for object-oriented usage.
• Robust Error Handling: Validates inputs and handles edge cases like NaNs and empty data.
• Visualization: Generates individual plots for indicators, saved as PNG files in an indicator_plots directory.
• Integration: Works seamlessly with pandas DataFrames and yfinance for data fetching.

Extras and Lazy Loading

• Optional extras keep the core lightweight:

  • pip install .[yf] to enable yfinance-based examples/tests
  • pip install .[plot] to enable plotting with matplotlib

• Lazy JIT compile: kernels compile on first use and are cached to disk. You can opt-in to eager compile for lower first-call latency:

from quantjourney_ti import TechnicalIndicators
ti = TechnicalIndicators(warmup=True)  # pre-compiles a common subset of kernels

• Logging: queue logging is opt-in to avoid starting background threads on import:

from quantjourney_ti import start_logging_queue
start_logging_queue()  # enable QueueHandler + background consumer thread

The library is ideal for backtesting trading strategies, real-time analysis, and research, with a focus on simplicity and extensibility.

Recent Improvements

• DataFrame inputs with only adj_close are now auto-normalized for indicators that require a close column.
• SMA gains a lightweight cache via @cached_indicator to speed repeat calls on unchanged inputs.
• Streaming buffers now respect the constructor’s max_buffer_size argument.
• Risk metrics correctly detect constant price series as prices (max drawdown = 0).
• Validation utilities and logging were streamlined to improve robustness in mixed environments.

Caching

Some indicators support lightweight caching to avoid repeated computation on identical inputs.

• The @cached_indicator(ttl_seconds=3600) decorator enables memoization with a time‑to‑live.
• Inputs are hashed by content (values + index) to detect duplicates safely.
• Example: SMA uses caching out of the box.

Cache control utilities:

from quantjourney_ti import get_cache_stats, clear_indicator_cache

# View cache statistics
print(get_cache_stats())

# Clear all cached entries
clear_indicator_cache()

To add caching to your own wrappers, apply @cached_indicator above your method. Choose an appropriate TTL for your workload.

Project Structure

The repository is organized as follows (top-level view):

quantjourney_ti/              # Package code
├── __init__.py               # Public exports and helpers
├── indicators.py             # Main API class (TechnicalIndicators)
├── technical_indicators.py   # Legacy compatibility wrapper(s)
├── _indicator_kernels.py     # Numba-accelerated kernels
├── _decorators.py            # timer / numba_fallback
├── _errors.py                # Custom errors
├── _utils.py                 # Validation, plotting, memory helpers
├── _performance.py           # Caching, profiling, perf stats
├── _risk_metrics.py          # Risk metrics utilities
├── _streaming.py             # Streaming indicators + datafeed
├── kernels/                  # Organized numba kernels
│   ├── __init__.py
│   ├── trend_numba.py
│   ├── momentum_numba.py
│   ├── volatility_numba.py
│   └── volume_numba.py
└── _legacy_/                 # Older APIs kept for reference
    └── technical_indicators.py

tests/                        # Unit and integration tests (pytest)
docs/                         # Documentation
├── INDICATORS.md
└── USAGE.md
examples/                     # Usage examples and scripts
notebooks/                    # Jupyter notebooks
indicator_plots/              # Saved example plots

pyproject.toml                # Build + project metadata
requirements.txt              # Dev/test dependencies
CHANGELOG.md                  # Release notes
LICENSE                       # MIT License text
README.md                     # This file

Installation

1. Clone the repository:

   git clone https://github.com/QuantJourneyOrg/qj_technical_indicators.git
   cd qj_technical_indicators
   

2. Install dependencies:

   pip install -r requirements.txt
   # optional extras
   pip install .[yf]
   pip install .[plot]
   

3. Install the package in editable mode:

   pip install -e .
   

Requirements:

• Python 3.11–3.14
• pandas, numpy, yfinance, numba, matplotlib

Usage

The library provides a TechnicalIndicators class for calculating indicators and saving plots. See docs/USAGE.md for a compact guide and notebooks/ for interactive examples. Example:

import numpy as np
import pandas as pd
import yfinance as yf

from quantjourney_ti import TechnicalIndicators
from quantjourney_ti._utils import plot_indicators

# Fetch data (requires extra 'yf')
df = yf.download("AAPL", start="2024-01-01", end="2025-02-01", progress=False)
if isinstance(df.columns, pd.MultiIndex):
    df.columns = df.columns.get_level_values(0).str.lower().str.replace(" ", "_")
else:
    df.columns = df.columns.str.lower().str.replace(" ", "_")
df["volume"] = df["volume"].replace(0, np.nan).ffill()

ti = TechnicalIndicators()
ema = ti.EMA(df["close"], 20)
rsi = ti.RSI(df["close"], 14)
macd = ti.MACD(df["close"], 12, 26, 9)

Examples:

python examples/run_basic.py --ticker AAPL --period 6mo
python examples/run_channels.py --ticker AAPL --period 6mo
python examples/run_from_csv.py --csv path/to/ohlcv.csv --sep ,

Notebooks:

• notebooks/01_basic_indicators.ipynb
• notebooks/02_channels_and_bands.ipynb
• notebooks/03_streaming_demo.ipynb

📊 Example Plot

Supported Indicators

The library supports 39 indicators (54 series):

• Single-Series Indicators (21):
  • SMA (Simple Moving Average)
  • EMA (Exponential Moving Average)
  • RSI (Relative Strength Index)
  • ATR (Average True Range)
  • MFI (Money Flow Index)
  • TRIX
  • CCI (Commodity Channel Index)
  • ROC (Rate of Change)
  • WILLR (Williams %R)
  • DEMA (Double Exponential Moving Average)
  • KAMA (Kaufman Adaptive Moving Average)
  • AO (Awesome Oscillator)
  • ULTIMATE_OSCILLATOR
  • CMO (Chande Momentum Oscillator)
  • DPO (Detrended Price Oscillator)
  • MASS_INDEX
  • VWAP (Volume Weighted Average Price)
  • AD (Accumulation/Distribution Line)
  • HULL_MA (Hull Moving Average)
  • OBV (On-Balance Volume)
  • RVI (Relative Vigor Index)
• Multi-Series Indicators (18):
  • MACD (MACD, Signal, Histogram)
  • BB (Bollinger Bands: BB_Upper, BB_Middle, BB_Lower)
  • STOCH (Stochastic Oscillator: K, D)
  • ADX (Average Directional Index: ADX, +DI, -DI)
  • ICHIMOKU (Tenkan-sen, Kijun-sen, Senkou Span A, Senkou Span B, Chikou Span)
  • KELTNER (Keltner Channels: KC_Upper, KC_Middle, KC_Lower)
  • DONCHIAN (Donchian Channels: DC_Upper, DC_Middle, DC_Lower)
  • AROON (AROON_UP, AROON_DOWN, AROON_OSC)
  • VOLUME_INDICATORS (Volume_SMA, Force_Index, VPT)
  • PIVOT_POINTS (PP, R1, R2, S1, S2)
  • RAINBOW (9 SMAs for periods 2-10)
  • BETA
  • DI (Directional Indicator: +DI, -DI)
  • ADOSC (Chaikin A/D Oscillator)
  • HEIKEN_ASHI (HA_Open, HA_High, HA_Low, HA_Close)
  • BENFORD_LAW (Observed, Expected)
  • MOMENTUM_INDEX (MomentumIndex, NegativeIndex)
  • ELDER_RAY (BullPower, BearPower)

See indicators.py for the full list and parameters.

Development

To contribute:

1. Fork the repository and create a branch.
2. Add new indicators in _indicator_kernels.py with Numba optimization.
3. Define public methods in indicators.py.
4. Update tests in tests/.
5. Submit a pull request.

Testing:

# Core tests (no network):
pytest -m "not slow"  # skips network-dependent tests

# Full suite including yfinance examples (requires network + optional extras):
pytest

• All tests live under tests/.
• Slow/optional tests are marked @pytest.mark.slow.
• Some tests require extras: install with pip install .[yf] and pip install .[plot].

Contact

For issues or feedback, contact Jakub Polec at [e-mail] or open an issue on GitHub.