Skip to main content

Instant stats for your fantasy football league.

Project description

leeger logo

Instant stats for your fantasy football league.

Main Build Last Commit

Table of Contents

Overview

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:

  1. Load stats into a League object
  2. 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.

FAQ

Question: How do I use this library to pull stats from my online fantasy league?

Answer:

  1. Find your fantasy site here and ensure you have everything you need for the site you are using
  2. 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.

Installation

Use the package manager pip to install.

pip install leeger

Supported League Loaders

Sites that you can automatically load your league data from.

Name Website Supported
ESPN https://www.espn.com/fantasy/football/ :heavy_check_mark:
MyFantasyLeague http://home.myfantasyleague.com/ :heavy_check_mark:
NFL https://fantasy.nfl.com/ :x:
Sleeper https://sleeper.com/fantasy-football :heavy_check_mark:
Yahoo https://football.fantasysports.yahoo.com/ :heavy_check_mark:

If a fantasy site you use is not listed here and you would like it to be, please open an issue.

ESPN


Examples
League Info Needed [PUBLIC LEAGUE]
  • League ID
League Info Needed [PRIVATE LEAGUE]
  • League ID
  • ESPN_S2 parameter
  • SWID parameter

How to find your ESPN league ID.

To retrieve ESPN_S2 and SWID, follow these steps:

  1. Visit your main league page ( > i.e. https://fantasy.espn.com/football/team?leagueId={your_league_id}seasonId={any_season})
  2. Make sure you are logged in.
  3. Open Developer Tools (on Chrome/Firefox, right-click anywhere on the page and select Inspect Element)
  4. Go to Storage (for Firefox) or Application (for Chrome) and browse the Cookies available for fantasy.espn.com
  5. The values you need are called "SWID" and "ESPN_S2". You can right-click and copy the values from here.

MyFantasyLeague


Examples
League Info Needed
  • 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.

Sleeper


Examples
League Info Needed
  • League ID

How to find your Sleeper league ID.

Yahoo


Examples
League Info Needed
  • 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
Notes
  • When the Yahoo League Loader is run, Yahoo OAuth will open up a new tab in a browser. You can close this tab.

Stats Explained

An explanation of some stats offered in this library that may not be obvious.

This is not a list of all stats in this library.

To see a list of all stats retrieved by this library, see the following models:

AWAL


Purpose

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.

Formula

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)\

Formula Explained

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


Purpose

Margins of Victory (or MOV) is used to measure the magnitude of any given win.

Formula

(In any given matchup)
MOV = |Team A Score - Team B Score|
OR
MOV = Winning Team Score - Losing Team Score

Formula Explained

Note: 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


Purpose

Max Score is used to retrieve the highest score for an individual team.
It is the inverse of Min Score.

Formula

Max Score = max(A)
WHERE:
A = List of every score by a single team within a sample

Formula Explained

Note: 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


Purpose

Min Score is used to retrieve the lowest score for an individual team.
It is the inverse of Max Score.

Formula

Min Score = min(A)
WHERE:
A = List of every score by a single team in a sample size

Formula Explained

Note: 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


Purpose

Plus/Minus (+/-) is used to show the net score differential for a team within a sample.

Formula

Plus/Minus = ΣA - ΣB
WHERE:
A = All scores by a team within a sample
B = All scores against a team within a sample

Formula Explained

Plus/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


Purpose

Points Scored Per Game is the total number of points a team scored.

Formula

Points Scored Per Game = Σ A
WHERE:
A = All scores by a team within a sample\

Formula Explained

N/A

Scoring Share


Purpose

Scoring Share is used to show what percentage of league scoring a team was responsible for.

Formula

Scoring Share = ((ΣA) / (ΣB)) * 100
WHERE:
A = All scores by a team within a sample
B = All scores by all teams within a sample

Formula Explained

Scoring 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


Purpose

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.

Formula

Scoring Standard Deviation = sqrt((Σ|x-u|²)/N)
WHERE:
x = A score
u = PPG
N = Number of scores (typically weeks played)

Formula Explained

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


Purpose

Smart Wins show how many wins a team would have if it played against every score in the league within a sample.

Formula

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 - 1

Formula Explained

Smart 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


Purpose

Team Luck is used to show how much more successful a team was than what they should have been.

Formula

Team Luck = Team Success - Team Score

Formula Explained

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


Purpose

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.

Formula

Team Score = ((AWAL / G) * 100) + (Scoring Share * 2) + ((Max Score + Min Score) * 0.05)

WHERE:
G = Total games played by a team within a sample

Formula Explained

This 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


Purpose

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.

Formula

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 size

Formula Explained

This 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


Purpose

WAL stands for Wins Against the League.
It is representative of the total amount of wins and ties a team has.

Formula

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 sample

Formula Explained

WAL is a quick and useful stat that is used typically to see how successful a team has been.

Win Percentage


Purpose

Win Percentage is WAL represented as a percentage (%).

Formula

Win Percentage = WAL / G
WHERE:
G = Total number of games played by a team within a sample

Formula Explained

Win Percentage is simply another way of representing how successful a team has been throughout a sample.

Running Tests

To run tests, run the following command:

  pytest

Contributing

Pull 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.

License

MIT

Credit

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

leeger-1.2.0.tar.gz (85.6 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page