supercontest.util.results

Utilites for analysis; primarily the core results and stats modules.

Functions

`adjust_purses_for_tied_ranks`	The discrete log series gives us purses for each rank, but we need to handle ties.
`calc_avg_user_pick_margins`	Takes all picks and returns the average overperformance margin per USER.
`calc_ranks_from_points`	Give a list of total points (scores, basically), iterate through and rank them, giving the same rank for ties.
`calc_weekly_bonus_winners`	Takes weekly point totals for all users determines what the current payout for the bonus is (accumulating over weeks where it is not won).
`determine_payout`	Determines payout for the paid league for a season.

supercontest.util.results.adjust_purses_for_tied_ranks(ranks: list[int], purses: list[int | float] | list[int] | list[float], min_purse: int | float = 50, round_down_threshold: int = 10) → tuple[list[int], int]

The discrete log series gives us purses for each rank, but we need to handle ties. If multiple users are split for a rank, they evenly split the sum of purses across all of their ranks. This needs to repeat some of the logic from log_rank_distribution().

In the case that a tied rank at the bottom of the purse positions results in a split payment that is lower than the min_purse (usually buyin), this will cut them off and add to the 1st place winner(s).

It then, of course, rounds all resultant purses down to the nearest 10, gives the extra to 1st place(s), then rounds down a final time, and returns the remainder.

Since you can have multiple people tied for first, this function recurses until the remainder is small enough to be a roundoff (as defined by input).

Parameters:

ranks – The return from calc_ranks_from_points().
purses – The return from determine_payout().
min_purse – This is needed here again, because a split purse may result in a purse that is smaller than the buyin.
round_down_threshold – The terminal condition for recursion; it re-splits and re-rounds until the remainder is smaller than the round-down precision.

Returns:

The modified purse list, with proper splits for ties.

Returns:

The final remainder after recursion/redistribution (smaller than round-down precision).

supercontest.util.results.calc_avg_user_pick_margins(raw_picks: defaultdict[int, defaultdict[int, defaultdict[int, list[Any]]]]) → dict[int, float]

Takes all picks and returns the average overperformance margin per USER.

Parameters:: raw_picks – The raw pick objects from the db.
Returns:: Dictionary of user:avg.

supercontest.util.results.calc_ranks_from_points(points: list[int | float]) → list[int]

Give a list of total points (scores, basically), iterate through and rank them, giving the same rank for ties.

Parameters:: points – The ordered list of point totals.
Returns:: The ordered list of ranks, based on point totals.

supercontest.util.results.calc_weekly_bonus_winners(point_rollups: defaultdict[int, defaultdict[int, defaultdict[int, defaultdict[str, float]]]], season: int) → defaultdict[int, float]

Takes weekly point totals for all users determines what the current payout for the bonus is (accumulating over weeks where it is not won).

Note that this returns the normalized prize. If you win a single perfect week prize, it’s 1. If it accumulates over 3 weeks and no one else hits 5 and then you do in the 3rd week, the return is 3. If you split a single week with 3 people, your return is 0.33.

Parameters:

point_rollups – The return from map_picks().
season – The season to calculate for (just filters the first param).

Returns:

Keys are user IDs, values are weekly prizes won. For a user without a prize, it will default to 0.0.

supercontest.util.results.determine_payout(paid_players: list[int], weeks_in_season: int, weekly_bonus_winners: defaultdict[int, float], buyin: int | float = 50, party_fee: int | float = 2, weekly_bonus: int | float = 10) → tuple[list[int], defaultdict[int, int], int]

Determines payout for the paid league for a season. All logic to check league_id or if it’s a free league must be done prior.

Free users cannot win a weekly prize for 5 correct picks, obviously. Note the weekly prize is rounded down to a whole dollar (int), if split, and the remainder is given to the party fund (as well as if no one hits 5 at the end of the season).

Parameters:

paid_players – The list of player IDs in the paid league to distribute payments to.
weeks_in_season – The number of weeks in the season (used for weekly bonus purse size).
weekly_bonus_winners – The return from calc_weekly_bonus_winners().
buyin – The cost of entry per player in the paid league.
party_fee – The fee from buyin which goes toward the end-of-year party.
weekly_bonus – The allocation toward each week’s group of perfect-5-pickers, rolling over if not won.

Returns:

Purses for position winnings, in order of rank, zero padded.

Returns:

Weekly bonuses. Keys are user_id, values are dollars won (default 0.0).

Returns:

Party fund.