fantasyfb 0.3.0__py3-none-any.whl

fantasyfb/analysis/war_calculator.py

@@ -0,0 +1,165 @@
+"""
+WAR (Wins Above Replacement) calculation for fantasy football players.
+
+This module calculates how many more wins a player would contribute
+compared to an average replacement player at their position.
+"""
+
+import pandas as pd
+import numpy as np
+
+
+class WARCalculator:
+    """
+    Calculates Wins Above Replacement (WAR) for fantasy football players.
+    
+    WAR represents how many more wins per season a player would contribute
+    compared to an average replacement player at their position.
+    """
+    
+    def __init__(self, num_sims: int = 10000):
+        """
+        Initialize WAR calculator.
+        
+        Args:
+            num_sims: Number of Monte Carlo simulations to run
+        """
+        self.num_sims = num_sims
+    
+    def calculate_war(self, players_df: pd.DataFrame, stats_df: pd.DataFrame) -> pd.DataFrame:
+        """
+        Calculate WAR for all players based on historical performance.
+        
+        Args:
+            players_df: DataFrame with player information including points_rate, points_stdev
+            stats_df: DataFrame with historical game statistics
+            
+        Returns:
+            DataFrame with WAR values added to player data
+        """
+        # Create position histograms from historical data
+        pos_hists = self._create_position_histograms(stats_df)
+        
+        # Simulate average team performance
+        sim_scores = self._simulate_average_teams(pos_hists)
+        
+        # Create player simulation data
+        player_sims = self._simulate_player_performance(players_df, sim_scores.shape[0])
+        
+        # Merge simulations
+        sim_scores = pd.merge(
+            left=sim_scores, right=player_sims, left_index=True, right_index=True
+        )
+        
+        # Calculate WAR for each player
+        players_with_war = players_df.copy()
+        for player in player_sims.columns:
+            if pd.isnull(player):
+                print("Null player name for some reason... Skipping...")
+                continue
+            
+            war_value = self._calculate_individual_war(sim_scores, player, players_df)
+            players_with_war.loc[players_with_war.name == player, "WAR"] = war_value
+        
+        return players_with_war
+    
+    def _create_position_histograms(self, stats_df: pd.DataFrame) -> dict:
+        """Create probability histograms for each position based on historical points."""
+        pos_hists = {"points": np.arange(-10, 50.1, 0.1)}
+        
+        for pos in stats_df.position.unique():
+            pos_hists[pos] = np.histogram(
+                stats_df.loc[stats_df.position == pos, "points"],
+                bins=pos_hists["points"],
+            )[0]
+            pos_hists[pos] = pos_hists[pos] / sum(pos_hists[pos])
+        
+        # Create FLEX histogram (RB + WR + TE)
+        pos_hists["FLEX"] = np.histogram(
+            stats_df.loc[stats_df.position.isin(["RB", "WR", "TE"]), "points"],
+            bins=pos_hists["points"],
+        )[0]
+        pos_hists["FLEX"] = pos_hists["FLEX"] / sum(pos_hists["FLEX"])
+        
+        return pos_hists
+    
+    def _simulate_average_teams(self, pos_hists: dict) -> pd.DataFrame:
+        """Simulate team performance using average players at each position."""
+        return pd.DataFrame({
+            "QB": np.random.choice(
+                pos_hists["points"][:-1], p=pos_hists["QB"], size=self.num_sims
+            ),
+            "RB1": np.random.choice(
+                pos_hists["points"][:-1], p=pos_hists["RB"], size=self.num_sims
+            ),
+            "RB2": np.random.choice(
+                pos_hists["points"][:-1], p=pos_hists["RB"], size=self.num_sims
+            ),
+            "WR1": np.random.choice(
+                pos_hists["points"][:-1], p=pos_hists["WR"], size=self.num_sims
+            ),
+            "WR2": np.random.choice(
+                pos_hists["points"][:-1], p=pos_hists["WR"], size=self.num_sims
+            ),
+            "TE": np.random.choice(
+                pos_hists["points"][:-1], p=pos_hists["TE"], size=self.num_sims
+            ),
+            "FLEX": np.random.choice(
+                pos_hists["points"][:-1], p=pos_hists["FLEX"], size=self.num_sims
+            ),
+            "K": np.random.choice(
+                pos_hists["points"][:-1], p=pos_hists["K"], size=self.num_sims
+            ),
+            "DEF": np.random.choice(
+                pos_hists["points"][:-1], p=pos_hists["DEF"], size=self.num_sims
+            ),
+        })
+    
+    def _simulate_player_performance(self, players_df: pd.DataFrame, num_sims: int) -> pd.DataFrame:
+        """Generate simulated performance for all players."""
+        return pd.DataFrame({
+            players_df.loc[ind, "name"]: np.round(
+                np.random.normal(
+                    loc=players_df.loc[ind, "points_rate"],
+                    scale=players_df.loc[ind, "points_stdev"],
+                    size=num_sims,
+                )
+            )
+            for ind in range(players_df.shape[0])
+        })
+    
+    def _calculate_individual_war(self, sim_scores: pd.DataFrame, player_name: str, 
+                                 players_df: pd.DataFrame) -> float:
+        """Calculate WAR for a single player."""
+        # Get player position
+        pos = players_df.loc[players_df.name == player_name, "position"].values[0]
+        
+        # Determine roster position for comparison
+        if pos in ["RB", "WR"]:
+            comparison_pos = pos + "1"
+        else:
+            comparison_pos = pos
+        
+        # Create alternative lineup with this player
+        baseline_cols = sim_scores.columns[:9].tolist()  # Standard positions
+        baseline_cols.remove(comparison_pos)
+        baseline_cols.append(player_name)
+        
+        # Calculate total scores
+        sim_scores["Total"] = sim_scores.iloc[:, :9].sum(axis=1)
+        sim_scores["Alt_Total"] = sim_scores[baseline_cols].sum(axis=1)
+        
+        # Calculate win rate difference
+        half_sims = sim_scores.shape[0] // 2
+        wins_above_replacement = sum(
+            sim_scores.loc[:half_sims - 1, "Alt_Total"].values >
+            sim_scores.loc[half_sims:, "Total"].values
+        ) / half_sims
+        
+        # Convert to WAR (14 games per season, centered at 0.5)
+        war_value = (wins_above_replacement - 0.5) * 14
+        
+        # Clean up temporary columns
+        del sim_scores["Alt_Total"]
+        
+        return war_value

fantasyfb/cli.py

@@ -0,0 +1,202 @@
+"""
+Command-line interface for fantasy football analysis.
+
+This module handles parsing command-line arguments and setting up
+default values for the fantasy football analysis script.
+"""
+
+import datetime
+import optparse
+import os
+
+
+def initialize_inputs():
+    """
+    Initializing arguments based on command line inputs provided by the user.
+
+    Returns:
+        optparse.Values: collection of cleaned input values based on inputs and basic logic.
+    """
+    parser = optparse.OptionParser()
+    parser.add_option(
+        "--season",
+        action="store",
+        type="int",
+        dest="season",
+        help="season of interest"
+    )
+    parser.add_option(
+        "--week",
+        action="store",
+        type="int",
+        dest="week",
+        help="week to project the season from"
+    )
+    parser.add_option(
+        "--team",
+        action="store",
+        dest="team",
+        help="name of team to analyze in the case of multiple teams in a single season",
+    )
+    parser.add_option(
+        "--earliest",
+        action="store",
+        type="int",
+        dest="earliest",
+        help="earliest week of stats being considered, e.g. 201807 corresponds to week 7 of the 2018 season",
+    )
+    parser.add_option(
+        "--games",
+        action="store",
+        type="int",
+        dest="games",
+        help="number of games to build each player's prior off of",
+    )
+    parser.add_option(
+        "--basaloppstringtime",
+        action="store",
+        dest="basaloppstringtime",
+        help="scaling factors for basal/opponent/depthchart/time factors, comma-separated string of values",
+    )
+    parser.add_option(
+        "--sims", action="store", type="int", dest="sims", help="number of season simulations"
+    )
+    parser.add_option(
+        "--payouts",
+        action="store",
+        dest="payouts",
+        help="comma separated string containing integer payouts for 1st, 2nd, and 3rd",
+    )
+    parser.add_option(
+        "--injurytries",
+        action="store",
+        type="int",
+        dest="injurytries",
+        default=10,
+        help="number of times to try pulling injury statuses before rolling with it",
+    )
+    parser.add_option(
+        "--bestball",
+        action="store_true",
+        dest="bestball",
+        help="whether to assess the league of interest in the context of bestball (simulates bench contributions better)",
+    )
+    parser.add_option(
+        "--pickups",
+        action="store",
+        dest="pickups",
+        help='assess possible free agent pickups for the players specified ("all" will analyze all possible pickups)',
+    )
+    parser.add_option(
+        "--adds",
+        action="store_true",
+        dest="adds",
+        help="whether to assess possible free agent adds",
+    )
+    parser.add_option(
+        "--drops",
+        action="store_true",
+        dest="drops",
+        help="whether to assess possible drops",
+    )
+    parser.add_option(
+        "--trades",
+        action="store",
+        dest="trades",
+        help='assess possible trades for the players specified ("all" will analyze all possible trades)',
+    )
+    parser.add_option(
+        "--given",
+        action="store",
+        dest="given",
+        help="given players to start with for multi-player trades",
+    )
+    parser.add_option(
+        "--deltas",
+        action="store_true",
+        dest="deltas",
+        help="whether to assess deltas for each matchup of the current week",
+    )
+    parser.add_option(
+        "--output",
+        action="store",
+        dest="output",
+        help="where to save the final projections spreadsheet",
+    )
+
+    options, args = parser.parse_args()
+    
+    # Apply default values and validation
+    options = _apply_defaults(options)
+    options = _validate_inputs(options)
+    
+    return options
+
+
+def _apply_defaults(options):
+    """Apply default values to command line options."""
+    if not options.season:
+        options.season = datetime.datetime.now().year - int(datetime.datetime.now().month < 6)
+    
+    # Handle basaloppstringtime parsing
+    if options.basaloppstringtime:
+        options.basaloppstringtime = options.basaloppstringtime.split(",")
+        if all([val.isnumeric() for val in options.basaloppstringtime]) and len(options.basaloppstringtime) == 4:
+            options.basaloppstringtime = [float(val) for val in options.basaloppstringtime]
+        else:
+            print("Invalid rate inference parameters, using defaults...")
+            options.basaloppstringtime = None
+    
+    # Handle payouts parsing with team-specific defaults
+    if options.payouts:
+        options.payouts = options.payouts.split(",")
+        if all([val.isnumeric() for val in options.payouts]) and len(options.payouts) == 3:
+            options.payouts = [float(val) for val in options.payouts]
+        else:
+            print("Weird values provided for payouts... Assuming standard payouts...")
+            options.payouts = [60.0, 30.0, 10.0]
+    elif options.team == "The Algorithm":
+        options.payouts = [720, 360, 120]
+    elif options.team == "Toothless Wonders":
+        options.payouts = [350, 100, 50]
+    elif options.team == "The GENIEs":
+        options.payouts = [120, 0, 0]
+    elif options.team == "The Great Gadsby's":
+        options.payouts = [50, 35, 15]
+    else:
+        options.payouts = [60.0, 30.0, 10.0]
+    
+    return options
+
+
+def _validate_inputs(options):
+    """Validate and set up output directory."""
+    if not options.output:
+        options.output = (
+            os.path.expanduser("~/Documents/")
+            if os.path.exists(os.path.expanduser("~/Documents/"))
+            else os.path.expanduser("~/")
+        )
+        
+        # Create team directory if it doesn't exist
+        if options.team and not os.path.exists(options.output + options.team.replace(" ", "")):
+            os.mkdir(options.output + options.team.replace(" ", ""))
+        
+        # Create season directory if it doesn't exist
+        if options.team and not os.path.exists(
+            options.output + options.team.replace(" ", "") + "/" + str(options.season)
+        ):
+            os.mkdir(
+                options.output
+                + options.team.replace(" ", "")
+                + "/"
+                + str(options.season)
+            )
+        
+        if options.team:
+            options.output += options.team.replace(" ", "") + "/" + str(options.season)
+    
+    if options.output[-1] != "/":
+        options.output += "/"
+    
+    return options

fantasyfb/configs.py

@@ -0,0 +1,166 @@
+"""
+Predefined league configurations for fantasy football platforms.
+
+This module contains scoring settings and roster configurations for
+various fantasy platforms like Scott Fish Bowl, DraftKings, Underdog, etc.
+"""
+
+import pandas as pd
+
+# Scott Fish Bowl 13 configuration (commented out - historical)
+# SFB13_CONFIG = {
+#     'settings': {
+#         'playoff_start_week': 12,
+#         'num_playoff_teams': 6
+#     },
+#     'scoring': {
+#         'Pass Yds': 0.04, 'Pass Comp': 0.1, 'Pass TD': 6.0, 'Pass 1D': 0.1, 'Pass 300+': 0.0,
+#         'Int Thrown': 0.0, 'Rush Yds': 0.1, 'Rush Att': 0.25, 'Rush TD': 6.0, 'Rush 1D': 1.0, 'Rush 100+': 0.0,
+#         'Rec Yds': 0.1, 'Rec': 1.0, 'Rec TD': 6.0, 'Rec 1D': 1.0, 'Rec 100+': 0.0, 'Ret Yds': 0.0, 'Ret TD': 6.0,
+#         'TE Rec Bonus': 1.0, 'TE 1D Bonus': 1.0, '2-PT': 2.0, 'Fum Lost': 0.0, 'Fum Ret TD': 6.0,
+#         'FG 0-19': 2.0, 'FG 20-29': 2.5, 'FG 30-39': 3.5, 'FG 40-49': 4.5, 'FG 50+': 5.5, 'PAT Made': 3.3,
+#         'Sack': 0.0, 'Int': 0.0, 'Fum Rec': 0.0, 'TD': 0.0, 'Safe': 0.0, 'Blk Kick': 0.0,
+#         'Pts Allow 0': 0.0, 'Pts Allow 1-6': 0.0, 'Pts Allow 7-13': 0.0, 'Pts Allow 14-20': 0.0,
+#         'Pts Allow 21-27': 0.0, 'Pts Allow 28-34': 0.0, 'Pts Allow 35+': 0.0, 'XPR': 0.0
+#     },
+#     'roster_spots': pd.DataFrame({
+#         'position': ['QB', 'RB', 'WR', 'TE', 'W/R/T', 'Q/W/R/T', 'K', 'BN'],
+#         'count': [1, 2, 3, 1, 2, 1, 1, 11]
+#     })
+# }
+
+# Scott Fish Bowl 14 configuration (commented out - historical)
+# SFB14_CONFIG = {
+#     'scoring': {
+#         'Pass Yds': 0.02, 'Pass Comp': 0.0, 'Pass TD': 6.0, 'Pass 1D': 0.0, 'Pass 300+': 0.0,
+#         'Int Thrown': 0.0, 'Rush Yds': 0.1, 'Rush Att': 0.25, 'Rush TD': 6.0, 'Rush 1D': 0.5, 'Rush 100+': 0.0,
+#         'Rec Yds': 0.1, 'Rec': 0.75, 'Rec TD': 6.0, 'Rec 1D': 0.5, 'Rec 100+': 0.0, 'Ret Yds': 0.2, 'Ret TD': 10.0,
+#         'TE Rec Bonus': 0.75, 'TE 1D Bonus': 1.0, '2-PT': 2.0, 'Fum Lost': 0.0, 'Fum Ret TD': 6.0,
+#         'FG 0-19': 2.0, 'FG 20-29': 2.5, 'FG 30-39': 3.5, 'FG 40-49': 4.5, 'FG 50+': 5.5, 'PAT Made': 3.3,
+#         'Sack': 0.0, 'Int': 0.0, 'Fum Rec': 0.0, 'TD': 0.0, 'Safe': 0.0, 'Blk Kick': 0.0,
+#         'Pts Allow 0': 0.0, 'Pts Allow 1-6': 0.0, 'Pts Allow 7-13': 0.0, 'Pts Allow 14-20': 0.0,
+#         'Pts Allow 21-27': 0.0, 'Pts Allow 28-34': 0.0, 'Pts Allow 35+': 0.0, 'XPR': 0.0
+#     },
+#     'roster_spots': pd.DataFrame({
+#         'position': ['QB', 'RB', 'WR', 'TE', 'W/R/T', 'Q/W/R/T', 'K', 'BN'],
+#         'count': [1, 1, 1, 1, 5, 1, 1, 11]
+#     })
+# }
+
+# Scott Fish Bowl 15 configuration (current)
+SFB_CONFIG = {
+    'scoring': {
+        'Pass Yds': 0.04, 'Pass Comp': 0.0, 'Pass TD': 6.0, 'Pass 1D': 0.0, 'Pass 300+': 0.0,
+        'Int Thrown': 0.0, 'Rush Yds': 0.1, 'Rush Att': 0.5, 'Rush TD': 6.0, 'Rush 1D': 1.0, 'Rush 100+': 0.0,
+        'Rec Yds': 0.1, 'Rec': 2.5, 'Rec TD': 6.0, 'Rec 1D': 1.0, 'Rec 100+': 0.0, 'Ret Yds': 0.0, 'Ret TD': 6.0,
+        'TE Rec Bonus': 1.0, 'TE 1D Bonus': 1.0, '2-PT': 2.0, 'Fum Lost': 0.0, 'Fum Ret TD': 6.0,
+        'FG 0-19': 0.0, 'FG 20-29': 0.0, 'FG 30-39': 0.0, 'FG 40-49': 0.0, 'FG 50+': 0.0, 'PAT Made': 0.0,
+        'Sack': 0.0, 'Int': 0.0, 'Fum Rec': 0.0, 'TD': 0.0, 'Safe': 0.0, 'Blk Kick': 0.0,
+        'Pts Allow 0': 0.0, 'Pts Allow 1-6': 0.0, 'Pts Allow 7-13': 0.0, 'Pts Allow 14-20': 0.0,
+        'Pts Allow 21-27': 0.0, 'Pts Allow 28-34': 0.0, 'Pts Allow 35+': 0.0, 'XPR': 0.0
+    },
+    'roster_spots': pd.DataFrame({
+        'position': ['QB', 'RB', 'WR', 'TE', 'W/R/T', 'Q/W/R/T', 'K', 'BN'],
+        'count': [0, 0, 0, 0, 9, 2, 0, 11]
+    })
+}
+
+# DraftKings Best Ball configuration
+DRAFTKINGS_CONFIG = {
+    'settings': {
+        'playoff_start_week': 14,
+        'num_playoff_teams': 2
+    },
+    'scoring': {
+        'Pass Yds': 0.04, 'Pass Comp': 0.0, 'Pass TD': 4.0, 'Pass 1D': 0.0, 'Pass 300+': 3.0,
+        'Int Thrown': -1.0, 'Rush Yds': 0.1, 'Rush Att': 0.0, 'Rush TD': 6.0, 'Rush 1D': 0.0, 'Rush 100+': 3.0,
+        'Rec Yds': 0.1, 'Rec': 1.0, 'Rec TD': 6.0, 'Rec 1D': 0.0, 'Rec 100+': 3.0, 'Ret Yds': 0.0, 'Ret TD': 6.0,
+        'TE Rec Bonus': 0.0, 'TE 1D Bonus': 0.0, '2-PT': 2.0, 'Fum Lost': -1.0, 'Fum Ret TD': 6.0,
+        'FG 0-19': 0.0, 'FG 20-29': 0.0, 'FG 30-39': 0.0, 'FG 40-49': 0.0, 'FG 50+': 0.0, 'PAT Made': 0.0,
+        'Sack': 0.0, 'Int': 0.0, 'Fum Rec': 0.0, 'TD': 0.0, 'Safe': 0.0, 'Blk Kick': 0.0,
+        'Pts Allow 0': 0.0, 'Pts Allow 1-6': 0.0, 'Pts Allow 7-13': 0.0, 'Pts Allow 14-20': 0.0,
+        'Pts Allow 21-27': 0.0, 'Pts Allow 28-34': 0.0, 'Pts Allow 35+': 0.0, 'XPR': 0.0
+    },
+    'roster_spots': pd.DataFrame({
+        'position': ['QB', 'RB', 'WR', 'TE', 'W/R/T', 'Q/W/R/T', 'K', 'BN'],
+        'count': [1, 2, 3, 1, 1, 0, 0, 12]
+    })
+}
+
+# Underdog Best Ball configuration
+UNDERDOG_CONFIG = {
+    'settings': {
+        'playoff_start_week': 14,
+        'num_playoff_teams': 2
+    },
+    'scoring': {
+        'Pass Yds': 0.04, 'Pass Comp': 0.0, 'Pass TD': 4.0, 'Pass 1D': 0.0, 'Pass 300+': 0.0,
+        'Int Thrown': -1.0, 'Rush Yds': 0.1, 'Rush Att': 0.0, 'Rush TD': 6.0, 'Rush 1D': 0.0, 'Rush 100+': 0.0,
+        'Rec Yds': 0.1, 'Rec': 0.5, 'Rec TD': 6.0, 'Rec 1D': 0.0, 'Rec 100+': 0.0, 'Ret Yds': 0.0, 'Ret TD': 0.0,
+        'TE Rec Bonus': 0.0, 'TE 1D Bonus': 0.0, '2-PT': 2.0, 'Fum Lost': -2.0, 'Fum Ret TD': 0.0,
+        'FG 0-19': 0.0, 'FG 20-29': 0.0, 'FG 30-39': 0.0, 'FG 40-49': 0.0, 'FG 50+': 0.0, 'PAT Made': 0.0,
+        'Sack': 0.0, 'Int': 0.0, 'Fum Rec': 0.0, 'TD': 0.0, 'Safe': 0.0, 'Blk Kick': 0.0,
+        'Pts Allow 0': 0.0, 'Pts Allow 1-6': 0.0, 'Pts Allow 7-13': 0.0, 'Pts Allow 14-20': 0.0,
+        'Pts Allow 21-27': 0.0, 'Pts Allow 28-34': 0.0, 'Pts Allow 35+': 0.0, 'XPR': 0.0
+    },
+    'roster_spots': pd.DataFrame({
+        'position': ['QB', 'RB', 'WR', 'TE', 'W/R/T', 'Q/W/R/T', 'K', 'BN'],
+        'count': [1, 2, 3, 1, 1, 0, 0, 10]
+    })
+}
+
+
+def get_league_config(platform: str):
+    """
+    Get predefined configuration for a specific platform.
+    
+    Args:
+        platform: Platform name ('sfb', 'draftkings'/'dk', 'underdog')
+        
+    Returns:
+        Dict containing scoring and roster configuration, or None if not found
+    """
+    platform_lower = platform.lower()
+    
+    if platform_lower == 'sfb':
+        return SFB_CONFIG
+    elif platform_lower in ['dk', 'draftkings']:
+        return DRAFTKINGS_CONFIG
+    elif platform_lower == 'underdog':
+        return UNDERDOG_CONFIG
+    else:
+        return None
+
+
+def apply_default_scoring_categories(scoring: dict):
+    """
+    Add missing scoring categories with default values of 0.0.
+    
+    Args:
+        scoring: Dictionary of scoring settings
+        
+    Returns:
+        Dictionary with all expected scoring categories
+    """
+    default_categories = [
+        'Pass Comp', 'Pass 1D', 'Rush Att', 'Rush 1D', 'Rec 1D',
+        'TE Rec Bonus', 'TE 1D Bonus', 'Pass 300+', 'Rush 100+', 'Rec 100+'
+    ]
+    
+    for category in default_categories:
+        if category not in scoring:
+            scoring[category] = 0.0
+    
+    # Set default kicker scoring if missing
+    if "FG 0-19" not in scoring:
+        scoring["FG 0-19"] = 3
+    
+    # Set default reception scoring if missing
+    if "Rec" not in scoring:
+        scoring["Rec"] = 0
+    
+    # Set default return yardage scoring if missing
+    if "Ret Yds" not in scoring:
+        scoring["Ret Yds"] = 0
+    
+    return scoring

fantasyfb/data/__init__.py

@@ -0,0 +1 @@
+"""Data providers and player/league clients."""

fantasyfb/data/nfl_provider.py

@@ -0,0 +1,102 @@
+"""
+NFL data provider interface.
+
+Defines the contract that every concrete NFL data backend must satisfy so
+that the rest of fantasyfb is decoupled from any specific source (PFR,
+nflreadpy, ESPN, etc.).
+
+The canonical column schema returned by each method is documented on the
+method itself. Concrete providers are responsible for translating their
+upstream schema into this canonical one.
+"""
+
+from abc import ABC, abstractmethod
+
+import pandas as pd
+
+
+class NFLDataProvider(ABC):
+    """Abstract base for NFL data backends.
+
+    The legacy column name `player_id_sr` is preserved as the canonical
+    cross-table player identifier. Concrete providers are free to populate
+    it with whatever ID system they natively use (PFR id, GSIS id, etc.) as
+    long as the same value joins stats, rosters, and depth charts.
+    """
+
+    @abstractmethod
+    def get_player_stats(self, start: int, finish: int) -> pd.DataFrame:
+        """Per-game player + team-defense stats for the YYYYWW range.
+
+        Required columns:
+            player_id_sr, name, position, team, opponent,
+            season, week, game_id, points_allowed,
+            rush_yds, rush_att, rush_td, rush_first_down,
+            rec, rec_yds, rec_td, rec_first_down,
+            pass_yds, pass_cmp, pass_td, pass_first_down, pass_int,
+            fumbles_lost, kick_ret_yds, punt_ret_yds,
+            kick_ret_td, punt_ret_td, xpm, fgm,
+            sacks, def_int, fumbles_rec, def_int_td, fumbles_rec_td
+
+        Defenses are emitted as one row per team-week with
+        position == "DEF" and player_id_sr set to the team abbreviation.
+        """
+
+    @abstractmethod
+    def get_schedule(self, start_year: int, end_year: int) -> pd.DataFrame:
+        """NFL schedule with one row per team-game (two rows per game).
+
+        Required columns:
+            season, week, date, team, home_away, opp_team,
+            elo_diff, opp_elo
+
+        elo_diff and opp_elo carry forward the legacy "opponent strength"
+        signal. Providers without true Elo ratings should map a strength
+        proxy (e.g. Vegas spread) into elo_diff with consistent sign:
+        positive elo_diff means the team is favored.
+        """
+
+    @abstractmethod
+    def get_rosters(self, start_year: int, end_year: int) -> pd.DataFrame:
+        """Active rosters for the year range.
+
+        Required columns:
+            name, current_team, position, player_id_sr
+
+        Optional columns (populated when available):
+            yahoo_id  -- enables direct Yahoo->NFL ID linkage
+        """
+
+    @abstractmethod
+    def get_depth_charts(self) -> pd.DataFrame:
+        """Current-week depth charts.
+
+        Required columns:
+            name, current_team, position, string
+
+        `string` follows the legacy convention: 1.0 = starter, 2.0 = backup,
+        3.0 = third string, etc.
+        """
+
+    @abstractmethod
+    def get_draft(self, year: int) -> pd.DataFrame:
+        """Draft picks for the given year.
+
+        Required columns:
+            name, current_team, player_id_sr
+        """
+
+    @abstractmethod
+    def team_aliases(self) -> pd.DataFrame:
+        """Translation table between Yahoo and provider-native team codes.
+
+        Required columns:
+            yahoo        -- value Yahoo emits as `editorial_team_abbr`
+            real_abbrev  -- provider-native team code (matches the `team`
+                            column returned by get_player_stats and
+                            get_schedule)
+
+        The column names mirror the legacy team_abbrevs.csv schema so that
+        existing callers reading `nfl_teams.real_abbrev` keep working; the
+        values now point at the active backend rather than at PFR.
+        """