Fantasy Basketball Matchup Luck Calculator

This tool analyzes matchup luck in ESPN Fantasy Basketball leagues by comparing actual performance against expected performance across all categories.

If a team has been really lucky with matchups they might not be as strong as their record indicates, and vice versa. For example if two really strong teams matchup and one team wins each stat category by a small amount, the loser would likely have beat any other team but does not get credit for it.

Overview

The matchup luck calculator:

• Calculates how each team would have performed against every other team each week
• Shows which teams have been lucky (performing better in their matchup that against the field) or unlucky (performing worse in their matchup than against the field)
• Identifies the most lucky and unlucky single-week performance

Installation

1. Clone this repository
2. Install required packages:

pip install requests tabulate colorama

Usage

Run the script and it will ask you for the league ID and season:

python matchup_luck.py

How It Works

1. Data Collection

   • Fetches league data from ESPN's API
   • Caches responses locally to avoid repeated API calls
   • Data is saved in data/[date]_[leagueid]_[season]_scoreboard.json

2. Luck Calculation

   • For each week, compares each team's category results against their expected results
   • Expected results are calculated by checking stats against all teams
   • Luck score = Actual Results - Expected Results
   • Positive scores indicate lucky performance (better than expected)
   • Negative scores indicate unlucky performance (worse than expected)

3. Output

   • Displays a table showing luck scores by team and week
   • Teams are sorted by season-long luck (most lucky to most unlucky)
   • Highlights the single most unlucky performance of the season
   • Saves the output to output/[date]_[leagueid]_[season]_luck.txt and output/[date]_[leagueid]_[season]_luck.html

Example Output

Team Luck (Actual - Expected) by Week: Positive values = Lucky (performed better than expected) Negative values = Unlucky (performed worse than expected)

Team	Season	Week 1	Week 2	Week 3	Week 4	Week 5	Week 6	Week 7	Week 8	Week 9	Week 10	Week 11	Week 12	Week 13	Week 14	Week 15
NYM	0.096	-0.024	0.367	-0.194	-0.209	0.291	0.458	0.082	0.336	-0.142	0.191	-0.024	0.406	-0.142	0.136	-0.094
RR	0.057	0.264	0.033	0.000	0.167	0.042	0.161	-0.173	-0.012	0.018	-0.230	0.164	0.215	0.197	-0.148	0.158
BHM	0.054	-0.109	0.018	0.276	0.152	0.267	-0.309	-0.194	-0.027	0.048	0.130	0.073	0.073	0.288	0.336	-0.218
BS	0.039	0.167	0.133	-0.042	-0.067	0.155	-0.024	0.036	-0.061	-0.006	-0.318	0.058	-0.024	0.285	-0.048	0.345
AS	0.032	-0.170	-0.188	0.167	0.033	0.006	0.242	0.100	0.000	0.506	0.112	-0.073	-0.003	0.070	-0.279	-0.039
WWB	0.015	-0.082	0.279	-0.258	0.206	-0.309	-0.318	-0.061	0.209	-0.109	-0.197	0.164	0.170	0.167	0.255	0.115
C-FL	0.014	0.327	-0.145	0.133	0.282	-0.115	-0.345	0.367	-0.227	-0.109	0.245	0.276	-0.133	-0.048	-0.452	0.155
SLS	0.012	0.024	-0.039	0.227	-0.021	0.042	0.088	0.227	0.100	-0.094	0.121	-0.158	-0.182	0.064	-0.088	-0.130
AB	-0.004	-0.200	-0.091	-0.233	0.170	0.373	-0.318	-0.415	-0.109	0.076	-0.003	0.112	0.194	0.052	-0.006	0.333
MM	-0.014	0.158	0.227	-0.215	-0.121	-0.173	0.106	-0.073	-0.261	-0.006	-0.106	0.176	0.094	-0.091	0.179	-0.109
MSS	-0.020	-0.167	-0.218	-0.109	0.130	-0.376	0.133	0.006	-0.412	-0.164	-0.182	0.436	0.012	0.197	0.112	0.297
CTP	-0.024	-0.112	-0.091	-0.085	-0.064	-0.021	0.285	0.239	-0.115	-0.015	0.164	-0.003	-0.027	-0.136	-0.258	-0.124
HKBC	-0.044	-0.064	-0.297	0.252	-0.027	0.152	-0.524	0.088	0.288	-0.258	0.327	-0.239	-0.412	-0.064	0.164	-0.048
Boog	-0.049	0.073	-0.094	0.273	-0.467	0.164	0.012	0.061	0.288	-0.291	-0.039	-0.427	-0.045	-0.352	0.252	-0.139
WW	-0.075	-0.188	-0.055	-0.039	0.133	-0.148	0.045	-0.103	-0.103	0.491	-0.064	-0.312	-0.127	-0.409	0.024	-0.276
SS	-0.087	0.103	0.161	-0.152	-0.297	-0.348	0.309	-0.188	0.106	0.055	-0.152	-0.221	-0.209	-0.076	-0.179	-0.224

## Notes

- Only processes completed matchups (no future weeks)
- Requires a valid ESPN Fantasy Basketball league ID
- League must be public or you must have access to view it