Tutorial: Using the NBA Rebuild Analyzer

Overview

This tutorial walks through how to use the nba_rebuilds package and its Streamlit applications to: - Fetch NBA standings data - Analyze multi-season rebuilds trends - Predict how long teams may take to return to the playoffs

No prior knowledge of the internal codebase is required.

Installation

Clone the repository and install dependencies:

git clone https://github.com/mitchster21/nba_rebuild_project.git
cd nba_rebuild_project
pip install -e .
uv sync

Fetch NBA Standings Data

Standings data can be fetched using the public NBA API or loaded from pre-downloaded CSV files.

To fetch manually:

uv run python -m nba_rebuilds.fetch_data --start 2010 --end 2023 --type standings

This command downloads season standings and saves CSV files under:

src/nba_rebuilds/data/

Launch Streamlit App

Run the entire NBA Analytics Suite (both Rebuild Analyzer and Playoff Predictor) with one command:

uv run streamlit run streamlit_app.py

Rebuild Analyzer (Streamlit App)

  • Select a range of NBA seasons.
  • Preview combined multi-season standings data.
  • Aggregate performance metrics by team (Team Summary) or view raw season data (Raw Season Data).
  • Click Compute Rebuilds to see detected rebuilds for the selected years.
  • Tip: Fetching via the NBA API is slow and sometimes restricted; using pre-fetched CSV files in src/nba_rebuilds/data/ is recommended.

Playoff Predictor (Streamlit App)

  • Estimate how many years a team may take to return to the playoffs based on roster continuity and player features.
  • Generate predictions for individual teams or run batch predictions.
  • View feature importance to understand model behavior.
  • Adjust toggles and filters to experiment with different team indicators.