quantjourney-ti 0.3.1

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.md 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:

quantjourney_ti/
├── __init__.py               # Package initialization and imports
├── _decorators.py            # Decorators for timing and fallback mechanisms
├── _errors.py                # Custom error classes for input validation
├── _indicator_kernels.py     # Numba-optimized functions for indicator calculations
├── _legacy_/                 # Legacy code (not actively maintained)
├── _utils.py                 # Utility functions for validation, plotting, and memory optimization
├── indicators.py             # Main API class (TechnicalIndicators) with public methods
├── docs/                     # Documentation
│   ├── INDICATORS.md         # Explanation of each indicator
├── examples/                 # Example scripts demonstrating usage
│   ├── example_basic.py      # Basic indicator calculations
│   ├── example_indicators.py # Advanced usage with multiple indicators and plotting
├── tests/                    # Unit and integration tests
│   ├── __init__.py
│   ├── _yf.py                # yfinance test utilities
│   ├── test_all_indicators.py # Tests for all indicators
│   ├── test_basic.py         # Basic functionality tests
│   ├── test_decorators.py    # Decorator tests
│   ├── test_demo.py          # Demo script tests
│   ├── test_indicators.py    # Individual indicator tests
│   ├── test_integration_yf.py # Integration tests with yfinance
│   ├── test_utils.py         # Utility function tests
├── quantjourney_ti.egg-info/ # Package metadata (generated, typically in .gitignore)
├── README.md                 # Project documentation (this file)
├── LICENSE.md                # License details
├── setup.py                  # Package installation configuration

Note: The quantjourney_ti.egg-info directory is generated during package installation (e.g., pip install -e .). It can be safely removed if not using editable mode, and should be included in .gitignore to avoid version control.

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:

from quantjourney_ti import TechnicalIndicators
from quantjourney_ti._utils import plot_indicators
import pandas as pd
import yfinance as yf
import os

# Fetch data (requires extra 'yf')
df = yf.download("AAPL", start="2024-01-01", end="2025-02-01")
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

Cleaning: Remove generated files:

rm -rf quantjourney_ti.egg-info dist build

Future Work

• Add more indicators (e.g., PPO, Ichimoku Cloud).
• Enhance plotting with customizable layouts.
• Optimize Numba functions for additional edge cases.
• Support real-time data feeds.

Contact

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