The SharpModels NFL series focuses on building reproducible sports models in Python, from a simple Elo rating system through to probability evaluation. The articles assume a working Python environment so they can concentrate on modelling decisions rather than software installation. This page provides the minimal setup needed to run every example in the series.
Who This Page Is For
This page is a lightweight setup guide for readers who want to run the SharpModels code examples locally.
The main SharpModels articles assume a working Python environment and focus on modelling logic rather than environment setup. If you already use Python for data analysis, you can safely skip this page.
Python Version
All examples in this series are written for standard CPython. They have been tested using Python 3.10+, although they should also run on Python 3.9 and later without modification.
- Minimum version: Python 3.9
- Recommended: Python 3.10+
If you are unsure which version you are running:
python --version
Required Libraries
SharpModels code examples rely on a lightweight scientific Python stack:
- polars — fast DataFrame operations
- matplotlib — plotting and visualisation
Install the dependencies with:
pip install polars matplotlib
No additional frameworks or machine learning libraries are required for the NFL Elo modelling series.
Data Files
The NFL modelling articles use a clean historical NFL results dataset containing one row per game. The data is provided in two formats:
- nfl_games_data.csv
- nfl_games_data.pq (Parquet)
Either format can be used. Parquet is recommended for faster loading and lower memory usage.
Most articles assume the data files live in the same directory as the Python script being run. If your folder structure differs, simply adjust the file paths used in the code.
Typical Project Structure
A simple local setup might look like:
sharpmodels/
├── nfl/
│ ├── data/
│ │ ├── nfl_games_data.csv
│ │ └── nfl_games_data.pq
│ ├── code/
│ │ ├── article1_clean_elo.py
│ │ ├── article2_elo_charts.py
│ │ └── elo_charts/
│ └── outputs/
└── README.md
This structure is only an example. The examples simply assume that the file paths used inside each script point to the correct data files.
Running the Examples
All scripts are designed to be run directly:
python article1_clean_elo.py
Outputs such as CSV files, Parquet files, or PNG charts will be written to the directories specified in each script.
The articles are designed to be followed sequentially. Later examples often build on outputs generated in earlier articles.
Assumptions and Scope
Throughout this series we assume the reader is already comfortable with basic Python syntax and running Python scripts from the command line. The focus is on sports modelling methodology rather than Python programming.
SharpModels articles deliberately avoid:
- Python language tutorials
- IDE configuration
- Virtual environment setup
- Operating-system specific installation guides
This keeps the articles focused on modelling concepts, implementation, diagnostics, and interpretation.
If Something Doesn't Run
If a script fails, check the following:
- Your Python version meets the minimum requirement.
- The required libraries are installed.
- The data file paths match your local setup.
- You are running the script from the expected working directory.
All examples are intentionally self-contained, with each article introducing one modelling concept at a time to keep the code easy to understand and debug.
Next Steps
Once your environment is ready, continue to Building A Clean NFL Elo Rating Model From Results, where we construct a complete Elo rating system from historical NFL results and establish the foundation for the rest of the SharpModels NFL series.
Prefer to Explore the Ratings?
The articles in this series explain the modelling techniques used to build reproducible sports rating systems in Python. They are designed to teach the underlying methodology rather than replicate every detail of our production models.
If you're more interested in exploring our current ratings than building the models yourself, you can browse our latest ratings here:
Our live ratings are built on the same core modelling principles introduced throughout the SharpModels series, while incorporating ongoing research, parameter optimisation, sport-specific refinements and continuous updates as new data becomes available.