supercontest.core.results

Calculations for the portions of views with results. Ordered by increasing complexity.

General scopes for the views:

view_allpicks(): single season, single week, all users
view_progression(): single season, all weeks, all users
view_leaderboard(): single season, all weeks, all users
view_alltime_leaderboard(): all seasons, all weeks, users

And therefore we divide utilities into buckets:

_week_results: provides data to the matchups view and the allpicks view
_season_results: provides data to the graph view and the leaderboard view
_alltime_results: provides data to the alltime leaderboard view

General flows for each view:

query_: get the raw data, usually picks / matchups, scoped by the view
map_: iterate over raw picks and key pick counts / points by season / week / user
calculate_: calculate / restructure as necessary to yield lists of user-result dicts
sort_: order those elements by the approprate keys
inject_: some information can only be calculated post-sort (eg ranks, payouts) - add those
toprow_: a final list of aggregations across a col (rather than row), for leaguewide results

FETCH, THEN COMPUTE. Each view_ function is the only part of this module that reads the database: it fetches the rows and the few facts about the season the calculation needs, and hands them to the pure function of the same view (allpicks(), progression(), leaderboard(), alltime()). Those, and every step under them, only read attributes off rows they were given – which is why the engine is tested with in-memory stand-ins, and why it never has to know how the rows were loaded.

TWO WAYS IN, ONE WAY THROUGH. The week view maps raw picks (map_picks()): it shows each pick. The season and all-time views read the week_totals the database keeps – each user’s week, already totalled – and map_week_totals() turns them into the very maps map_picks() makes. Everything after the map is shared (*_from_maps). The pick path of those views (progression(), leaderboard(), alltime()) is kept as the oracle the week totals are tested against: both must give the same answer for every season.

Functions

`allpicks`	Ranks a week's picks.
`alltime`	Ranks every finished pick ever made.
`alltime_from_maps`	Ranks every season's finished picks.
`calc_alltime_results`	Picks counts, rollups (points, total picks, etc) - data dictionaries for every user.
`calc_season_results`	Picks counts, rollups (points, total picks, etc) - data dictionaries for every user.
`calc_week_results`	Picks counts, rollups (points, total picks, etc) - data dictionaries for every user.
`fetch_season_facts`	Reads a season's `SeasonFacts`.
`get_toprow_alltime_results`	For each season, sums the total points across all users and the total picks across all users to determine a league-wide percentage.
`get_toprow_season_results`	Takes the season results by user and calculates the leaguewide perf.
`get_toprow_week_results`	Takes all picks from all users and aggregates them into the top row for leaguewide pick counts for that week.
`inject_alltime_results`	Does the post-sort value injection.
`inject_season_results`	Does the post-sort value injection.
`inject_week_results`	Does the post-sort value injection.
`leaderboard`	Ranks a season's picks, with the money in the paid league.
`leaderboard_from_maps`	Ranks a season, with the money in the paid league.
`map_picks`	Takes a raw list of pick rows and iterates over them to create the maps of pick counts and point rollups, all by season/week/user.
`map_week_totals`	The maps `map_picks()` makes, from the totals instead of the picks.
`previous_ranks`	Each user's rank at the end of the previous week: the leaderboard's movement.
`progression`	Totals a season's picks per user, in rank order.
`progression_from_maps`	Totals a season per user, in rank order.
`sort_alltime_results`	Sorts the alltime leaderboard.
`sort_season_results`	Sorts all user-week-point info.
`sort_week_results`	At the end of the day, only "total points" matters.
`view_allpicks`	The entry point for the allpicks view: fetches, then `allpicks()`.
`view_alltime_leaderboard`	The entry point for the alltimelb view: fetches, then `alltime()`.
`view_leaderboard`	The entry point for the leaderboard view: fetches, then `leaderboard()`.
`view_progression`	The entry point for the graph view: fetches, then `progression()`.

Classes

SeasonFacts

What the season views need to know about a season besides its picks.

class supercontest.core.results.SeasonFacts(weeks_in_season: int, paid_league_id: int, paid_players: list[int])

Bases: object

What the season views need to know about a season besides its picks.

paid_league_id: int: Its paid league, the one ranking whose rows carry money.

paid_players: list[int]: The paid league’s members: the size of the purse.

weeks_in_season: int: How many weeks it has: the leaderboard’s column count and the payout’s bonus count.

supercontest.core.results.allpicks(sorted_games: list[Game], picks: list[Pick], season: int, week: int) → tuple[list[WeekResults], list[tuple[int, int]]]

Ranks a week’s picks.

Parameters:

sorted_games – The week’s games, in the matchups order.
picks – The week’s picks in the league.
season – Season.
week – Week.

Returns:

The final/sorted/injected list of user:results dicts.

Returns:

The leaguewide pick counts for each team, paired by matchups.

supercontest.core.results.alltime(picks: list[Pick]) → tuple[list[AlltimeResults], list[int | float], int | float]

Ranks every finished pick ever made. The oracle for the week-totals path.

Parameters:: picks – The finished picks.
Returns:: As alltime_from_maps().

supercontest.core.results.alltime_from_maps(pick_counts: defaultdict[int, defaultdict[int, defaultdict[int, defaultdict[str, int]]]], point_rollups: defaultdict[int, defaultdict[int, defaultdict[int, defaultdict[str, float]]]], user_pick_margins: dict[int, float]) → tuple[list[AlltimeResults], list[int | float], int | float]

Ranks every season’s finished picks.

Parameters:

pick_counts – From map_week_totals() or map_picks(), finished picks only.
point_rollups – From the same.
user_pick_margins – Each user’s average margin over their finished picks.

Returns:

The final/sorted/injected list of user:results dicts.

Returns:

Leaguewide pick percentages per season.

Returns:

Rollup for alltime pick percentage, all users, all seasons, all leagues, etc.

supercontest.core.results.calc_alltime_results(pick_counts: defaultdict[int, defaultdict[int, defaultdict[int, defaultdict[str, int]]]], point_rollups: defaultdict[int, defaultdict[int, defaultdict[int, defaultdict[str, float]]]]) → list[AlltimeResults]

Picks counts, rollups (points, total picks, etc) - data dictionaries for every user.

Parameters:

pick_counts – The return from map_picks().
point_rollups – The return from map_picks().

Returns:

All aggregated results, an element per user.

supercontest.core.results.calc_season_results(pick_counts: defaultdict[int, defaultdict[int, defaultdict[int, defaultdict[str, int]]]], point_rollups: defaultdict[int, defaultdict[int, defaultdict[int, defaultdict[str, float]]]], season: int) → list[SeasonResults]

Picks counts, rollups (points, total picks, etc) - data dictionaries for every user.

Parameters:

pick_counts – The return from map_picks().
point_rollups – The return from map_picks().
season – Which season to extract from the other inputs.

Returns:

All results, an element per user.

supercontest.core.results.calc_week_results(pick_counts: defaultdict[int, defaultdict[int, defaultdict[int, defaultdict[str, int]]]], point_rollups: defaultdict[int, defaultdict[int, defaultdict[int, defaultdict[str, float]]]], raw_picks: defaultdict[int, defaultdict[int, defaultdict[int, list[Any]]]], sorted_games: list[Game], season: int, week: int) → list[WeekResults]

Picks counts, rollups (points, total picks, etc) - data dictionaries for every user.

Uses the sorted_scores input to sort the picked teams for each user; the left rollup on the allpicks view. First goes by status, then points, then mirrors the matchups sort (datetime then favoredteam name).

Parameters:

pick_counts – The return from map_picks().
point_rollups – The return from map_picks().
raw_picks – The return from map_picks().
sorted_games – The return from get_scores().
season – Which season to extract from the other inputs.
week – Which week to extract from the other inputs.

Returns:

All results, an element per user.

async supercontest.core.results.fetch_season_facts(session: AsyncSession, season: int) → SeasonFacts

Reads a season’s SeasonFacts.

Parameters:

session – The session to read through.
season – Season year.

Returns:

The facts.

supercontest.core.results.get_toprow_alltime_results(pick_counts: defaultdict[int, defaultdict[int, defaultdict[int, defaultdict[str, int]]]], point_rollups: defaultdict[int, defaultdict[int, defaultdict[int, defaultdict[str, float]]]]) → tuple[list[int | float], int | float]

For each season, sums the total points across all users and the total picks across all users to determine a league-wide percentage. Then combines across all seasons to determine an alltime league-wide %. This doesn’t filter by league, remember; it’s the free league (all users).

Parameters:

pick_counts – The return from map_picks().
point_rollups – The return from map_picks().

Returns:

Leaguewide pick percentages per season.

Returns:

Rollup for alltime pick percentage, all users, all seasons, all leagues, etc.

supercontest.core.results.get_toprow_season_results(pick_counts: defaultdict[int, defaultdict[int, defaultdict[int, defaultdict[str, int]]]], point_rollups: defaultdict[int, defaultdict[int, defaultdict[int, defaultdict[str, float]]]], season: int, weeks_in_season: int) → tuple[list[float | int | None], float | int | None]

Takes the season results by user and calculates the leaguewide perf.

This is the top row of the leaderboard. Percentage per week, as well as overall percentage for the season.

Parameters:

pick_counts – The return from map_picks().
point_rollups – The return from map_picks().
season – Season.
weeks_in_season – How many weeks it has, to pad the future ones with empty values.

Returns:

Leaguewide pick percentages. Length is the number of weeks in the season. Elements are None for future weeks with no data.

Returns:

Rollup for the whole league, whole season.

supercontest.core.results.get_toprow_week_results(sorted_games: list[Game], week_results: list[WeekResults]) → list[tuple[int, int]]

Takes all picks from all users and aggregates them into the top row for leaguewide pick counts for that week.

Parameters:

sorted_games – The return from get_scores().
week_results – The return from calc_week_results().

Returns:

The picks counts for each team in each matchup that week.

supercontest.core.results.inject_alltime_results(sorted_alltime_results: list[AlltimeResults], user_pick_margins: dict[int, float]) → list[AlltimeResults]

Does the post-sort value injection.

In-place, returning the same list-of-dicts with some new keys: rank, and each user’s average margin.

Parameters:

sorted_alltime_results – The return from sort_alltime_results().
user_pick_margins – Each user’s average margin over their finished picks, from map_week_totals() or calc_avg_user_pick_margins().

Returns:

The same as the argument list, with keys injected into each dict element.

supercontest.core.results.inject_season_results(sorted_season_results: list[SeasonResults], point_rollups: defaultdict[int, defaultdict[int, defaultdict[int, defaultdict[str, float]]]], season: int, facts: SeasonFacts, league_id: int = 0) → tuple[list[SeasonResults], int]

Does the post-sort value injection. The season views do a lot more than the week views.

Rank, percentile are standards for free leagues. This function also handles the logic for paid leagues, adding the purse/bonus/payout keys.

Parameters:

sorted_season_results – The return from sort_season_results().
point_rollups – The return from map_picks().
season – Season.
facts – The season’s week count and paid league.
league_id – League ID.

Returns:

The same as the argument list, with keys injected into each dict element.

Returns:

The remaining party fund after paid league distributions (0 if free league).

supercontest.core.results.inject_week_results(sorted_games: list[Game], sorted_week_results: list[WeekResults], toprow_week_results: list[tuple[int, int]]) → list[WeekResults]

Does the post-sort value injection. For WEEK view this is rank and pick score/grade.

Remember rank considers ONLY completed games (whereas full sort considers more). Note that this mutates the argument, the passed dict - and then returns it anyway to be explicit. Grade is the measure for how similar your picks are to other users (higher = you agreed with other users, lower = more users picked the opponent of your pick).

Parameters:

sorted_games – The return from get_scores().
sorted_week_results – The return from sort_week_results().
toprow_week_results – The picks counts for each team in each matchup that week.

Returns:

The same as the argument list, with keys injected into each dict element.

supercontest.core.results.leaderboard(picks: list[Pick], season: int, facts: SeasonFacts, league_id: int) → tuple[list[SeasonResults], list[float | int | None], float | int | None, int]

Ranks a season’s picks, with the money in the paid league. The week totals’ oracle.

Parameters:

picks – The season’s picks in the league.
season – Season.
facts – The season’s week count and paid league.
league_id – League ID.

Returns:

As leaderboard_from_maps().

supercontest.core.results.leaderboard_from_maps(pick_counts: defaultdict[int, defaultdict[int, defaultdict[int, defaultdict[str, int]]]], point_rollups: defaultdict[int, defaultdict[int, defaultdict[int, defaultdict[str, float]]]], season: int, facts: SeasonFacts, league_id: int) → tuple[list[SeasonResults], list[float | int | None], float | int | None, int]

Ranks a season, with the money in the paid league.

Parameters:

pick_counts – From map_week_totals() or map_picks().
point_rollups – From the same.
season – Season.
facts – The season’s week count and paid league.
league_id – League ID.

Returns:

The final/sorted/injected list of user:results dicts.

Returns:

Leaguewide pick percentages, one per week.

Returns:

Rollup for the whole league, whole season.

Returns:

The remaining party fund after paid league distributions (0 if free league).

supercontest.core.results.map_picks(picks: list[Pick]) → tuple[defaultdict[int, defaultdict[int, defaultdict[int, defaultdict[str, int]]]], defaultdict[int, defaultdict[int, defaultdict[int, defaultdict[str, float]]]], defaultdict[int, defaultdict[int, defaultdict[int, list[Any]]]]]

Takes a raw list of pick rows and iterates over them to create the maps of pick counts and point rollups, all by season/week/user. Is scoped by the picks that you pass it; not some manual logic of seasons/weeks/users. Therefore this function works for all views.

Parameters:: picks – The return from pick obj fetch. Pick counts and point rollups.
Returns:: Pick counts.
Returns:: Point rollups.
Returns:: Raw pick objects.

supercontest.core.results.map_week_totals(rows: Sequence[tuple[int, int, WeekTotal]], finished_only: bool = False) → tuple[defaultdict[int, defaultdict[int, defaultdict[int, defaultdict[str, int]]]], defaultdict[int, defaultdict[int, defaultdict[int, defaultdict[str, float]]]], dict[int, float]]

The maps map_picks() makes, from the totals instead of the picks.

Equal to what map_picks() returns for the same picks, key for key: a count appears only when it is not zero, as map_picks only adds to one it has a pick for; finished points only for a week with a finished pick, and inprogress only for one with a pick in progress – even when the points are zero.

Parameters:

rows – (season, week, row), as get_week_totals() returns them.
finished_only – Map only finished picks, as map_picks() does when it is given only those (the all-time view).

Returns:

Pick counts.

Returns:

Point rollups.

Returns:

Each user’s average margin over their finished picks.

supercontest.core.results.previous_ranks(pick_counts: defaultdict[int, defaultdict[int, defaultdict[int, defaultdict[str, int]]]], point_rollups: defaultdict[int, defaultdict[int, defaultdict[int, defaultdict[str, float]]]], season: int) → dict[int, int]

Each user’s rank at the end of the previous week: the leaderboard’s movement.

The previous week is every week of the season before its latest one – the latest being the highest week with any picks. The ranking is the leaderboard’s own (sort_season_results(), then calc_ranks_from_points()) over just those weeks, so the two ranks are comparable.

Parameters:

pick_counts – From map_week_totals() or map_picks().
point_rollups – From the same.
season – Season.

Returns:

user id -> rank. Empty in the season’s first week, and a user with no picks before the latest week has no entry.

supercontest.core.results.progression(picks: list[Pick], season: int) → list[SeasonResults]

Totals a season’s picks per user, in rank order. The oracle for the week-totals path.

Parameters:

picks – The season’s picks in the league.
season – Season.

Returns:

The sorted list of user:results dicts.

supercontest.core.results.progression_from_maps(pick_counts: defaultdict[int, defaultdict[int, defaultdict[int, defaultdict[str, int]]]], point_rollups: defaultdict[int, defaultdict[int, defaultdict[int, defaultdict[str, float]]]], season: int) → list[SeasonResults]

Totals a season per user, in rank order.

Parameters:

pick_counts – From map_week_totals() or map_picks().
point_rollups – From the same.
season – Season.

Returns:

The sorted list of user:results dicts.

supercontest.core.results.sort_alltime_results(alltime_results: list[AlltimeResults]) → list[AlltimeResults]

Sorts the alltime leaderboard.

Remember, rank is only dependent upon points (same as regular lb), but this sort considers more. It’s deterministic, because the frontend has to show row by row. There are no ties in the visual organization space. Sort logic:

Greater total points
Greater pick cover percentage
Fewer pushes (to weight covers more than pushes, for same points)
User ID (similar to tenure, just keeping the sort deterministic)

Parameters:: alltime_results – The return from calc_alltime_results().
Returns:: The same as the argument list, but sorted.

supercontest.core.results.sort_season_results(season_results: list[SeasonResults]) → list[SeasonResults]

Sorts all user-week-point info.

This is the same as the weekly sort for the all-picks view, but because it’s for the leaderboard (and graph), it only considers COMPLETED games. Sort logic:

Greater total points COMPLETED
Greater pick cover percentage
Fewer pushes (to weight covers more than pushes, for same points)
User ID (basically tenure, just keeping the sort deterministic)

Parameters:: season_results – The return from calc_season_results().
Returns:: The same as the argument list, but sorted.

supercontest.core.results.sort_week_results(week_results: list[WeekResults]) → list[WeekResults]

At the end of the day, only “total points” matters.

However, we must display the rows on the site in a specific order, so we make that deterministic with the following logic:

Greater total points COMPLETED
Greater covers COMPLETED
Fewer noncovers COMPLETED
Greater total points IN PROGRESS
Greater covers IN PROGRESS
Fewer noncovers IN PROGRESS
Greater number of total picks (give advantage to more active players)
User ID (basically tenure, just keeping the sort deterministic)

Parameters:: week_results – The return from calc_week_results().
Returns:: The same as the argument list, but sorted.

async supercontest.core.results.view_allpicks(session: AsyncSession, season: int, week: int, league_id: int) → tuple[list[Game], list[WeekResults], list[tuple[int, int]]]

The entry point for the allpicks view: fetches, then allpicks().

Parameters:

session – The session to read through.
season – Season.
week – Week.
league_id – League ID.

Returns:

Sorted score objects.

Returns:

The final/sorted/injected list of user:results dicts.

Returns:

The leaguewide pick counts for each team, paired by matchups.

async supercontest.core.results.view_alltime_leaderboard(session: AsyncSession) → tuple[list[AlltimeResults], list[int | float], int | float]

The entry point for the alltimelb view: fetches, then alltime().

Parameters:: session – The session to read through.
Returns:: The final/sorted/injected list of user:results dicts.
Returns:: Leaguewide pick percentages per season.
Returns:: Rollup for alltime pick percentage, all users, all seasons, all leagues, etc.

async supercontest.core.results.view_leaderboard(session: AsyncSession, season: int, league_id: int) → tuple[list[SeasonResults], list[float | int | None], float | int | None, int]

The entry point for the leaderboard view: fetches, then leaderboard().

Parameters:

session – The session to read through.
season – Season.
league_id – League ID.

Returns:

The final/sorted/injected list of user:results dicts.

Returns:

Leaguewide pick percentages. Length is the number of weeks in the season. Elements are None for future weeks with no data.

Returns:

Rollup for the whole league, whole season.

Returns:

The remaining party fund after paid league distributions (0 if free league).

async supercontest.core.results.view_progression(session: AsyncSession, season: int, league_id: int) → list[SeasonResults]

The entry point for the graph view: fetches, then progression().

Parameters:

session – The session to read through.
season – Season.
league_id – League ID.

Returns:

The sorted list of user:results dicts.