QuantResearch 2.3
Technical indicators and visualization tools for quantitative research
License: MIT
Requires Python: >=3.7
Keywords: finance, trading, technical-analysis, indicators, quantitative, stocks, yfinance

# QuantResearch

[![Python Version](https://img.shields.io/badge/python-3.7+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI](https://img.shields.io/pypi/v/QuantResearch.svg)](https://pypi.org/project/QuantResearch/)

A comprehensive Python library for quantitative financial analysis, technical indicator calculation, and advanced trading signal visualization. QuantResearch provides easy-to-use functions for fetching market data, calculating technical indicators, and generating professional-grade trading charts with candlestick patterns.

## 📋 Table of Contents

- [Overview](#overview)
- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [API Reference](#api-reference)
  - [Data Fetching](#data-fetching)
  - [Technical Indicators](#technical-indicators)
  - [Visualization](#visualization)
- [Usage Examples](#usage-examples)
- [Requirements](#requirements)
- [Authors](#authors)
- [License](#license)
- [Support](#support)

## 🎯 Overview

QuantResearch is designed for traders, financial analysts, and quantitative researchers who need reliable technical analysis tools with professional visualization capabilities. It combines data fetching, indicator calculation, and candlestick charting into a single, intuitive package.

Whether you're backtesting trading strategies, analyzing market trends, or building automated trading systems, QuantResearch provides the essential tools you need with enhanced visualization options including candlestick charts for all major indicators.

## ✨ Features

- **📊 Data Fetching**: Download historical OHLCV data from Yahoo Finance
- **📈 Technical Indicators**: RSI, MACD, Bollinger Bands, ATR, SMA, EMA, DEMA, TEMA, RVWAP
- **🎨 Professional Visualization**: Beautiful charts with both line and candlestick chart support
- **🕯️ Candlestick Charts**: Full candlestick chart support for price action analysis
- **📉 Multi-Chart Views**: Combined price and indicator charts in single views
- **🔔 Signal Generation**: Automatic buy/sell crossover point detection
- **⚡ Simple API**: Intuitive functions that are easy to learn and use
- **🔧 Customizable Parameters**: Adjust periods and thresholds for your strategy
- **📱 Cross-Platform**: Works on Windows, macOS, and Linux

## 📦 Installation

Install QuantResearch using pip:

```bash
pip install QuantResearch
```

Or install from source:

```bash
git clone https://github.com/vinayak1729-web/QuantR.git
cd QuantR
pip install -e .
```

## 🚀 Quick Start

Here's a simple example to get started in 5 minutes:

```python
from QuantResearch import fetch_data, Rsi, plot_rsi

# Step 1: Fetch stock data
ticker = "AAPL"
data = fetch_data(ticker, start_date="2023-01-01", end_date="2024-01-01")

# Step 2: Calculate RSI
rsi = Rsi(data['Close'], period=14)

# Step 3: Visualize with candlestick chart
plot_rsi(data=data, rsi=rsi, period=14, ticker=ticker, kind='candle')
```

Run this and you'll see a beautiful dual-pane chart with candlesticks and RSI with overbought/oversold levels!

---

## 📚 API Reference

### Data Fetching

#### `fetch_data(ticker, start_date, end_date)`

Downloads historical OHLCV (Open, High, Low, Close, Volume, Adjusted Close) data for a given ticker from Yahoo Finance.

**Parameters:**
- `ticker` (str): Stock ticker symbol (e.g., "AAPL", "MSFT", "GOOGL")
- `start_date` (str): Start date in format "YYYY-MM-DD"
- `end_date` (str): End date in format "YYYY-MM-DD"

**Returns:**
- `pandas.DataFrame`: Contains columns: Open, High, Low, Close, Adj Close, Volume

**Example:**
```python
data = fetch_data("AAPL", "2023-01-01", "2024-01-01")
print(data.head())
print(f"Shape: {data.shape}")
```

---

### Technical Indicators

#### `Rsi(price, period=14)`

**Relative Strength Index** - A momentum oscillator measuring the magnitude of recent price changes.

**Parameters:**
- `price` (pandas.Series): Price series (typically closing prices)
- `period` (int): Lookback period for RSI calculation (default: 14)

**Returns:**
- `pandas.Series`: RSI values ranging from 0 to 100

**Interpretation:**
```
RSI > 70  → Overbought (potential sell signal)
RSI < 30  → Oversold (potential buy signal)
30-70     → Neutral zone
```

**Example:**
```python
rsi = Rsi(data['Close'], period=14)
print(f"Current RSI: {rsi.iloc[-1]:.2f}")
```

---

#### `bb_bands(price, period=20, num_std=2)`

**Bollinger Bands** - Volatility bands placed above and below a moving average.

**Parameters:**
- `price` (pandas.Series): Price series
- `period` (int): Lookback period (default: 20)
- `num_std` (int/float): Number of standard deviations (default: 2)

**Returns:**
- Tuple: (upper_band, middle_band, lower_band)

**Example:**
```python
upper, mid, lower = bb_bands(data['Close'], period=20, num_std=2)
plot_bollinger(data=data, adj_close=data['Close'], bb_upper=upper, 
               bb_mid=mid, bb_lower=lower, ticker="AAPL", kind='candle')
```

---

#### `macd(price, short_period=12, long_period=26, signal_period=9)`

**MACD** - Moving Average Convergence Divergence trend indicator.

**Parameters:**
- `price` (pandas.Series): Price series
- `short_period` (int): Short EMA period (default: 12)
- `long_period` (int): Long EMA period (default: 26)
- `signal_period` (int): Signal line EMA period (default: 9)

**Returns:**
- Tuple: (macd_line, signal_line, histogram)

**Example:**
```python
macd_line, signal_line, hist = macd(data['Close'])
plot_macd(macd_line, signal_line, hist, ticker="AAPL", data=data, kind='candle')
```

---

#### `atr(data, period=14)`

**Average True Range** - Volatility indicator measuring price movement range.

**Parameters:**
- `data` (pandas.DataFrame): OHLC data
- `period` (int): Lookback period (default: 14)

**Returns:**
- `pandas.Series`: ATR values

**Example:**
```python
atr_values = atr(data, period=14)
print(f"Current ATR: {atr_values.iloc[-1]:.2f}")
```

---

#### `sma(price, period=9)`

**Simple Moving Average** - Average price over specified period.

**Parameters:**
- `price` (pandas.Series): Price series
- `period` (int): Lookback period (default: 9)

**Returns:**
- `pandas.Series`: SMA values

---

#### `ema(price, period=9)`

**Exponential Moving Average** - Weighted average giving more importance to recent prices.

**Parameters:**
- `price` (pandas.Series): Price series
- `period` (int): Lookback period (default: 9)

**Returns:**
- `pandas.Series`: EMA values

---

#### `demma(price, period=9)`

**Double Exponential Moving Average** - Smoother trend indicator with reduced lag.

**Parameters:**
- `price` (pandas.Series): Price series
- `period` (int): Lookback period (default: 9)

**Returns:**
- `pandas.Series`: DEMA values

---

#### `temma(price, period=9)`

**Triple Exponential Moving Average** - Smoothest trend indicator with minimal lag.

**Parameters:**
- `price` (pandas.Series): Price series
- `period` (int): Lookback period (default: 9)

**Returns:**
- `pandas.Series`: TEMA values

---

#### `RVWAP(high, low, close, volume, period=20)`

**Rolling Volume-Weighted Average Price** - Price benchmark reflecting volume and price.

**Parameters:**
- `high` (pandas.Series): High prices
- `low` (pandas.Series): Low prices
- `close` (pandas.Series): Close prices
- `volume` (pandas.Series): Trading volume
- `period` (int): Lookback period (default: 20)

**Returns:**
- `pandas.Series`: VWAP values

---

### Visualization

All visualization functions now support two chart types via the `kind` parameter:
- `kind='line'`: Traditional line charts (default)
- `kind='candle'`: Candlestick charts with OHLC data

---

#### `plot_candlestick(data, ticker='Stock')`

**NEW FUNCTION** - Plot standalone candlestick chart.

**Parameters:**
- `data` (pandas.DataFrame): OHLC data with 'Open', 'High', 'Low', 'Close' columns
- `ticker` (str): Stock ticker for title (default: 'Stock')

**Returns:**
- None (displays chart)

**Example:**
```python
plot_candlestick(data, ticker="AAPL")
```

---

#### `plot_macd(macd_line, signal_line, histogram, ticker=None, data=None, kind='line')`

**ENHANCED** - Displays MACD with optional candlestick price chart.

**Parameters:**
- `macd_line` (pandas.Series): MACD line values
- `signal_line` (pandas.Series): Signal line values
- `histogram` (pandas.Series): Histogram values
- `ticker` (str, optional): Stock ticker
- `data` (pandas.DataFrame, optional): OHLC data (required if kind='candle')
- `kind` (str): Chart type - 'line' or 'candle' (default: 'line')

**Example:**
```python
# Line chart (traditional)
plot_macd(macd_line, signal_line, hist, ticker="AAPL")

# Candlestick chart with price action
plot_macd(macd_line, signal_line, hist, ticker="AAPL", data=data, kind='candle')
```

---

#### `plot_bollinger(data=None, adj_close=None, bb_upper=None, bb_mid=None, bb_lower=None, ticker=None, kind='line')`

**ENHANCED** - Visualizes Bollinger Bands with optional candlestick chart.

**Parameters:**
- `data` (pandas.DataFrame, optional): OHLC data (required if kind='candle')
- `adj_close` (pandas.Series): Adjusted close prices (required if kind='line')
- `bb_upper` (pandas.Series): Upper Bollinger Band
- `bb_mid` (pandas.Series): Middle Bollinger Band
- `bb_lower` (pandas.Series): Lower Bollinger Band
- `ticker` (str, optional): Stock ticker
- `kind` (str): Chart type - 'line' or 'candle' (default: 'line')

**Example:**
```python
upper, mid, lower = bb_bands(data['Close'])

# Line chart
plot_bollinger(adj_close=data['Close'], bb_upper=upper, bb_mid=mid, 
               bb_lower=lower, ticker="AAPL")

# Candlestick chart
plot_bollinger(data=data, adj_close=data['Close'], bb_upper=upper, 
               bb_mid=mid, bb_lower=lower, ticker="AAPL", kind='candle')
```

---

#### `plot_rsi(data=None, rsi=None, period=14, lower=30, upper=70, ticker=None, kind='line')`

**ENHANCED** - Displays RSI with optional price candlestick chart.

**Parameters:**
- `data` (pandas.DataFrame, optional): OHLC data (required if kind='candle')
- `rsi` (pandas.Series): RSI values
- `period` (int): RSI period (default: 14)
- `lower` (int): Oversold threshold (default: 30)
- `upper` (int): Overbought threshold (default: 70)
- `ticker` (str, optional): Stock ticker
- `kind` (str): Chart type - 'line' or 'candle' (default: 'line')

**Example:**
```python
rsi = Rsi(data['Close'], period=14)

# Line chart
plot_rsi(rsi=rsi, period=14, ticker="AAPL")

# Candlestick chart with price
plot_rsi(data=data, rsi=rsi, period=14, ticker="AAPL", kind='candle')
```

---

#### `plot_moving_averages(data=None, price=None, sma_val=None, ema_val=None, dema_val=None, tema_val=None, ticker=None, kind='line')`

**ENHANCED** - Compares moving averages with optional candlestick chart.

**Parameters:**
- `data` (pandas.DataFrame, optional): OHLC data (required if kind='candle')
- `price` (pandas.Series, optional): Price series (required if kind='line')
- `sma_val` (pandas.Series, optional): SMA values
- `ema_val` (pandas.Series, optional): EMA values
- `dema_val` (pandas.Series, optional): DEMA values
- `tema_val` (pandas.Series, optional): TEMA values
- `ticker` (str, optional): Stock ticker
- `kind` (str): Chart type - 'line' or 'candle' (default: 'line')

**Example:**
```python
sma = sma(data['Close'], period=20)
ema = ema(data['Close'], period=20)

# Candlestick chart with moving averages
plot_moving_averages(data=data, sma_val=sma, ema_val=ema, 
                     ticker="AAPL", kind='candle')
```

---

## 💡 Usage Examples

### Example 1: Complete Technical Analysis with Candlesticks

```python
from QuantResearch import *

# Fetch data
ticker = "AAPL"
data = fetch_data(ticker, "2023-06-01", "2024-06-01")

# Calculate indicators
rsi = Rsi(data['Close'], period=14)
macd_line, signal_line, histogram = macd(data['Close'])
upper, mid, lower = bb_bands(data['Close'])

# Display all charts with candlesticks
plot_candlestick(data, ticker=ticker)
plot_rsi(data=data, rsi=rsi, ticker=ticker, kind='candle')
plot_macd(macd_line, signal_line, histogram, ticker=ticker, data=data, kind='candle')
plot_bollinger(data=data, adj_close=data['Close'], bb_upper=upper, 
               bb_mid=mid, bb_lower=lower, ticker=ticker, kind='candle')
```

---

### Example 2: Moving Average Strategy with Candlesticks

```python
from QuantResearch import fetch_data, sma, ema, plot_moving_averages

data = fetch_data("MSFT", "2023-01-01", "2024-01-01")

# Calculate moving averages
sma_20 = sma(data['Close'], period=20)
sma_50 = sma(data['Close'], period=50)
ema_12 = ema(data['Close'], period=12)

# Visualize with candlesticks
plot_moving_averages(data=data, sma_val=sma_20, ema_val=ema_12, 
                     ticker="MSFT", kind='candle')

# Detect crossovers
golden_cross = (sma_20 > sma_50) & (sma_20.shift(1) <= sma_50.shift(1))
print(f"Golden Cross signals: {golden_cross.sum()}")
```

---

### Example 3: RSI Strategy with Candlestick Analysis

```python
from QuantResearch import fetch_data, Rsi, plot_rsi

data = fetch_data("GOOGL", "2023-01-01", "2024-01-01")
rsi = Rsi(data['Close'], period=14)

# Generate signals
oversold = rsi < 30
overbought = rsi > 70

print(f"Oversold signals: {oversold.sum()}")
print(f"Overbought signals: {overbought.sum()}")

# Visualize with candlesticks and RSI
plot_rsi(data=data, rsi=rsi, period=14, ticker="GOOGL", kind='candle')
```

---

### Example 4: MACD Crossover with Price Action

```python
from QuantResearch import fetch_data, macd, plot_macd

data = fetch_data("TSLA", "2024-01-01", "2024-11-01")
macd_line, signal_line, hist = macd(data['Close'])

# Detect crossovers
bullish = (macd_line > signal_line) & (macd_line.shift(1) <= signal_line.shift(1))
bearish = (macd_line < signal_line) & (macd_line.shift(1) >= signal_line.shift(1))

print(f"Bullish signals: {bullish.sum()}")
print(f"Bearish signals: {bearish.sum()}")

# Display with candlesticks
plot_macd(macd_line, signal_line, hist, ticker="TSLA", data=data, kind='candle')
```

---

### Example 5: Bollinger Bands Squeeze Detection

```python
from QuantResearch import fetch_data, bb_bands, plot_bollinger

data = fetch_data("NVDA", "2023-01-01", "2024-01-01")
upper, mid, lower = bb_bands(data['Close'], period=20, num_std=2)

# Calculate band width for squeeze detection
band_width = (upper - lower) / mid
squeeze = band_width < band_width.quantile(0.25)

print(f"Squeeze periods detected: {squeeze.sum()}")

# Visualize with candlesticks
plot_bollinger(data=data, adj_close=data['Close'], bb_upper=upper, 
               bb_mid=mid, bb_lower=lower, ticker="NVDA", kind='candle')
```

---

## 📋 Requirements

| Package | Version | Purpose |
|---------|---------|---------|
| Python | >= 3.7 | Runtime environment |
| pandas | >= 1.3.0 | Data manipulation |
| yfinance | >= 0.2.0 | Financial data retrieval |
| matplotlib | >= 3.4.0 | Visualization |
| numpy | >= 1.19.0 | Numerical computations |

---

## 👥 Authors

**QuantResearch** is developed and maintained by:

- **Vinayak Shinde**
  - Email: vinayak.r.shinde.1729@gmail.com
  - GitHub: [@vinayak1729-web](https://github.com/vinayak1729-web)
  - Role: Lead Developer

- **Vishal Mishra**
  - Email: vishal214.mishra@gmail.com
  - GitHub: [@vishalmishra369](https://github.com/vishalmishra369)
  - Role: Co-Developer

---

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](https://opensource.org/licenses/MIT) file for details.

---

## 🤝 Support

For issues, questions, or feature requests:

- **GitHub Issues**: [Report a bug](https://github.com/vinayak1729-web/QuantR/issues)
- **Documentation**: [View on GitHub](https://github.com/vinayak1729-web/QuantR#readme)
- **Email Support**: Contact the authors

---

## ⚠️ Disclaimer

**Important**: QuantResearch is provided for **educational and research purposes only**. It is **not intended as financial advice**.

- Always consult with a financial advisor before making investment decisions
- Past performance does not guarantee future results
- Technical indicators are tools; they should not be used as sole decision-making factors
- Use proper risk management in all trading activities
- Test strategies thoroughly before live trading

---

## 📊 What's New in Version 2.0

### Major Enhancements
- ✅ **Candlestick Chart Support**: All major visualization functions now support candlestick charts
- ✅ **New Function**: `plot_candlestick()` for standalone candlestick visualization
- ✅ **Enhanced Visualizations**: Dual-pane charts showing price action with indicators
- ✅ **Improved Code Quality**: Refactored visualization module with helper functions
- ✅ **Better Error Handling**: Robust error handling in all plotting functions
- ✅ **Flexible API**: Support for both line and candlestick charts via `kind` parameter

### Chart Type Options
All enhanced functions support:
- `kind='line'`: Traditional line charts (backward compatible)
- `kind='candle'`: New candlestick charts with OHLC data

---

## 🙏 Acknowledgments

- **Yahoo Finance** for providing historical market data
- **pandas** and **matplotlib** communities for excellent libraries
- All contributors and users who provide feedback

---

## 📞 Contact

For more information, visit:
- **Repository**: https://github.com/vinayak1729-web/QuantR
- **PyPI Package**: https://pypi.org/project/QuantResearch/

---

**Made with ❤️ by Vinayak Shinde and Vishal Mishra**