Instant stats for your fantasy football league.
- Overview
- FAQ
- Installation
- Supported League Loaders
- Stats Explained
- Running Tests
- Contributing
- License
- Credit
This library allows you to take data from an existing fantasy football league and get instant stats from that league
into either a Python script or an Excel spreadsheet.
This library supports multiple fantasy sites AND manual league data input.
Python stats will be stored in these objects:
Excel sheets will include:
- A tab with stats for each year the league has existed
- A tab with all-time stats for the league
- Sortable rows for each team and owner
The main idea behind this library is:
- Load stats into a League object
- Pass this League object into various library methods to extract stats
For guides on how to use this library, see the information
under Supported League Loaders and
in the example folder.
Question: How do I use this library to pull stats from my online fantasy league?
Answer:
- Find your fantasy site here and ensure you have everything you need for the site you are using
- Follow the example code snippets for your fantasy site to load the League object
Q: How can I get stats into Excel once I have my League object?
A: Follow this example code.
Q: Can I combine years from different fantasy sites that are loaded as separate League objects into a single League object?
A:
Yes, the League object supports addition (+) to combine multiple league objects.
An example of this can be found here.
Q: Can I disable validation on my League object?
A:
Yes. While it is not recommended that you disable this, as validation ensures the stats are calculated properly,
disabling validation can be done by passing validate=False into any method that takes a League object.
Use the package manager pip to install.
pip install leegerSites that you can automatically load your league data from.
If a fantasy site you use is not listed here and you would like it to be, please open an issue.
- League ID
- League ID
- ESPN_S2 parameter
- SWID parameter
How to find your ESPN league ID.
To retrieve ESPN_S2 and SWID, follow these steps:
- Visit your main league page ( > i.e. https://fantasy.espn.com/football/team?leagueId={your_league_id}seasonId={any_season})
- Make sure you are logged in.
- Open Developer Tools (on Chrome/Firefox, right-click anywhere on the page and select Inspect Element)
- Go to Storage (for Firefox) or Application (for Chrome) and browse the Cookies available for fantasy.espn.com
- The values you need are called "SWID" and "ESPN_S2". You can right-click and copy the values from here.
- League ID
- MFL Username
- MFL Password
- MFL User Agent Name
How to find your MyFantasyLeague league ID.
To set up your MyFantasyLeague account, follow these steps:
- Register a client via the API Client Registration Page (replace " current_year" with the current year)
- Set up your API Client, making sure that:
- Client Purpose = "Data Collection"
- Client User Agent is set (remember what this is as you will need it for the League Loader)
- Authorized Users has at least your MFL username- Validate your client by selecting "Validate" for your newly-created client under "Configured Clients".
- This will allow you to validate your API Client via text message.
- League ID
- League ID
- Client ID
- Client secret
How to find your Yahoo league ID.
To set up your Yahoo account, follow these steps:
- Register a new application on the Yahoo Developer Site
- Retrieve the Client ID and Client secret for the application
- Set the callback/redirect URI of the application to: https://localhost:8000
- Make sure the application has READ permissions
- When the Yahoo League Loader is run, Yahoo OAuth will open up a new tab in a browser. You can close this tab.
AWAL stands for Adjusted Wins Against the League.
It is exactly that, an adjustment added to the Wins Against the League ( or WAL) of a team.
In simple terms, this stat more accurately represents how many WAL any given team should have.
Ex: A team with 6.3 AWAL "deserves" 6.3 WAL.AWAL = W * (1/L) + T * (0.5/L)
Where:
W = Teams outscored in a week
T = Teams tied in a week
L = Opponents in a week (usually league size - 1)\To properly calculate AWAL, the AWAL must be calculated once for each team every week. Each week's AWAL can then be added together to create an aggregate AWAL for each team. A team's AWAL for any given week will always be between 0 and 1 (inclusive).
Margins of Victory (or MOV) is used to measure the magnitude of any given win.
(In any given matchup)
MOV = |Team A Score - Team B Score|
OR
MOV = Winning Team Score - Losing Team ScoreNote: Margins of Victory must be greater than 0.
Games that result in a Tie will never qualify for the Margins of Victory stat.
Max Score is used to retrieve the highest score for an individual team.
It is the inverse of Min Score.Max Score = max(A)
WHERE:
A = List of every score by a single team within a sampleNote: If a team has multiple "max" scores, this does not change the outcome.
Ex: A team with scores: [100, 105, 104, 102] has a Max Score of 105.
AND
A team with scores: [99, 105, 105, 101] has a Max Score of 105.
Min Score is used to retrieve the lowest score for an individual team.
It is the inverse of Max Score.Min Score = min(A)
WHERE:
A = List of every score by a single team in a sample sizeNote: If a team has multiple "min" scores, this does not change the outcome.
Ex: A team with scores: [100, 105, 104, 102] has a Min Score of 100.
AND
A team with scores: [99, 100, 100, 101] has a Min Score of 100.
Plus/Minus (+/-) is used to show the net score differential for a team within a sample.
Plus/Minus = ΣA - ΣB
WHERE:
A = All scores by a team within a sample
B = All scores against a team within a samplePlus/Minus can be a misleading stat, as a team with a high Plus/Minus isn't necessarily a better team than one with a low Plus/Minus.
However, it is typically a good indication of how successful a team was, as a positive net score differential typically translates to more wins.
Points Scored Per Game is the total number of points a team scored.
Points Scored Per Game = Σ A
WHERE:
A = All scores by a team within a sample\N/A
Scoring Share is used to show what percentage of league scoring a team was responsible for.
Scoring Share = ((ΣA) / (ΣB)) * 100
WHERE:
A = All scores by a team within a sample
B = All scores by all teams within a sampleScoring Share is a good way to compare how a team performed in a league one year vs another year.
While 100 Points Scored Per Game one year may not be equivalent to 100 Points Scored Per Game another year,
scoring 10% of the league's points will be equivalent to scoring 10% of the league's points another year.
Scoring Standard Deviation is used to show how volatile a team's scoring was.
This stat measures a team's scores relative to the Points Scored Per Game of all of their scores.Scoring Standard Deviation = sqrt((Σ|x-u|²)/N)
WHERE:
x = A score
u = PPG
N = Number of scores (typically weeks played)A team with low Scoring Standard Deviation has been consistent in their scoring patterns.
A team with high Scoring Standard Deviation has been volatile in their scoring patterns.
It should be noted that if a team has lower Scoring Standard Deviation than another team, it is not an indication that the team with lower Scoring Standard Deviation has performed better.
Ex: Team A has scores: [100, 120, 150, 160] and a Scoring STDEV of 23.8
Team B has scores: [70, 72, 71, 69] and a Scoring STDEV of 1.12
Team B has a lower Scoring STDEV than Team A, but has definitely performed worse.
Smart Wins show how many wins a team would have if it played against every score in the league within a sample.
Smart Wins = Σ((W + (T/2)) / S)
WHERE:
W = Total scores in the league beat within a sample
T = Total scores in the league tied within a sample
S = Number of scores in the league within a sample - 1Smart Wins is a good compliment to AWAL when comparing both to a team's WAL.
Smart Wins is better than AWAL at giving a team credit if they lose by a small margin in any given week.
Team Luck is used to show how much more successful a team was than what they should have been.
Team Luck = Team Success - Team Score
A team with a higher Team Success than Team Score likely has a higher WAL than they deserve.
Team Luck helps to quantify just how much better a team ended up than they should have.
A team with 0 Team Luck has a "fair" amount of WAL.
A team with positive (+) Team Luck has a higher amount of WAL than they deserve.
A team with negative (-) Team Luck has a lower amount of WAL than they deserve.
Note: This stat is more accurate with larger sample sizes (the more games played, the better).
Note2: The sum of all Team Luck's within a league will be ≈ 0.
Team Score is a score given to a team that is representative of how "good" that team is.
It is the sister score of Team Success.Team Score = ((AWAL / G) * 100) + (Scoring Share * 2) + ((Max Score + Min Score) * 0.05)
WHERE:
G = Total games played by a team within a sampleThis formula uses several "magic" numbers as multipliers, which typically should be avoided.
However, these numbers can be tweaked and the general Team Score for each team relative to the league will remain roughly the same.
Note: This stat is more accurate with larger sample sizes (the more games played, the better).
Team Success is a score given to a team that is representative of how successful that team has been.
It is the sister score of Team Score.Team Success = ((WAL / G) * 100) + (Scoring Share * 2) + ((Max Score + Min Score) * 0.05)
WHERE:
G = Total games played by a team in a sample sizeThis formula uses several "magic" numbers as multipliers, which typically should be avoided.
However, these numbers can be tweaked and the general Team Success for each team relative to the league will remain roughly the same.
Note: This stat is more accurate with larger sample sizes (the more games played, the better).
WAL stands for Wins Against the League.
It is representative of the total amount of wins and ties a team has.WAL = W + (T * 0.5)
WHERE:
W = Total number of wins a team has within a sample
T = Total number of ties a team has within a sampleWAL is a quick and useful stat that is used typically to see how successful a team has been.
Win Percentage is WAL represented as a percentage (%).
Win Percentage = WAL / G
WHERE:
G = Total number of games played by a team within a sampleWin Percentage is simply another way of representing how successful a team has been throughout a sample.
To run tests, run the following command:
pytestPull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
Please make sure to update tests as appropriate.