Metadata-Version: 2.4
Name: stock-market-screener
Version: 0.1.2
Summary: A data-driven stock screener that analyzes Dow 30 stocks using technical indicators
Author-email: Sophie Zhang <sophieszhang.ssz@gmail.com>
License: MIT
Project-URL: Repository, https://github.com/Sophie-S-Z/Stonks.git
Project-URL: Documentation, https://github.com/Sophie-S-Z/Stonks/blob/main/README.md
Keywords: stock-screener,technical-analysis,trading,finance
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=1.3.0
Requires-Dist: numpy>=1.21.0
Requires-Dist: yfinance>=0.2.0
Requires-Dist: TA-Lib>=0.4.24
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: seaborn>=0.11.0
Dynamic: license-file

# Stock Market Screener

A data-driven stock screener that analyzes Dow 30 stocks using technical indicators and machine learning-inspired scoring algorithms to identify promising investment opportunities.

## Overview

This project evaluates 30 major stocks from the Dow Jones Industrial Average based on multiple technical indicators and combines them into a comprehensive scoring system. The screener uses recent market data (from 2025-01-01 onwards) to calculate momentum, trend, and volume signals.

## Quick Start

If you're in a hurry:

1. **Clone/download** the repo
2. **Create virtual environment**: `python -m venv .venv && .venv\Scripts\activate` (Windows) or `python3 -m venv .venv && source .venv/bin/activate` (Mac/Linux)
3. **Install packages**: `pip install -r requirements.txt`
4. **Run screener**: `python stock_screener.py`

That's it! Results will display in your terminal and be saved as CSV + PNG charts.

## Features

- **Multi-Factor Analysis**: Combines three complementary scoring metrics:
  - **MA50 Score**: Moving average convergence/divergence analysis using 50-day and 200-day moving averages
  - **RSI Momentum Score**: Relative Strength Index momentum detection to identify overbought/oversold conditions
  - **Volume Score**: Volume analysis combined with price trend confirmation

- **Normalized Scoring System**: All metrics are normalized between -1 and +1 for easy comparison
- **Final Composite Score**: Averaging of all three components for a holistic view
- **Visual Analytics**: 
  - Bar chart visualization of final scores by ticker
  - Color-coded heatmap for quick pattern recognition (red = negative, green = positive)

## Data Source

- **API**: Yahoo Finance (via yfinance)
- **Stocks**: Dow 30 constituents (30 large-cap US stocks)
- **Timeframe**: 1-year rolling analysis (Jan 2025 - Jan 2026)
- **Frequency**: Daily OHLCV data with auto-adjustment for splits and dividends

## Technical Stack

- **Data Analysis**: Pandas, NumPy
- **Technical Indicators**: TA-Lib (TALib)
- **Visualization**: Matplotlib, Seaborn
- **Finance Data**: yfinance

## Installation

### 1. Clone or Download the Repository
Download this project or clone it from the repository link.

### 2. Create a Virtual Environment (Recommended)

**On Windows:**
```bash
python -m venv .venv
.venv\Scripts\activate
```

**On macOS/Linux:**
```bash
python3 -m venv .venv
source .venv/bin/activate
```

### 3. Install Dependencies

```bash
pip install -r requirements.txt
```

> **Note on TA-Lib**: If you encounter issues installing TA-Lib, refer to the [TA-Lib installation guide](https://github.com/mrjbq7/ta-lib#installation). It requires a compiled C library.

## Usage

You can run the stock screener in two ways:

### Option 1: Run the Python Script (Easiest)

```bash
python stock_screener.py
```

This will:
- Download historical data for all 30 Dow stocks
- Calculate scores for all stocks
- Display results in the terminal
- Generate and display visualizations
- Save results to a timestamped CSV file
- Save chart images (bar_chart.png and heatmap.png)

### Option 2: Run the Jupyter Notebook

```bash
jupyter notebook "Stock Market Screener.ipynb"
```

Then run all cells in order. The notebook provides the same functionality with interactive exploration capabilities.

## Scoring Methodology

### MA50 Score
Combines three factors:
- **Distance from MA50** (50%): How far the current price is from its 50-day moving average
- **MA50 Slope** (30%): The direction and strength of recent moving average trend
- **Trend Regime** (20%): Whether price is above/below the 200-day moving average

### RSI Momentum Score
Measures the rate of change of RSI:
- Normalizes recent RSI changes by rolling volatility
- Positive values = RSI strengthening (bullish momentum)
- Negative values = RSI weakening (bearish momentum)

### Volume Score
Combines volume and price action:
- **Volume Component** (50%): Current volume relative to 20-day average
- **Trend Confirmation** (50%): Whether volume increases on up or down days

## Output

The screener produces three types of output:

### 1. Terminal Output
- Displays all stock scores in a formatted table
- Shows progress as data is downloaded and calculated

### 2. CSV Report
- Automatically saved as `stock_screener_results_YYYYMMDD_HHMMSS.csv`
- Contains all individual scores and final composite scores
- Can be imported into Excel or other tools for further analysis

### 3. Visualizations
- **Bar Chart** (`stock_screener_bar_chart.png`): Final scores ranked by ticker for easy comparison
- **Heatmap** (`stock_screener_heatmap.png`): Color-coded grid view showing all stocks and their scores at a glance

## Output Files

After running the screener, you'll find these files in the project directory:

```
stock_screener_results_20260107_123456.csv      # Results data (timestamp varies)
stock_screener_bar_chart.png                     # Bar chart visualization
stock_screener_heatmap.png                       # Heatmap visualization
```

## Customization

You can easily customize the screener by editing `stock_screener.py`:

```python
# Change the date range
START_DATE = '2025-01-01'
END_DATE = '2026-01-07'

# Modify the stock list
TICKERS = {"AAPL", "MSFT", "GOOGL", ...}

# Adjust scoring weights in the scoring functions
# For example, in ma50_score():
score = 0.5 * dist_score + 0.3 * slope_score + 0.2 * regime
```

## Troubleshooting

**Q: I get a TA-Lib installation error**
- A: TA-Lib requires a compiled C library. See [TA-Lib GitHub](https://github.com/mrjbq7/ta-lib) for platform-specific installation instructions.

**Q: yfinance download is slow or fails**
- A: This can happen during peak hours. The script includes multi-threading, but you can increase retry attempts by modifying the `download_data()` function.

**Q: I get "module not found" errors**
- A: Make sure you activated your virtual environment and ran `pip install -r requirements.txt`.

**Q: Charts don't display**
- A: If running on a headless server, comment out `plt.show()` lines in the script. Charts are still saved as PNG files.

## Project Files

```
Stock Market Screener/
├── Stock Market Screener.ipynb    # Main interactive notebook
├── stock_screener.py              # Standalone Python script
├── requirements.txt               # Python dependencies
├── README.md                      # This file
├── .gitignore                     # Git ignore rules
└── stock_screener_results_*.csv   # Generated reports (after running)
```

## Important Notes

- **Score Range**: All scores range from -1 (bearish) to +1 (bullish)
- **Final Score Calculation**: The final_score is the arithmetic mean of the three component scores
- **Interpretation**: Higher scores suggest better momentum and trend alignment
- **Disclaimer**: This is a technical analysis tool and should not be used as the sole basis for investment decisions
- **Data Quality**: Historical data is auto-adjusted for stock splits and dividends
- **Real-Time Usage**: This screener uses daily data; for intraday trading, modify the data frequency in `stock_screener.py`

## Future Enhancements

- Additional indicators (Bollinger Bands, MACD, Stochastic Oscillator)
- Sector-based filtering and comparison
- Fully customizable date ranges via command-line arguments
- Integration with broader market indices
- Machine learning-based dynamic scoring weights
- Real-time alerts for significant score changes
- Web-based dashboard for interactive exploration
- Integration with brokerage APIs

## Contributing

Found a bug or have an improvement? Feel free to fork and submit a pull request.

## Author

Created as part of quantitative stock analysis research.

## License

Personal use project. Feel free to modify and share for personal investment research.
