Scoring

FantasyScorer

Converts NFL stats into fantasy points using the league's scoring rules.

fantasyfb.scoring.fantasy_scoring.FantasyScorer

FantasyScorer(scoring_settings: Dict[str, float])

Calculates fantasy points from player statistics using configurable scoring rules.

This class extracts the core scoring logic to work with any fantasy platform that can provide player stats in the expected DataFrame format.

Note: Yahoo also exposes a generic 'TD' scoring category alongside the specific Pass/Rush/Rec/Ret/Off Fumb TD categories above. Every TD pathway nflreadpy exposes is already covered by one of those specific categories, so 'TD' is intentionally left unwired here -- scoring it independently would risk double-counting the same touchdown twice.

Initialize scorer with league-specific scoring settings.

Parameters:

Name	Type	Description	Default
scoring_settings	Dict[str, float]	Dictionary mapping stat categories to point values. Expected keys include: - 'Rush Yds', 'Rush Att', 'Rush TD', 'Rush 1D' - 'Rec', 'Rec Yds', 'Rec TD', 'Rec 1D' - 'Pass Yds', 'Pass Comp', 'Pass TD', 'Pass 1D' - 'Int Thrown', 'Fum Lost', 'Ret Yds', 'Ret TD' - 'PAT Made', 'PAT Miss', 'FG 0-19', 'FG Yds' - 'TE Rec Bonus', 'TE 1D Bonus' - 'Pass 300+', 'Rush 100+', 'Rec 100+' - '2-PT', 'Off Fumb TD' - 'Sack', 'Int', 'Fum Rec', 'TFL', 'Safe', 'Blk Kick', 'Pts Allow 0', etc.	required

calculate_points

calculate_points(stats_df: DataFrame) -> pd.DataFrame

Calculate fantasy points for all players in the stats DataFrame.

Parameters:

Name	Type	Description	Default
stats_df	DataFrame	DataFrame with player statistics. Expected columns include: - position: Player position ('QB', 'RB', 'WR', 'TE', 'K', 'DEF') - Standard stat columns like rush_yds, rec, pass_td, etc. - For DEF: points_allowed, sacks, def_int, etc.	required

Returns:

Type	Description
DataFrame	DataFrame with added 'points' column containing calculated fantasy points.

MatchupModel

Per-game multiplicative matchup factor: team implied scoring total (Vegas), opponent's allowed fantasy points to the player's position, and depth-chart string, each folded around 1.0 so points_avg = points_rate * factor. Replaces V1's basal + opp_elo_weight*elo_diff + string_weight*(1-string) formula.

fantasyfb.scoring.matchup_model.MatchupModel

MatchupModel(weights: Optional[Dict[str, _PositionWeights]] = None)

Per-game multiplicative matchup factor.

Build via :meth:from_history, which precomputes the league-wide distributions of implied total and allowed-vs-position used to z-score each input. Then call :meth:apply_factors to attach a matchup_factor column to a players DataFrame for a given week.

from_history classmethod

from_history(stats_df: DataFrame, schedule_df: DataFrame, weights: Optional[Dict[str, _PositionWeights]] = None) -> 'MatchupModel'

Fit the league-average baselines from historical data.

Parameters:

Name	Type	Description	Default
stats_df	DataFrame	per-game player stats with points, position, opponent, season, week columns. Used to compute "fantasy points allowed by team X to position P per game" via the player's opponent field.	required
schedule_df	DataFrame	per-team-game schedule with implied_total. Used for the league mean/std of implied totals.	required
weights	Optional[Dict[str, _PositionWeights]]	optional per-position coefficient overrides.	None

factor

factor(position: str, team_implied_total: float, opp_implied_total: float, opp_team: str, string: float = 1.0) -> float

Per-player matchup multiplier centered at 1.0.

apply_factors

apply_factors(players: DataFrame, schedule: DataFrame, as_of: int) -> pd.DataFrame

Attach a matchup_factor column to a players-shaped DataFrame.

Parameters:

Name	Type	Description	Default
players	DataFrame	must have current_team, position, and string.	required
schedule	DataFrame	provider schedule output (one row per team-week).	required
as_of	int	YYYYWW of the week we're projecting.	required

Returns:

Type	Description
DataFrame	A copy of players with matchup_factor and the underlying
DataFrame	inputs (team implied total, opp_team, opp allowed) joined on
DataFrame	for debuggability.

LineupOptimizer

Picks the best legal starting lineup given per-player projections and the league's roster slots.

fantasyfb.scoring.lineup_optimizer.LineupOptimizer

LineupOptimizer(roster_spots, teams, client: FantasyPlatformClient)

Handles optimal lineup selection for fantasy football teams.

Initialize the lineup optimizer.

Parameters:

Name	Type	Description	Default
roster_spots		DataFrame with roster position requirements	required
teams		List of team dictionaries	required
client	FantasyPlatformClient	FantasyPlatformClient instance	required

set_optimal_lineup

set_optimal_lineup(players, week, season, current_week, latest_season, nfl_schedule, matchup_model)

Identifies which players should be started on each fantasy team based on fantasy point projections and available roster spots.

Parameters:

Name	Type	Description	Default
players		DataFrame with player data including projections	required
week		Week for which to identify starters	required
season		Current season	required
current_week		The actual current week	required
latest_season		Most recent NFL season	required
nfl_schedule		NFL schedule with Vegas implied totals	required
matchup_model		MatchupModel that produces the per-week multiplicative factor on points_rate. Replaces V1's basal/opp_elo/string_weight formula.	required

Returns:

Type	Description
	DataFrame with players marked as starters and injury/game factors added