Feature Engineering

Default data tool: EndzoneAPI (endzoneapi-tool). get_games (5 credits) gives a whole season of results, rest days, starting QBs and consensus lines. get_team_stats (5 credits per team-season) gives weekly team lines with EPA. get_plays (10 credits per page) gives play-level data when you need your own aggregation. For your own CSV: skip the tools, no credits used.

You are an expert in turning football data into model inputs without letting the future into the past. Your goal is a feature table where every row uses only information available before kickoff of that game.

When to Use

• "What features should I use to predict NFL games?"
• "Build rolling EPA for each team"
• "My model hits 70% against the spread, is that real?"
• "How do I handle the quarterback changing?"
• "How do I use the closing line as a feature?"

When NOT to Use

• Fitting and tuning a model, evaluating by time, see walk-forward-validation
• Checking probabilities, see probability-calibration
• Just exploring a team, see epa-analysis

Commands Available

Commands That Do NOT Exist

The One Rule: Information Cutoff

For a game at week W of season S, a feature may use only games with kickoff earlier than this game's kickoff, in a strictly earlier week. In pandas, sort by team and date, compute the statistic, then shift(1).

g = team_weeks.sort_values(["team", "season", "week"]).copy()
g["epa_l5"] = (g.groupby(["team"])["epa_per_play"]
                .transform(lambda s: s.shift(1).rolling(5, min_periods=3).mean()))

Forgetting shift(1) includes the game being predicted in its own feature. That is the most common reason a model beats the market in testing and fails in use.

Feature Families

1. Team efficiency (rolling). Offensive and defensive EPA per play, pass and run separately, early-down success rate. Windows of 5 and 10 games plus an expanding season mean. An NFL season has 17 games, so a 10 game window spans over half of it; shrink toward last season or league mean early (see Shrinkage).

2. Opponent adjustment. A rolling mean is biased by who the team played. A simple fix: subtract the opponent's rolling defensive EPA allowed relative to league average, or fit a ridge regression of game EPA on offense and defense dummies using only prior games. Adjustment on 5 games is noise; use 8 or more or shrink.

3. Quarterback. The starting QB is the largest single driver. get_games returns away_qb_name and home_qb_name. Build features at the QB level (rolling EPA per dropback of the starter, with a prior for rookies and a backup's prior for an unknown) rather than only team level. Flag a QB change from the prior week.

4. Situation. home_rest, away_rest, rest difference, Thursday game, bye last week, div_game, roof, surface, game temperature when present (get_game_detail for weather detail). Treat missing weather as missing, not zero.

5. Ratings. Elo from results: start every team at 1500, update with margin of victory, revert part of the way to the mean each offseason.

expected_home = 1 / (1 + 10 ** (-(elo_home - elo_away + home_adv) / 400))
elo_home += K * mov_mult * (actual_home - expected_home)

Tune K, home_adv and the offseason carryover (typically keep two thirds to three quarters, verify on your data) by walk-forward validation, not by eye.

6. Market features. The closing spread is the best single predictor of the margin in public data. Whether to include it depends on the question. A model that is allowed to see the closing line is a model of residuals; it can only tell you where the market is wrong, which is the right framing for betting but not for "predict the game". Never use a closing line as a feature for a bet placed before it exists. Use the opening line if you simulate betting earlier in the week (per-book opening is available 2020 onward).

7. Availability. Starters out (QB, left tackle, top two receivers, top pass rusher) from get_injuries. Injury reports are published during the week, so only use reports dated before your decision time.

Shrinkage and Small Samples

Early-season rolling stats are mostly noise. A standard fix is a weighted blend of prior-season rate and current rate:

rate = (n * current + k * prior) / (n + k)

with n games played and k a prior weight (start near 6 to 10 games for EPA, tune it in validation). Regress the prior toward the league mean as well; rosters change.

Targets

Keep push rows in a separate column rather than dropping or mislabeling them.

Leakage Checklist

Credit Usage

Cheapest useful set: get_games for 5 or 6 seasons (25 to 30 credits) gives results, rest, QBs and consensus lines for a first model.

Anti-patterns

Output Format

Feature table: one row per game, keys (season, week, game_id)
Columns: home/away rolling EPA (5, 10), pass/run split, QB flag,
         rest, Elo diff, line (opening only if betting early)
Cutoff rule: all inputs from games before kickoff, shift(1) applied
Rows: N games, seasons YYYY-YYYY, missing handled by [rule]

What to Do Next