Imported from jgx0/nfl-data-analysis (AGENTS.md). Install upstream with npx skills add jgx0/nfl-data-analysis. Copyright stays with the author.

Agent Guidelines for NFL Projection Analysis Project

This document outlines the standards, workflows, and conventions for agents working on this repository. It is designed to ensure consistency and reliability across all automated and manual contributions.

1. Project Overview

This project analyzes NFL player projections against actual performance to determine optimal statistical weighting formulas. It ingests data from multiple sources, performs statistical regression, and outputs detailed PDF reports and CSV datasets.

• Primary Script: nfl_detailed_analysis.py
• Legacy/Alternative Script: nfl_prediction_analysis.py
• Data Sources:
  • hvpkod/NFL-Data (GitHub CSVs for projections)
  • nflreadpy (Official nflverse actuals)
• Outputs:
  • Detailed_NFL_Analysis.pdf (Multi-page report)
  • detailed_nfl_data.csv (Raw processed data)

2. Environment & Commands

Dependencies

The project relies on a specific set of Python data science libraries. Ensure these are installed in your virtual environment:

• pandas: Data manipulation and merging
• numpy: Numerical operations
• matplotlib: Core plotting library
• seaborn: Statistical data visualization
• scikit-learn: Linear regression models
• fpdf: PDF generation
• nflreadpy: NFL data fetching

Build & Run Instructions

There is no compilation step as this is a Python project.

1. Setup Environment:

python3 -m venv venv
source venv/bin/activate
pip install pandas numpy matplotlib seaborn scikit-learn fpdf nflreadpy

2. Run the Main Analysis:

# This generates the PDF and CSV outputs
python nfl_detailed_analysis.py

3. Run Verification/Tests: Currently, the project uses implicit integration testing via script execution. To verify functionality after changes:

# Run the script and check for exit code 0
python nfl_detailed_analysis.py && echo "Success" || echo "Failure"

# Check if output files were generated (MacOS/Linux)
ls -l Detailed_NFL_Analysis.pdf detailed_nfl_data.csv

4. Running Specific Checks: If you need to verify specific components (e.g., data fetching):

• Use check_pos.py for quick data validation.
• You can create temporary scripts to test individual functions like get_projections(2025).

3. Code Style & Conventions

Adhere to these guidelines to maintain codebase consistency.

Formatting

• Indentation: 4 spaces (Standard Python).
• Line Length: Soft limit of 100 characters. Long strings (SQL, URLs, multiline text) are exceptions.
• String Quotes: Use double quotes " for strings and f-strings. Use single quotes ' only when nesting requires it or for dictionary keys if consistent.
• Blank Lines: Use 2 blank lines between top-level functions/classes.

Imports

Organize imports in the following groups:

1. Standard Library: os, sys, json
2. Data Science Stack: pandas, numpy, sklearn
3. Visualization: matplotlib, seaborn
4. Utilities/Domain: fpdf, nflreadpy

Example:

import os
import pandas as pd
import numpy as np
import matplotlib.pyplot as plt
import seaborn as sns
from sklearn.linear_model import LinearRegression
from fpdf import FPDF
import nflreadpy as nfl

Naming Conventions

• Variables & Functions: snake_case (e.g., get_actuals, subset_df, opt_corr).
• Classes: PascalCase (e.g., PDF).
• Constants: UPPER_CASE (e.g., YEAR, HVPKOD_BASE_URL).
• DataFrames: Use descriptive suffixes like _df, or clear names like projections, actuals.
• Columns: Keep raw CSV column names until normalized. Normalized names should be snake_case (e.g., player_name_clean, projected_points).

Type Hinting

While legacy code may not have full typing, new code must use type hints.

def analyze_position(df: pd.DataFrame, pos: str, pdf: FPDF) -> None:
    """Analyzes a specific position and adds pages to the PDF."""
    ...

Error Handling

• Network Calls: All external data fetching (URLs, APIs) must be wrapped in try...except blocks.
• Failures: If a specific week or position fails to load, log the error (print) and continue rather than crashing the entire script.
• Empty Data: Always check if df.empty: before proceeding with analysis.

Data Handling

• Pandas Best Practices:
  • Avoid iterating over rows (iterrows) for calculations. Use vectorization.
  • Example: df['diff'] = df['actual'] - df['proj'] instead of a loop.
• Merging:
  • Always normalize join keys (lowercase, strip whitespace, remove suffixes) before merging.
  • Explicitly define on=['player_name_clean', 'Week'] and how='inner'.
• Deduplication:
  • Handle duplicate projections by sorting by score/date and keeping the top/latest entry.

Visualization Rules

• Libraries: Use seaborn for complex statistical plots and matplotlib for basic adjustments.
• Style:
  • Always set plt.figure(figsize=(...)) before plotting.
  • Always add titles and axis labels.
  • Use plt.tight_layout() to prevent clipping.
  • Close plots explicitly with plt.close() to free memory.
• PDF Integration: Save charts as temporary PNGs, insert into PDF, and overwrite/delete as needed.

4. Operational Guidelines

Workflow for Agents

1. Plan: Understand the request (e.g., "add a new formula").
2. Check Data: Verify if the necessary columns exist in the raw CSVs or nflreadpy output.
3. Implement: Modify apply_formulas or analyze_position.
4. Visualize: Create a new chart if relevant.
5. Report: Update the PDF generation code to include the new finding.
6. Verify: Run the script and inspect the generated PDF for layout issues (overlapping text, missing images).

Common Pitfalls

• Character Encoding: fpdf uses latin-1 by default. Avoid special characters like em-dashes (—) or smart quotes. Use standard ASCII replacements.
• PDF Page Breaks: Manually check pdf.get_y() before adding large elements (tables/images) to avoid awkward cuts. Add pdf.add_page() if y > 230 (approx).

5. Directory Structure

.
├── nfl_detailed_analysis.py    # MAIN SCRIPT
├── AGENTS.md                   # This file
├── Detailed_NFL_Analysis.pdf   # Output Report
├── detailed_nfl_data.csv       # Output Data
├── *.png                       # Temporary charts (generated during runtime)
└── venv/                       # Virtual Environment