Metadata-Version: 2.1
Name: quantjourney-ti
Version: 0.3.2
Summary: Comprehensive technical indicators for financial data.
Author-email: Jakub Polec <jakub@quantjourney.pro>
License: MIT License
        
        Copyright (c) 2025 Jakub Polec
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: Homepage, https://quantjourney.substack.com
Project-URL: Repository, https://github.com/QuantJourneyOrg/qj_technical_indicators
Project-URL: Bug Tracker, https://github.com/QuantJourneyOrg/qj_technical_indicators/issues
Keywords: financial,technical analysis,indicators,quant,numba
Classifier: License :: OSI Approved :: MIT License
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.15,>=3.11
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.26.0
Requires-Dist: pandas<3.0,>=2.0.0
Requires-Dist: numba>=0.59.0
Requires-Dist: scipy<2.0,>=1.11.0

# 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](https://quantjourney.substack.com), providing robust tools for traders and researchers.**

**License**: MIT License - see `LICENSE` for details.  
**Author**: Jakub Polec ([jakub@quantjourney.pro](mailto:jakub@quantjourney.pro))  
**Repository**: [github.com/QuantJourneyOrg/qj_technical_indicators](https://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:

```python
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:

```python
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:

```python
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:
   ```bash
   git clone https://github.com/QuantJourneyOrg/qj_technical_indicators.git
   cd qj_technical_indicators
   ```

2. Install dependencies:
   ```bash
   pip install -r requirements.txt
   # optional extras
   pip install .[yf]
   pip install .[plot]
   ```

3. Install the package in editable mode:
   ```bash
   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:

```python
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:

```bash
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
![Technical Indicator Example](docs/technical_indicator.png)

## 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**:
```bash
# 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 [jakub@quantjourney.pro](mailto:jakub@quantjourney.pro) or open an issue on GitHub.
