NFL Projection Analysis

A data analysis toolkit that evaluates NFL player projections against actual performance. This project ingests data from various sources, performs statistical regression analysis to determine optimal weighting formulas, and generates detailed PDF reports and CSV datasets.

Features

• Data Ingestion: Fetches projection data from community repositories (e.g., hvpkod/NFL-Data) and actual performance statistics via nflreadpy.
• Statistical Analysis: Uses linear regression (scikit-learn) to analyze the correlation between projected and actual points.
• Visualizations: Generates scatter plots and correlation charts using seaborn and matplotlib to visualize performance trends by position (QB, RB, WR, TE).
• Automated Reporting: Produces a comprehensive PDF report (Detailed_NFL_Analysis.pdf) summarizing findings, including methodology, statistical insights, and embedded visualizations.
• Data Export: Outputs processed data to detailed_nfl_data.csv for further external analysis.

Prerequisites

• Python 3.8+
• Internet connection (for fetching data)

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/nfl-analysis.git
   cd nfl-analysis

2. Create and activate a virtual environment (optional but recommended):

   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install the required dependencies:

   pip install pandas numpy matplotlib seaborn scikit-learn fpdf nflreadpy

Configuration

The analysis year is currently hardcoded in nfl_detailed_analysis.py. To change the season being analyzed:

1. Open nfl_detailed_analysis.py.
2. Locate the YEAR variable near the top of the file:

   # --- Configuration ---
   YEAR = 2025

3. Update it to the desired season (e.g., YEAR = 2024).

Usage

Run the main analysis script to generate the report and data files:

python nfl_detailed_analysis.py

Utility Scripts

• check_pos.py: A quick utility to verify available player positions in the nflreadpy dataset for the current/target season.
• nfl_prediction_analysis.py: Legacy script for earlier versions of the analysis logic.

Output

After running the main script, the following files will be generated in the project root:

• Detailed_NFL_Analysis.pdf: A multi-page report containing:
  • Executive Summary
  • Methodology
  • Position-specific analysis (QB, RB, WR, TE)
  • Visualization charts (Correlation matrices, Scatter plots)
• detailed_nfl_data.csv: The raw dataset used for the analysis, containing merged projection and actual performance data.
• *.png: Temporary image files generated during the execution (cleaned up or overwritten in subsequent runs).

Project Structure

.
├── nfl_detailed_analysis.py    # Main application entry point
├── AGENTS.md                   # Guidelines for AI agents and contributors
├── check_pos.py                # Utility for data validation
├── Detailed_NFL_Analysis.pdf   # Generated Report (Output)
├── detailed_nfl_data.csv       # Generated Data (Output)
└── ...

Contributing

See AGENTS.md for detailed guidelines on code style, conventions, and operational workflows for this project.

License

MIT (or appropriate license)