stockcharts 0.5.0

NASDAQ stock screener using Heiken Ashi candles and RSI divergence for trend reversal detection with volume and price filtering

StockCharts

A Python library for screening NASDAQ stocks using Heiken Ashi candles and RSI divergence to detect trend reversals with volume and price filtering.

Features

� NASDAQ Screener

• Full NASDAQ Coverage: Automatically fetches all 5,120+ NASDAQ tickers from official FTP source
• Heiken Ashi Analysis: Detects red-to-green and green-to-red candle color changes
• Volume Filtering: Filter by average daily volume to focus on liquid, tradeable stocks
• Flexible Timeframes: Support for intraday (1m-1h), daily, weekly, and monthly charts
• Custom Date Ranges: Screen historical data with specific start/end dates
• CSV Export: Save screening results for further analysis

📊 Chart Generation

• Heiken Ashi Charts: Generate candlestick charts from screening results
• Price/RSI Divergence Charts: Visualize price action with RSI indicator and marked divergences
• Support for multiple timeframes: 1m, 5m, 15m, 1h, 1d, 1wk, 1mo
• High-quality PNG output for technical analysis
• Automatic divergence detection and highlighting on charts

🎯 Trading Styles Supported

• Day Trading: 1m-1h periods, high volume (2M+ shares/day)
• Swing Trading: Daily charts, moderate volume (500K-1M shares/day)
• Position Trading: Weekly/monthly charts, lower volume acceptable

Installation

From PyPI

pip install stockcharts

From Source

# Clone the repository
git clone https://github.com/paulboys/HeikinAshi.git
cd HeikinAshi

# Create conda environment
conda create -n stockcharts python=3.12 -y
conda activate stockcharts

# Install in editable mode
pip install -e .

Quick Start

After installation, you'll have four command-line tools available:

1. stockcharts-screen - Heiken Ashi Color Screening

2. stockcharts-plot - Heiken Ashi Chart Generation

3. stockcharts-rsi-divergence - RSI Divergence Screening

4. stockcharts-plot-divergence - Price/RSI Divergence Charts

Usage

1. Screen for Trend Reversals

Find green reversals (red→green) for swing trading:

stockcharts-screen --color green --changed-only --min-volume 500000

Day trading setup (1-hour charts with high volume):

stockcharts-screen --color green --period 1h --lookback 1mo --min-volume 2000000 --changed-only

Weekly analysis over 6 months:

stockcharts-screen --color green --period 1wk --lookback 6mo --changed-only

Screen specific date range:

stockcharts-screen --color red --start 2024-01-01 --end 2024-12-31

2. Generate Charts from Results

Plot all screened stocks:

stockcharts-plot

Plot from specific CSV:

stockcharts-plot --input results/green_reversals.csv --output-dir my_charts/

3. Screen for RSI Divergences

Find bullish divergences (potential buy signals):

stockcharts-rsi-divergence --type bullish --min-price 10

Find bearish divergences (potential sell signals):

stockcharts-rsi-divergence --type bearish --min-price 10 --max-price 100

Custom RSI parameters:

stockcharts-rsi-divergence --rsi-period 21 --period 6mo

4. Generate Divergence Charts

Plot divergences from screener results:

stockcharts-plot-divergence

Documentation

Comprehensive, consolidated documentation lives in the docs/ directory:

Topic	File
Project Overview & Architecture	docs/overview.md
Heiken Ashi Screener Guide	docs/screener.md
RSI Divergence Screener	docs/rsi_divergence.md
Parameters & Configuration	docs/parameters.md
Volume Filtering	docs/volume.md
Trading Style Guidance	docs/trading_styles.md
Quick Reference Commands	docs/quick_reference.md
Roadmap & Next Steps	docs/roadmap.md
Legacy Mapping	docs/legacy.md

All documentation is consolidated under docs/. Legacy root markdown files have been removed.

See also: CHANGELOG.md for release history.

Hosted Documentation

An interactive, searchable documentation site is published via MkDocs + GitHub Pages.

Local Preview

pip install -r requirements-docs.txt
mkdocs serve
# Visit http://127.0.0.1:8000

Manual Build

mkdocs build --strict
# Output generated in ./site/

Deployment (CI Automated)

Docs are automatically built and deployed when you push changes to docs/, mkdocs.yml, or requirements-docs.txt on main.

Workflow file: .github/workflows/docs.yml using peaceiris/actions-gh-pages.

To trigger manually:

gh workflow run Deploy Documentation

Site URL

https://paulboys.github.io/HeikinAshi/

If the page is not yet enabled, activate GitHub Pages in repository settings pointing to the gh-pages branch.

Custom analysis with longer lookback:

stockcharts-plot-divergence --input results/rsi_all.csv --lookback 6mo --output-dir charts/analysis/

Limit number of charts and customize RSI:

stockcharts-plot-divergence --max-plots 20 --rsi-period 21

Command-Line Options

stockcharts-screen (Heiken Ashi Screening)

• --color: Filter by red or green candles (default: green)
• --period: Aggregation period: 1m, 5m, 15m, 1h, 1d, 1wk, 1mo (default: 1d)
• --lookback: Historical window: 1d, 5d, 1mo, 3mo, 6mo, 1y, 2y, max (default: 3mo)
• --start, --end: Custom date range in YYYY-MM-DD format
• --changed-only: Only show stocks where color changed in latest candle
• --min-volume: Minimum average daily volume (e.g., 500000)
• --min-price: Minimum stock price (e.g., 5.0 or 10.0)
• --output: CSV output path (default: results/nasdaq_screen.csv)
• --debug: Show detailed error messages

stockcharts-plot (Chart Generation)

• --input: Input CSV file from screener
• --output-dir: Directory for chart images (default: charts/)
• --period: Chart timeframe (default: 1d)
• --lookback: Historical data window (default: 3mo)

stockcharts-rsi-divergence (RSI Divergence Screening)

• --type: Divergence type: bullish, bearish, or all (default: all)
• --period: Data lookback: 1mo, 3mo, 6mo, 1y, etc. (default: 3mo)
• --rsi-period: RSI calculation period (default: 14)
• --min-price: Minimum stock price filter
• --max-price: Maximum stock price filter
• --swing-window: Window for swing point detection (default: 5)
• --lookback: Bars to analyze for divergence (default: 60)
• --output: CSV output path (default: results/rsi_divergence.csv)

stockcharts-plot-divergence (Divergence Chart Generation)

• --input: Input CSV file from RSI divergence screener
• --output-dir: Directory for chart images (default: charts/divergence/)
• --interval: Data aggregation interval: 1d, 1wk, 1mo (default: 1d)
• --lookback: Historical data window (default: 3mo)
• --rsi-period: RSI calculation period (default: 14)
• --swing-window: Window for swing point detection (default: 5)
• --divergence-lookback: Bars to look back for divergence (default: 60)
• --max-plots: Maximum number of charts to generate (default: all)

See QUICK_REFERENCE.md for parameter details.

Library API

You can also use StockCharts programmatically in your Python code:

from stockcharts.screener.screener import screen_nasdaq
from stockcharts.screener.rsi_divergence import screen_rsi_divergence
from stockcharts.screener.nasdaq import get_nasdaq_tickers
from stockcharts.data.fetch import fetch_ohlc
from stockcharts.charts.heiken_ashi import heiken_ashi
from stockcharts.indicators.rsi import compute_rsi
from stockcharts.indicators.divergence import detect_divergence

# Screen for green reversals with volume filter
results = screen_nasdaq(
    color='green',
    period='1d',
    lookback='3mo',
    changed_only=True,
    min_volume=500000
)

# Screen for RSI bullish divergences
rsi_results = screen_rsi_divergence(
    divergence_type='bullish',
    min_price=10.0,
    period='6mo'
)

# Get all NASDAQ tickers
tickers = get_nasdaq_tickers()
print(f"Found {len(tickers)} NASDAQ tickers")

# Fetch data and compute Heiken Ashi
data = fetch_ohlc('AAPL', period='1d', lookback='3mo')
ha_data = heiken_ashi(data)

# Calculate RSI and detect divergences
data['RSI'] = compute_rsi(data['Close'], period=14)
divergence = detect_divergence(data)

Project Structure

StockCharts/
├── src/stockcharts/          # Main package
│   ├── cli.py                # Command-line entry points
│   ├── charts/               # Heiken Ashi computation
│   ├── data/                 # Data fetching (yfinance)
│   ├── indicators/           # Technical indicators (RSI, divergence)
│   └── screener/             # NASDAQ screening logic
├── scripts/                  # Legacy CLI scripts
├── tests/                    # Unit tests
├── requirements.txt          # Dependencies
└── pyproject.toml            # Package configuration

Requirements

• Python 3.9+
• yfinance >= 0.2.38
• pandas >= 2.0.0
• matplotlib >= 3.7.0
• numpy >= 1.24.0

Output Examples

Screener CSV Output

ticker,color,ha_open,ha_close,last_date,period,color_changed,avg_volume
AAPL,green,225.34,227.89,2024-01-15,1d,True,58234567
MSFT,green,402.15,405.67,2024-01-15,1d,True,25678901
NVDA,green,520.88,528.45,2024-01-15,1d,True,45123890

Chart Output

Charts include:

• Green candles for bullish moves (HA_Close >= HA_Open)
• Red candles for bearish moves (HA_Close < HA_Open)
• Full wicks showing HA_High and HA_Low
• Date labels on x-axis
• Automatic scaling based on price range

Documentation

• LIBRARY_GUIDE.md: Comprehensive usage guide with examples
• RSI_DIVERGENCE_GUIDE.md: RSI divergence screening guide
• QUICK_REFERENCE.md: Parameter quick reference
• VOLUME_FILTERING_GUIDE.md: Volume filtering strategies
• TRADING_STYLE_GUIDE.md: Recommendations by trading style
• DISTRIBUTION.md: Build and distribution guide (for maintainers)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Roadmap

• Publish to PyPI
• Add unit tests and CI/CD
• RSI divergence detection (bullish/bearish price vs RSI divergences)
• Additional technical indicators (MACD, Bollinger Bands, Stochastic)
• Multi-ticker comparison charts
• Backtesting framework
• Real-time data integration (requires API like Alpaca/Polygon - yfinance is EOD only)
• Alert/notification system

License

MIT License - see LICENSE file for details.

Disclaimer

This project is provided for educational and informational purposes only and does not constitute financial, investment, trading, legal, tax, or other professional advice. Outputs (including screens, indicators, charts, divergences) may contain errors, omissions, delays, or false signals. Trading and investing involve risk of loss, including principal. Past performance or detected patterns do not guarantee future results. Validate all insights independently before acting.

By using this software you accept full responsibility for any decisions and agree to indemnify the author against claims arising from its use. For personalized advice consult a licensed financial professional. See DISCLAIMER.md for full details.

Acknowledgments

• yfinance: Yahoo Finance data API
• pandas: Data manipulation and analysis
• matplotlib: Chart generation
• NASDAQ: Official ticker data via FTP

Support

If you encounter any issues or have questions:

• Open an issue: https://github.com/paulboys/HeikinAshi/issues
• Check the documentation in this repository

---

Happy Trading! 📈