Learning ObjectivesBy the end of this chapter, you will be able to:

1. Understand salary cap mechanics and structure
2. Analyze contract value and optimization
3. Evaluate positional spending strategies
4. Study market efficiency and value contracts
5. Build roster cost optimization models

Introduction

The NFL salary cap represents one of the most complex and consequential constraints in professional sports. Unlike other major North American sports leagues with luxury tax systems (NBA, MLB) or higher caps (NBA), the NFL enforces a hard salary cap that requires teams to make difficult choices about resource allocation.

In 2023, the salary cap was set at $224.8 million per team, with projections reaching $255+ million by 2024. While this seems like a large amount, the reality is that with 53-man rosters, practice squads, and guaranteed contracts, teams must carefully manage every dollar to remain competitive.

The salary cap creates a unique analytical challenge: teams must simultaneously optimize for on-field performance (winning games), financial efficiency (maximizing value per dollar), and long-term sustainability (maintaining flexibility for future seasons). This multi-objective optimization problem requires sophisticated data science approaches that combine financial analysis, statistical modeling, and strategic planning.

Consider the strategic dilemma facing teams with elite quarterbacks on expensive contracts. Patrick Mahomes, for example, signed a 10-year, $450 million extension with the Kansas City Chiefs in 2020. While Mahomes is undoubtedly worth the investment, his cap hit limits spending elsewhere on the roster. The Chiefs must find value contracts at other positions—often through the draft or by identifying undervalued veterans—to maintain a competitive roster. This is the essence of salary cap analytics: making optimal resource allocation decisions under severe budget constraints.

This chapter explores how teams can use data science to navigate these challenges effectively. We'll cover both the practical mechanics of the salary cap and the analytical techniques used to gain competitive advantages in roster construction.

Salary Cap Structure and Mechanics

Understanding salary cap analytics requires first understanding how the cap itself works. The NFL salary cap is far more complex than simply "teams can't spend more than $X million." The rules around contract structure, bonus proration, dead money, and roster accounting create opportunities for creative cap management—and analytical advantages for teams that understand these nuances.

The Basics

The NFL salary cap is determined by a formula based on league revenues, which are split between owners and players according to the Collective Bargaining Agreement (CBA). The current CBA, negotiated in 2020, specifies that players receive approximately 48% of total league revenue.

$$ \text{Salary Cap} = \frac{\text{Total League Revenue} \times \text{Player Share}}{32 \text{ teams}} $$

This formula creates a direct link between league financial health and team spending capacity. When league revenues grow—through new broadcast deals, expanded playoffs, or increased sponsorship—the salary cap rises, giving teams more flexibility. Conversely, events like the COVID-19 pandemic that reduce revenues can constrain team spending.

The cap applies to the "top 51" rule during the offseason, meaning only a team's 51 highest cap hits count against the cap until the final roster is set. This allows teams to sign draft picks and maintain larger rosters during training camp without immediately counting every contract against the cap.

Key Cap Concepts

Several critical concepts separate cash spending from cap accounting, creating opportunities for financial engineering:

Cash vs. Cap: The actual cash paid to a player in a given year can differ significantly from the cap hit due to signing bonuses and guarantees. Teams often use this distinction to manipulate their cap situation, paying players large upfront bonuses (cash) that prorate over multiple years (cap), creating short-term cap savings at the expense of future flexibility.

Dead Money: Cap charges that remain when a player is released, typically from prorated signing bonuses. When a team releases a player, any remaining prorated bonus money "accelerates" to the current year (with some exceptions for post-June 1 designations). Dead money represents perhaps the most visible cost of roster mistakes—teams paying millions in cap space for players no longer on the roster.

Cap Carry Over: Unused cap space from one season can be carried to the next, creating a strategic decision: should teams use all available cap space to maximize current season competitiveness, or preserve some for future flexibility? This decision depends on championship window considerations and upcoming contract situations.

Performance Escalators: Contract provisions that increase salary based on playing time or performance. These allow teams to bet on player development while protecting against overpayment if the player doesn't meet expectations. For example, a contract might escalate by $2 million if a player makes the Pro Bowl.

These cap mechanics create a complex optimization problem. Teams must balance immediate competitiveness (using cap space now) against future flexibility (preserving cap space for later). The best analytical approaches model these trade-offs explicitly, considering multiple future scenarios and their probabilities.

Positional Cap Rules

Certain positions have minimum salary requirements and special rules that create strategic considerations:

Top-51 Rule: During offseason, only top 51 cap hits count. This creates an interesting strategic element: teams can sign extra players to compete during training camp without immediately facing cap consequences. However, when final rosters are set, all contracts count, potentially creating cap crunches for teams that aren't careful with their planning.

Minimum Salary Benefit: Veteran minimum salaries have cap advantages through the Veteran Salary Benefit program. When teams sign veteran players to minimum salary contracts, only a portion counts against the cap, with the league funding the difference. This creates value opportunities for teams willing to sign older players to short-term, minimum contracts.

Franchise Tag: Calculated as average of top 5 salaries at position (or 120% of previous salary, whichever is greater). The franchise tag allows teams to retain players for one year without negotiating a long-term deal, but at a premium price. This creates strategic decisions: is it better to sign a player to a long-term deal with lower annual value, or keep them on the tag while maintaining future flexibility?

Understanding these rules is essential for cap analytics because they create opportunities for arbitrage—finding loopholes or inefficiencies in the cap system that allow teams to gain competitive advantages. The best cap managers combine deep knowledge of these rules with analytical rigor to construct optimal rosters.

Setting Up the Environment

Before we dive into salary cap analysis, we need to set up our analytical environment with the necessary packages and libraries. In a real-world scenario, you would access contract data from sources like Over The Cap or Spotrac through their APIs. For this chapter, we'll use simulated contract data that mirrors the structure of real NFL contracts, allowing us to demonstrate analytical techniques without requiring API access.

The data we'll work with includes key contract elements: player names, positions, teams, contract length, total value, guaranteed money, and annual cap hits. We'll also incorporate player performance data from nflfastR to evaluate contract efficiency—the relationship between what teams pay and what they receive in on-field production.

#| eval: false
#| echo: true

# Install required packages for salary cap analysis
# tidyverse: data manipulation and visualization
# nflfastR: NFL play-by-play data for performance metrics
# nflreadr: efficient data reading from nflverse
# gt/gtExtras: creating publication-quality tables
# scales: formatting numbers and currencies
# glmnet: regularized regression for market value models
# randomForest: ensemble models for contract prediction

install.packages("tidyverse")
install.packages("nflfastR")
install.packages("nflreadr")
install.packages("gt")
install.packages("gtExtras")
install.packages("scales")
install.packages("glmnet")
install.packages("randomForest")

#| message: false
#| warning: false

# Load packages into R session
library(tidyverse)      # For data manipulation and visualization
library(nflfastR)       # For NFL play-by-play data
library(nflreadr)       # For efficient data loading
library(gt)             # For creating formatted tables
library(gtExtras)       # For enhanced table features
library(scales)         # For formatting numbers and scales

cat("✓ R packages loaded successfully\n")

#| eval: false
#| echo: true

# Install required packages for salary cap analysis
# pandas: data manipulation and analysis
# numpy: numerical computing and array operations
# nfl-data-py: NFL data access including play-by-play
# matplotlib/seaborn: data visualization
# scikit-learn: machine learning for contract models
# scipy: optimization algorithms for roster construction

pip install pandas numpy nfl-data-py matplotlib seaborn scikit-learn scipy

#| message: false
#| warning: false

# Import Python packages
import pandas as pd                           # Data manipulation
import numpy as np                            # Numerical operations
import nfl_data_py as nfl                     # NFL data access
import matplotlib.pyplot as plt               # Plotting
import seaborn as sns                         # Statistical visualization
from sklearn.linear_model import LinearRegression, Ridge  # Regression models
from sklearn.ensemble import RandomForestRegressor        # Ensemble models
from sklearn.model_selection import train_test_split     # Model validation
from scipy.optimize import minimize                       # Optimization

print("✓ Python packages loaded successfully")

Both R and Python provide excellent tools for salary cap analysis. R's tidyverse ecosystem offers intuitive data manipulation, while Python's scikit-learn provides robust machine learning capabilities. Choose based on your team's existing infrastructure and expertise.

Loading and Preparing Salary Cap Data

Contract data forms the foundation of salary cap analytics. In production environments, this data typically comes from specialized sources like Over The Cap, Spotrac, or proprietary team databases. These sources track detailed contract information including signing bonuses, yearly salaries, guaranteed amounts, roster bonuses, workout bonuses, and option clauses.

For our analysis, we'll simulate contract data that mirrors real NFL contract structures. This simulation includes realistic distributions of contract values by position, appropriate ranges for guaranteed percentages, and sensible relationships between age, experience, and contract value.

Contract Data Sources

Real-world contract data requires careful validation because publicly available information may be incomplete or inaccurate. Teams often structure contracts with complex clauses and incentives that aren't immediately apparent in public databases. When building production analytics systems, always cross-reference multiple sources and validate against official league cap reports.

#| label: load-contract-data-r
#| message: false
#| warning: false
#| cache: true

# Simulate contract data for demonstration purposes
# In practice, this would come from Over The Cap, Spotrac, or similar sources
# Real data would include: signing bonuses, yearly breakdowns, option years,
# incentives, guarantees for injury vs. skill, and detailed cap accounting

set.seed(2024)  # Set seed for reproducible random generation

# Create simulated contract dataset
contracts <- tibble(
  # Generate player identifiers (in practice, would be actual names)
  player = paste("Player", 1:500),

  # Position assignment - weighted toward positions with more players
  position = sample(c("QB", "RB", "WR", "TE", "OL",
                     "DL", "LB", "CB", "S", "K/P"),
                   500, replace = TRUE),

  # Team assignment - sample from actual NFL teams
  team = sample(nfl_teams()$team_abbr, 500, replace = TRUE),

  # Contract length - most contracts are 3-5 years
  years = sample(1:6, 500, replace = TRUE),

  # Total contract value - log-normal distribution for realistic skew
  # exp(rnorm(mean=16, sd=1.5)) creates values centered around $9M
  total_value = exp(rnorm(500, mean = 16, sd = 1.5)) * 1e6,

  # Guaranteed percentage - varies by position and player quality
  # Range from 20% (prove-it deals) to 80% (star players)
  guaranteed = runif(500, 0.2, 0.8),

  # Player age - realistic age range for NFL players
  age = sample(22:35, 500, replace = TRUE),

  # Years of experience in NFL
  experience = sample(0:15, 500, replace = TRUE),

  # Calculate average annual value (APY)
  apy = total_value / years
) %>%
  mutate(
    # Calculate guaranteed money in dollars
    guaranteed_money = total_value * guaranteed,

    # Cap hit for 2024 - varies around APY due to signing bonus proration
    # Real contracts would have exact yearly cap hits
    cap_hit_2024 = apy * runif(500, 0.8, 1.2),

    # Adjust QB contracts upward - QBs command premium salaries
    # Multiply by 2.5 to reflect QB market (top QBs make ~$50M APY)
    total_value = ifelse(position == "QB", total_value * 2.5, total_value),

    # Recalculate derived values after QB adjustment
    apy = total_value / years,
    guaranteed_money = total_value * guaranteed,
    cap_hit_2024 = apy * runif(500, 0.8, 1.2)
  )

# Display summary statistics
cat("Loaded", nrow(contracts), "player contracts\n")
cat("Total contract value:", scales::dollar(sum(contracts$total_value)), "\n")
cat("Average APY:", scales::dollar(mean(contracts$apy)), "\n")
cat("Position breakdown:\n")
print(table(contracts$position))

#| label: load-contract-data-py
#| message: false
#| warning: false
#| cache: true

# Simulate contract data structure
# In production, would load from API or database
np.random.seed(2024)

# Get team abbreviations from nfl_data_py
teams = nfl.import_team_desc()[['team_abbr']].dropna()['team_abbr'].unique()

# Define position groups
positions = ['QB', 'RB', 'WR', 'TE', 'OL', 'DL', 'LB', 'CB', 'S', 'K/P']

# Number of contracts to simulate
n = 500

# Create contract dataframe with realistic structure
contracts = pd.DataFrame({
    # Player identifiers
    'player': [f'Player {i}' for i in range(1, n+1)],

    # Random position assignment
    'position': np.random.choice(positions, n),

    # Random team assignment from actual NFL teams
    'team': np.random.choice(teams, n),

    # Contract length - most 3-5 years
    'years': np.random.randint(1, 7, n),

    # Total value - log-normal distribution for realistic skew
    # Most contracts $5-20M total, some much higher
    'total_value': np.exp(np.random.normal(16, 1.5, n)) * 1e6,

    # Guaranteed percentage - varies widely
    'guaranteed': np.random.uniform(0.2, 0.8, n),

    # Player age - realistic NFL range
    'age': np.random.randint(22, 36, n),

    # Years in NFL
    'experience': np.random.randint(0, 16, n)
})

# Calculate derived contract values
contracts['apy'] = contracts['total_value'] / contracts['years']
contracts['guaranteed_money'] = contracts['total_value'] * contracts['guaranteed']
contracts['cap_hit_2024'] = contracts['apy'] * np.random.uniform(0.8, 1.2, n)

# Adjust QB contracts to reflect market premium
qb_mask = contracts['position'] == 'QB'
contracts.loc[qb_mask, 'total_value'] *= 2.5

# Recalculate derived values after QB adjustment
contracts['apy'] = contracts['total_value'] / contracts['years']
contracts['guaranteed_money'] = contracts['total_value'] * contracts['guaranteed']
contracts.loc[qb_mask, 'cap_hit_2024'] = contracts.loc[qb_mask, 'apy'] * np.random.uniform(0.8, 1.2, qb_mask.sum())

# Display summary
print(f"Loaded {len(contracts):,} player contracts")
print(f"Total contract value: ${contracts['total_value'].sum():,.0f}")
print(f"Average APY: ${contracts['apy'].mean():,.0f}")
print(f"\nPosition breakdown:")
print(contracts['position'].value_counts().sort_index())

This simulated data provides a realistic foundation for our analyses. The key variables—position, team, contract value, guarantees, age, and experience—mirror actual NFL contract structures. The data reflects real patterns: QB contracts are significantly larger, contract length varies by position, and guaranteed percentages differ based on player leverage and risk.

Loading Performance Data

To evaluate contract efficiency—whether teams are getting good value for their spending—we need performance metrics to pair with contract data. The most comprehensive approach combines multiple data sources: nflfastR for play-by-play EPA, PFF grades for subjective evaluation, and Next Gen Stats for tracking data.

For this analysis, we'll focus on EPA-based metrics from nflfastR, which provide objective, outcome-based measures of player contribution. We'll calculate position-specific performance metrics that can be directly related to contract value.

#| label: load-performance-r
#| message: false
#| warning: false
#| cache: true

# Load recent season data for performance metrics
# This provides play-by-play EPA data we can aggregate by player
pbp_2023 <- load_pbp(2023)

# Calculate QB performance metrics
# Focus on efficiency metrics (EPA per play) rather than volume
qb_performance <- pbp_2023 %>%
  # Filter to plays with valid EPA and identified passer
  filter(!is.na(epa), !is.na(passer_player_name)) %>%

  # Group by QB and team to calculate performance metrics
  group_by(passer_player_name, posteam) %>%
  summarise(
    # Sample size - minimum 100 dropbacks for reliable estimates
    dropbacks = n(),

    # Expected Points Added per play - primary efficiency metric
    epa_per_play = mean(epa),

    # Completion percentage over expectation - adjusts for difficulty
    cpoe = mean(cpoe, na.rm = TRUE),

    # Success rate - percentage of positive EPA plays
    success_rate = mean(epa > 0),

    .groups = "drop"
  ) %>%

  # Filter to QBs with sufficient sample size
  filter(dropbacks >= 100) %>%

  # Rename for joining with contract data
  rename(player = passer_player_name, team = posteam)

# Calculate RB performance metrics
# Running backs evaluated on rushing efficiency
rb_performance <- pbp_2023 %>%
  filter(!is.na(epa), play_type == "run", !is.na(rusher_player_name)) %>%
  group_by(rusher_player_name, posteam) %>%
  summarise(
    rushes = n(),
    epa_per_rush = mean(epa),
    success_rate = mean(epa > 0),
    yards_per_rush = mean(yards_gained, na.rm = TRUE),
    .groups = "drop"
  ) %>%
  filter(rushes >= 50) %>%
  rename(player = rusher_player_name, team = posteam)

# Calculate WR/TE performance metrics
# Receivers evaluated on per-target efficiency
wr_performance <- pbp_2023 %>%
  filter(!is.na(epa), play_type == "pass", !is.na(receiver_player_name)) %>%
  group_by(receiver_player_name, posteam) %>%
  summarise(
    targets = n(),
    epa_per_target = mean(epa),
    success_rate = mean(epa > 0),
    yards_per_target = mean(yards_gained, na.rm = TRUE),
    .groups = "drop"
  ) %>%
  filter(targets >= 30) %>%
  rename(player = receiver_player_name, team = posteam)

cat("Performance metrics calculated for",
    nrow(qb_performance), "QBs,",
    nrow(rb_performance), "RBs,",
    nrow(wr_performance), "WRs\n")

#| label: load-performance-py
#| message: false
#| warning: false
#| cache: true

# Load 2023 season play-by-play data
pbp_2023 = nfl.import_pbp_data([2023])

# Calculate QB performance metrics
# Group by passer and aggregate efficiency metrics
qb_performance = (pbp_2023
    .query("epa.notna() & passer_player_name.notna()")
    .groupby(['passer_player_name', 'posteam'])
    .agg(
        # Count total dropbacks (sample size)
        dropbacks=('epa', 'count'),

        # Mean EPA per dropback (efficiency metric)
        epa_per_play=('epa', 'mean'),

        # Completion percentage over expectation
        cpoe=('cpoe', lambda x: x.mean()),

        # Success rate (% of positive EPA plays)
        success_rate=('epa', lambda x: (x > 0).mean())
    )
    # Filter to QBs with meaningful sample size
    .query("dropbacks >= 100")
    .reset_index()
    .rename(columns={'passer_player_name': 'player', 'posteam': 'team'})
)

# Calculate RB performance metrics
rb_performance = (pbp_2023
    .query("epa.notna() & play_type == 'run' & rusher_player_name.notna()")
    .groupby(['rusher_player_name', 'posteam'])
    .agg(
        rushes=('epa', 'count'),
        epa_per_rush=('epa', 'mean'),
        success_rate=('epa', lambda x: (x > 0).mean()),
        yards_per_rush=('yards_gained', 'mean')
    )
    .query("rushes >= 50")
    .reset_index()
    .rename(columns={'rusher_player_name': 'player', 'posteam': 'team'})
)

# Calculate WR/TE performance metrics
wr_performance = (pbp_2023
    .query("epa.notna() & play_type == 'pass' & receiver_player_name.notna()")
    .groupby(['receiver_player_name', 'posteam'])
    .agg(
        targets=('epa', 'count'),
        epa_per_target=('epa', 'mean'),
        success_rate=('epa', lambda x: (x > 0).mean()),
        yards_per_target=('yards_gained', 'mean')
    )
    .query("targets >= 30")
    .reset_index()
    .rename(columns={'receiver_player_name': 'player', 'posteam': 'team'})
)

print(f"Performance metrics calculated for {len(qb_performance)} QBs, "
      f"{len(rb_performance)} RBs, {len(wr_performance)} WRs")

These performance metrics provide the foundation for evaluating contract efficiency. By combining per-play efficiency metrics (EPA per play) with contract data (APY), we can identify which players provide the most value per dollar—a critical insight for cap-constrained teams.

The key insight here is using efficiency metrics (per-play EPA) rather than volume metrics (total yards or touchdowns). Volume metrics conflate opportunity with production—a player who gets more plays will accumulate more total stats regardless of efficiency. Efficiency metrics isolate the player's contribution per opportunity, which better reflects true value and translates across different usage levels.

Contract Valuation Analysis

Understanding what drives contract values is fundamental to salary cap analytics. Contract valuation isn't purely about performance—market timing, positional scarcity, leverage in negotiations, and team cap situations all influence final contract terms. By building statistical models that account for these factors, we can identify when teams are paying above or below market rate for players.

This section develops market value models that predict expected contract value based on observable player characteristics. The residuals from these models—the difference between actual and predicted contract value—reveal which players represent value contracts (underpaid) or overpays.

Average Annual Value (APY) by Position

The most basic metric for contract comparison is Average Annual Value (APY), calculated by dividing total contract value by contract length. While simple, APY has limitations: it doesn't account for guarantees, signing bonus structure, or the real cap accounting. However, it provides a useful starting point for cross-contract comparisons.

$$ \text{APY} = \frac{\text{Total Contract Value}}{\text{Contract Years}} $$

Different positions command dramatically different APY values in the NFL market. Quarterbacks earn far more than any other position, reflecting their disproportionate impact on winning. Within non-QB positions, there's a clear hierarchy: elite pass rushers and left tackles command premiums, while running backs and off-ball linebackers earn less.

#| label: positional-apy-r
#| message: false
#| warning: false

# Calculate comprehensive APY statistics by position
# This analysis reveals the positional market structure
apy_by_position <- contracts %>%
  group_by(position) %>%
  summarise(
    # Sample size for each position
    n = n(),

    # Mean APY - affected by star contracts and outliers
    mean_apy = mean(apy),

    # Median APY - more robust to outliers, better represents "typical" contract
    median_apy = median(apy),

    # 75th percentile - represents "good" contracts for starters
    q75_apy = quantile(apy, 0.75),

    # Maximum APY - represents elite player contracts
    max_apy = max(apy),

    # Average percentage of contract guaranteed
    pct_guaranteed = mean(guaranteed * 100),

    .groups = "drop"
  ) %>%
  # Sort by mean APY to see positional hierarchy
  arrange(desc(mean_apy))

# Display as formatted table with proper currency formatting
apy_by_position %>%
  gt() %>%
  cols_label(
    position = "Position",
    n = "N",
    mean_apy = "Mean APY",
    median_apy = "Median APY",
    q75_apy = "75th Pct",
    max_apy = "Max APY",
    pct_guaranteed = "% Guaranteed"
  ) %>%
  fmt_currency(
    columns = c(mean_apy, median_apy, q75_apy, max_apy),
    decimals = 0
  ) %>%
  fmt_number(
    columns = pct_guaranteed,
    decimals = 1
  ) %>%
  tab_header(
    title = "Contract APY by Position",
    subtitle = "Average Annual Value and Guarantee Rates"
  ) %>%
  tab_source_note("Sample contract data")

#| label: positional-apy-py
#| message: false
#| warning: false

# Calculate APY statistics by position
# Provides comprehensive view of positional markets
apy_by_position = (contracts
    .groupby('position')
    .agg(
        n=('apy', 'count'),
        mean_apy=('apy', 'mean'),
        median_apy=('apy', 'median'),
        q75_apy=('apy', lambda x: x.quantile(0.75)),
        max_apy=('apy', 'max'),
        pct_guaranteed=('guaranteed', lambda x: x.mean() * 100)
    )
    .sort_values('mean_apy', ascending=False)
    .reset_index()
)

print("\nContract APY by Position:")
print("="*80)
for _, row in apy_by_position.iterrows():
    print(f"{row['position']:>4} | N={row['n']:>3} | "
          f"Mean: ${row['mean_apy']/1e6:>5.1f}M | "
          f"Median: ${row['median_apy']/1e6:>5.1f}M | "
          f"Max: ${row['max_apy']/1e6:>5.1f}M | "
          f"Guaranteed: {row['pct_guaranteed']:>4.1f}%")

When we examine these positional APY statistics, several patterns emerge. Quarterbacks command dramatically higher APY than any other position—often 2-3 times higher than the next highest position. This reflects the quarterback's unique importance to team success. Research consistently shows QB play explains more variance in team wins than any other position.

Within non-QB positions, we see a clear hierarchy. Positions that impact the passing game—wide receivers, cornerbacks, edge rushers—command higher APY than positions primarily involved in the run game—running backs, off-ball linebackers. This reflects the modern NFL's pass-heavy offensive approach. Since passing is more efficient than running (as we discussed in earlier chapters), players who excel in the passing game command market premiums.

The guarantee percentage also varies significantly by position. Quarterbacks and left tackles typically receive higher guarantee percentages because (1) they have more leverage in negotiations due to positional scarcity, and (2) teams are more confident in their evaluation of these positions. Running backs receive lower guarantees because teams worry about injury risk and rapid performance decline with age.

Guaranteed Money Analysis

While APY provides a useful summary, guaranteed money often matters more for understanding true contract value. Guaranteed money represents the minimum a player will earn regardless of injury or performance decline. From the player's perspective, guarantees provide financial security. From the team's perspective, guarantees represent committed capital that limits future flexibility.

The relationship between contract length and guarantee percentage reveals interesting patterns about risk allocation between teams and players. Generally, longer contracts have lower guarantee percentages because teams become less confident in player performance further into the future. However, this relationship varies by position and player quality.

#| label: fig-guaranteed-analysis-r
#| fig-cap: "Guaranteed money percentage by position and contract length"
#| fig-width: 10
#| fig-height: 6
#| message: false
#| warning: false

# Visualize relationship between contract length and guarantees
# Shows how teams manage risk across different contract structures
contracts %>%
  # Focus on major positions with sufficient sample size
  filter(position %in% c("QB", "WR", "RB", "OL", "DL", "LB", "CB", "S")) %>%

  # Create scatter plot with trend lines
  ggplot(aes(x = years, y = guaranteed * 100, color = position)) +

  # Individual contract points with transparency to show density
  geom_point(alpha = 0.4, size = 2) +

  # LOESS smoothing to show non-linear trends
  # se = FALSE removes confidence bands for cleaner visualization
  geom_smooth(method = "loess", se = FALSE, linewidth = 1) +

  # Format y-axis as percentages
  scale_y_continuous(labels = scales::percent_format(scale = 1)) +

  # Show all contract lengths from 1-6 years
  scale_x_continuous(breaks = 1:6) +

  # Use color palette that works for colorblind viewers
  scale_color_brewer(palette = "Set2") +

  labs(
    title = "Contract Guarantee Rates by Position and Length",
    subtitle = "Longer contracts typically have lower guarantee percentages",
    x = "Contract Length (Years)",
    y = "Percentage Guaranteed",
    color = "Position"
  ) +

  theme_minimal() +
  theme(
    plot.title = element_text(face = "bold", size = 14),
    legend.position = "right"
  )

#| label: fig-guaranteed-analysis-py
#| fig-cap: "Guaranteed money percentage by position and contract length - Python"
#| fig-width: 10
#| fig-height: 6
#| message: false
#| warning: false

# Filter to positions with sufficient data
positions = ['QB', 'WR', 'RB', 'OL', 'DL', 'LB', 'CB', 'S']
plot_data = contracts[contracts['position'].isin(positions)].copy()

# Create figure
plt.figure(figsize=(10, 6))

# Plot each position separately to create colored groups
for i, pos in enumerate(positions):
    pos_data = plot_data[plot_data['position'] == pos]

    # Scatter plot with transparency
    plt.scatter(pos_data['years'], pos_data['guaranteed'] * 100,
                alpha=0.4, label=pos, s=50)

plt.xlabel('Contract Length (Years)', fontsize=12)
plt.ylabel('Percentage Guaranteed (%)', fontsize=12)
plt.title('Contract Guarantee Rates by Position and Length\n'
          'Longer contracts typically have lower guarantee percentages',
          fontsize=14, fontweight='bold')
plt.legend(title='Position', bbox_to_anchor=(1.05, 1), loc='upper left')
plt.grid(True, alpha=0.3)
plt.tight_layout()
plt.show()

This visualization reveals several important patterns in how teams structure guarantees. First, we see a general downward trend: longer contracts tend to have lower guarantee percentages. This makes intuitive sense—teams are less willing to commit guaranteed money five years into the future when uncertainty about player performance is high.

Second, we observe position-specific patterns. Quarterbacks tend to maintain high guarantee percentages even on longer contracts, reflecting their unique value and leverage. Running backs show the opposite pattern—even short contracts often have relatively low guarantees due to injury concerns and positional replaceability.

Third, there's significant variation within positions. Some QBs sign contracts with 90%+ guarantees (typically elite players with leverage), while others receive only 40-50% guarantees (often younger players or those with injury histories). This variation represents differences in player quality, team cap situations, and negotiating leverage.

Contract Length and Age Dynamics

Beyond just the guarantee percentage, the interaction between player age and contract length creates interesting dynamics. Teams generally prefer to avoid paying for "decline years"—ages when player performance typically deteriorates. This creates age-specific contract length patterns.

Younger players in their early-to-mid 20s often receive longer contracts because teams expect sustained performance. Players in their late 20s at peak performance may also receive long-term deals, though often structured with outs in later years. Players in their 30s typically receive shorter contracts as teams become wary of age-related decline.

The optimal contract structure balances team risk management with player compensation preferences. Players generally prefer longer contracts with more guarantees (security), while teams prefer shorter contracts with fewer guarantees (flexibility). The final terms reflect relative negotiating leverage, which varies by position, player quality, and market conditions.

Positional Spending Patterns

Understanding how teams allocate cap resources across positions reveals strategic priorities and potential inefficiencies. Some teams invest heavily in quarterback and offensive line, betting that a clean pocket produces efficient offense. Others spread resources more evenly across the roster. Analyzing these allocation patterns helps us understand different roster construction philosophies and identify which approaches correlate with success.

Position-level spending analysis also reveals market inefficiencies. If analytics show that interior defensive line play drives wins more than the market prices it at, teams can gain advantages by over-investing at that position. Conversely, if running backs contribute less to winning than their salaries suggest, teams should spend less at RB.

Team-Level Positional Allocation

To understand team construction strategies, we need to examine how much cap space each team dedicates to each position. This reveals whether teams are following conventional wisdom or taking contrarian approaches that might provide competitive advantages.

#| label: team-positional-spend-r
#| message: false
#| warning: false

# Calculate team spending by position
# This analysis reveals team-level strategic priorities
team_position_spend <- contracts %>%
  group_by(team, position) %>%
  summarise(
    # Total cap hit for this team-position combination
    total_cap = sum(cap_hit_2024),

    # Number of players at this position for this team
    n_players = n(),

    .groups = "drop"
  ) %>%

  # Calculate percentage of team's total cap at each position
  group_by(team) %>%
  mutate(
    # Each position's share of team's total cap spending
    pct_of_cap = total_cap / sum(total_cap) * 100
  ) %>%
  ungroup()

# Display QB spending as example
# QB spending varies widely - some teams have expensive veterans,
# others have cheap rookies, creating massive cap flexibility differences
team_position_spend %>%
  filter(position == "QB") %>%
  arrange(desc(pct_of_cap)) %>%
  head(10) %>%
  gt() %>%
  cols_label(
    team = "Team",
    position = "Position",
    total_cap = "Total Cap Hit",
    n_players = "Players",
    pct_of_cap = "% of Cap"
  ) %>%
  fmt_currency(
    columns = total_cap,
    decimals = 0
  ) %>%
  fmt_number(
    columns = pct_of_cap,
    decimals = 1
  ) %>%
  tab_header(
    title = "Top 10 Teams by QB Cap Spending",
    subtitle = "2024 Season"
  )

#| label: team-positional-spend-py
#| message: false
#| warning: false

# Calculate team spending by position
team_position_spend = (contracts
    .groupby(['team', 'position'])
    .agg(
        total_cap=('cap_hit_2024', 'sum'),
        n_players=('player', 'count')
    )
    .reset_index()
)

# Calculate percentage of each team's total cap
team_totals = (team_position_spend
    .groupby('team')['total_cap']
    .sum()
    .reset_index()
    .rename(columns={'total_cap': 'team_total'})
)

# Merge team totals back to calculate percentages
team_position_spend = team_position_spend.merge(team_totals, on='team')
team_position_spend['pct_of_cap'] = (
    team_position_spend['total_cap'] / team_position_spend['team_total'] * 100
)

# Show QB spending as example
qb_spend = (team_position_spend
    .query("position == 'QB'")
    .sort_values('pct_of_cap', ascending=False)
    .head(10)
)

print("\nTop 10 Teams by QB Cap Spending (2024):")
print("="*70)
for _, row in qb_spend.iterrows():
    print(f"{row['team']:>3} | ${row['total_cap']/1e6:>6.2f}M | "
          f"{row['pct_of_cap']:>5.1f}% of cap | "
          f"{row['n_players']:>2} players")

This analysis reveals one of the most important factors in NFL team building: quarterback cap allocation. Teams with expensive veteran quarterbacks might dedicate 15-20% of their cap to the position, while teams with quarterbacks on rookie contracts might spend only 2-3%. This 12-17% difference—roughly $25-35 million in cap space—represents a massive competitive advantage for teams with cheap QB play.

The Kansas City Chiefs' success from 2018-2020 illustrates this advantage. While Patrick Mahomes was on his rookie contract, the Chiefs could afford elite weapons like Tyreek Hill and Travis Kelce, plus a strong defense. After Mahomes' extension kicked in, the Chiefs had to make difficult choices, letting some players leave and finding value in other areas.

This pattern creates strategic implications for team building:

1. Teams with rookie QBs: Should maximize competitive window by spending aggressively at other positions
2. Teams extending QBs: Must find value contracts and draft well to maintain roster quality
3. Teams with expensive veteran QBs: Need extreme efficiency in non-QB spending

Positional Spending Heat Map

To visualize team allocation strategies across all positions simultaneously, we can create a heat map showing each team's spending distribution. This allows us to identify teams with unusual allocation patterns that might represent contrarian strategies or inefficient spending.

#| label: fig-position-heatmap-r
#| fig-cap: "Team positional spending patterns (% of salary cap)"
#| fig-width: 12
#| fig-height: 8
#| message: false
#| warning: false

# Create heatmap of positional spending
# Shows team-specific allocation strategies
spending_matrix <- team_position_spend %>%
  # Focus on major positions for cleaner visualization
  filter(position %in% c("QB", "RB", "WR", "TE", "OL", "DL", "LB", "CB", "S")) %>%

  # Reshape to wide format for heatmap
  select(team, position, pct_of_cap) %>%
  pivot_wider(names_from = position, values_from = pct_of_cap, values_fill = 0) %>%
  arrange(team)

# Sample 16 teams for cleaner visualization
# Full 32-team heatmap would be too dense
set.seed(42)
sample_teams <- sample(spending_matrix$team, 16)

spending_matrix %>%
  filter(team %in% sample_teams) %>%

  # Convert back to long format for ggplot
  pivot_longer(-team, names_to = "position", values_to = "pct") %>%

  ggplot(aes(x = position, y = team, fill = pct)) +

  # Tile geometry creates heatmap
  geom_tile(color = "white", linewidth = 0.5) +

  # Color scale: white (low) to dark blue (high spending)
  scale_fill_gradient2(
    low = "white",
    mid = "lightblue",
    high = "darkblue",
    midpoint = 10,  # Typical position spending around 10%
    name = "% of Cap"
  ) +

  # Add percentage text in each cell
  geom_text(aes(label = sprintf("%.1f", pct)), size = 3) +

  labs(
    title = "Team Positional Spending Patterns",
    subtitle = "Percentage of salary cap allocated to each position (Sample of 16 teams)",
    x = "Position",
    y = "Team"
  ) +

  theme_minimal() +
  theme(
    plot.title = element_text(face = "bold", size = 14),
    axis.text.x = element_text(angle = 0, hjust = 0.5)
  )

#| label: fig-position-heatmap-py
#| fig-cap: "Team positional spending patterns - Python (% of salary cap)"
#| fig-width: 12
#| fig-height: 8
#| message: false
#| warning: false

# Create heatmap of positional spending
positions = ['QB', 'RB', 'WR', 'TE', 'OL', 'DL', 'LB', 'CB', 'S']

# Pivot to wide format for heatmap
spending_matrix = (team_position_spend
    .query("position in @positions")
    .pivot(index='team', columns='position', values='pct_of_cap')
    .fillna(0)
)

# Sample 16 teams for cleaner visualization
np.random.seed(42)
sample_teams = np.random.choice(spending_matrix.index, 16, replace=False)
spending_sample = spending_matrix.loc[sample_teams, positions]

# Create heatmap using seaborn
plt.figure(figsize=(12, 8))
sns.heatmap(spending_sample,
            annot=True,           # Show values in cells
            fmt='.1f',            # Format as one decimal place
            cmap='Blues',         # Color scheme
            cbar_kws={'label': '% of Cap'},
            linewidths=0.5)       # Add gridlines

plt.title('Team Positional Spending Patterns\n'
          'Percentage of salary cap allocated to each position (Sample of 16 teams)',
          fontsize=14, fontweight='bold', pad=20)
plt.xlabel('Position', fontsize=12)
plt.ylabel('Team', fontsize=12)
plt.tight_layout()
plt.show()

The heatmap visualization reveals interesting patterns in team construction. Some teams show heavy concentration in one or two positions (high-risk, high-reward strategies), while others spread spending more evenly (conservative, balanced approaches).

Looking across teams, we can identify different strategic archetypes:

Pass-First Teams: High spending at QB, WR, and OL (pass protection). Lower spending on RB and run-stopping positions. These teams bet on passing efficiency driving wins.

Balanced Teams: Relatively even distribution across positions. These teams don't make strong bets on specific positions being more valuable.

Defense-First Teams: Higher spending on DL, CB, and S. These teams bet on defense winning championships and controlling games.

Contrarian Teams: Unusual spending patterns that deviate from league norms. These might represent analytical insights (investing in undervalued positions) or strategic mistakes (overpaying positions with limited impact).

The key question for analysts: which spending patterns correlate with winning? Teams that can identify undervalued positions and allocate accordingly gain systematic advantages in roster construction.

Market Value Models

Building statistical models to predict market value allows us to identify systematically over- or under-paid players. These models use player characteristics (age, experience, position) and performance metrics to estimate expected contract value. Players earning significantly less than expected represent value contracts, while those earning more than expected are potential overpays.

Market value modeling serves several purposes:

1. Contract negotiations: Provides objective basis for offer amounts
2. Value identification: Highlights players providing excess value
3. Market tracking: Shows how positional values evolve over time
4. Decision support: Informs extension timing and free agent targeting

The key challenge is separating player quality from market conditions. A player might be "overpaid" not because he's bad, but because he signed at market peak or had leverage from multiple bidders. Conversely, "value contracts" often reflect signing timing (before breakout) rather than analytical genius.

Building a Market Value Model

We start with a simple linear regression model predicting log(APY) based on player characteristics. Using logarithmic transformation helps because contract values are log-normally distributed (most players earn modest amounts, few earn enormous amounts).

$$ \log(\text{APY}_i) = \beta_0 + \beta_1 \text{Age}_i + \beta_2 \text{Age}^2_i + \beta_3 \text{Experience}_i + \beta_4 \text{Guaranteed}_i + \epsilon_i $$

The model includes age and age-squared to capture non-linear age effects (value peaks in late 20s, then declines). Experience captures market seniority effects separate from age. Guaranteed percentage proxies for player quality—better players negotiate higher guarantees.

#| label: market-value-model-r
#| message: false
#| warning: false

# Build market value model for quarterbacks
# QBs chosen because position is homogeneous (same role across teams)
# and market is liquid (frequent transactions provide price discovery)

qb_model_data <- contracts %>%
  filter(position == "QB") %>%
  mutate(
    # Log transform APY for better model fit
    # Log transformation handles right-skewed distribution
    log_apy = log(apy),

    # Age-squared term captures non-linear age effects
    # Peak performance typically late 20s, decline after 30
    age_squared = age^2
  )

# Fit linear model
# Predicts log(APY) from age, experience, guarantees
qb_market_model <- lm(
  log_apy ~ age + age_squared + experience + guaranteed,
  data = qb_model_data
)

# Display model summary
# Look for significant coefficients and R-squared
summary(qb_market_model)

# Generate predictions and calculate value over market
qb_model_data <- qb_model_data %>%
  mutate(
    # Predicted log(APY) from model
    predicted_log_apy = predict(qb_market_model),

    # Transform back to dollar scale
    predicted_apy = exp(predicted_log_apy),

    # Difference between actual and predicted (in dollars)
    value_over_market = apy - predicted_apy,

    # Percentage difference (easier to interpret)
    value_pct = (apy - predicted_apy) / predicted_apy * 100
  )

cat("\nModel Performance:\n")
cat("R-squared:", summary(qb_market_model)$r.squared, "\n")
cat("RMSE:", sqrt(mean((qb_model_data$log_apy - qb_model_data$predicted_log_apy)^2)), "\n")

#| label: market-value-model-py
#| message: false
#| warning: false

from sklearn.metrics import r2_score, mean_squared_error

# Build market value model for QBs
qb_model_data = contracts[contracts['position'] == 'QB'].copy()

# Transform and create features
qb_model_data['log_apy'] = np.log(qb_model_data['apy'])
qb_model_data['age_squared'] = qb_model_data['age'] ** 2

# Prepare feature matrix and target
X = qb_model_data[['age', 'age_squared', 'experience', 'guaranteed']]
y = qb_model_data['log_apy']

# Fit linear regression model
qb_market_model = LinearRegression()
qb_market_model.fit(X, y)

# Generate predictions
qb_model_data['predicted_log_apy'] = qb_market_model.predict(X)
qb_model_data['predicted_apy'] = np.exp(qb_model_data['predicted_log_apy'])
qb_model_data['value_over_market'] = (qb_model_data['apy'] -
                                       qb_model_data['predicted_apy'])
qb_model_data['value_pct'] = (qb_model_data['value_over_market'] /
                               qb_model_data['predicted_apy'] * 100)

# Model performance metrics
r2 = r2_score(y, qb_model_data['predicted_log_apy'])
rmse = np.sqrt(mean_squared_error(y, qb_model_data['predicted_log_apy']))

print(f"\nQB Market Value Model:")
print(f"R-squared: {r2:.3f}")
print(f"RMSE: {rmse:.3f}")
print(f"\nCoefficients:")
for feat, coef in zip(X.columns, qb_market_model.coef_):
    print(f"  {feat}: {coef:.4f}")
print(f"  Intercept: {qb_market_model.intercept_:.4f}")

The model reveals several interesting patterns in QB market pricing. The age coefficient shows how age affects market value, while age-squared captures the inverted-U shape of age curves. Experience has a separate effect from age—two 28-year-olds with different NFL experience might command different salaries.

The R-squared value indicates how much of contract variation the model explains. A moderate R-squared (0.3-0.5) suggests other factors beyond age, experience, and guarantees drive contracts—things like recent performance, playoff success, team cap situations, and negotiation leverage. This residual variation is where we find value contracts and overpays.

One limitation of this simple model: it doesn't include performance metrics. A more sophisticated approach would incorporate EPA per play, completion percentage over expectation, or other objective performance measures. However, even this simple model provides useful insights by establishing baseline market expectations.

Identifying Value Contracts and Overpays

The residuals from our market value model—the difference between actual and predicted APY—identify players earning significantly more or less than market expectations. Large negative residuals indicate value contracts (player earning less than expected), while large positive residuals indicate potential overpays.

#| label: value-contracts-r
#| message: false
#| warning: false

# Identify biggest value contracts (most underpaid)
# Negative value_pct means earning less than predicted
value_contracts <- qb_model_data %>%
  filter(!is.na(value_pct)) %>%
  arrange(value_pct) %>%
  select(player, team, age, apy, predicted_apy, value_over_market, value_pct) %>%
  head(10)

# Identify biggest overpays (most overpaid)
# Positive value_pct means earning more than predicted
overpays <- qb_model_data %>%
  filter(!is.na(value_pct)) %>%
  arrange(desc(value_pct)) %>%
  select(player, team, age, apy, predicted_apy, value_over_market, value_pct) %>%
  head(10)

# Display value contracts in formatted table
value_contracts %>%
  gt() %>%
  cols_label(
    player = "Player",
    team = "Team",
    age = "Age",
    apy = "Actual APY",
    predicted_apy = "Expected APY",
    value_over_market = "Value Over Market",
    value_pct = "% Over Market"
  ) %>%
  fmt_currency(
    columns = c(apy, predicted_apy, value_over_market),
    decimals = 0
  ) %>%
  fmt_number(
    columns = value_pct,
    decimals = 1
  ) %>%
  tab_header(
    title = "Top 10 Value QB Contracts",
    subtitle = "Most underpaid relative to market model"
  ) %>%
  tab_style(
    style = cell_fill(color = "lightgreen"),
    locations = cells_body(columns = value_pct)
  )

#| label: value-contracts-py
#| message: false
#| warning: false

# Identify value contracts (underpaid players)
value_contracts = (qb_model_data
    .dropna(subset=['value_pct'])
    .nsmallest(10, 'value_pct')
    [['player', 'team', 'age', 'apy', 'predicted_apy',
      'value_over_market', 'value_pct']]
)

# Identify overpays (overpaid players)
overpays = (qb_model_data
    .dropna(subset=['value_pct'])
    .nlargest(10, 'value_pct')
    [['player', 'team', 'age', 'apy', 'predicted_apy',
      'value_over_market', 'value_pct']]
)

print("\nTop 10 Value QB Contracts (Underpaid):")
print("="*90)
for _, row in value_contracts.iterrows():
    print(f"{row['player']:>10} ({row['team']}) | "
          f"Age: {row['age']:>2} | "
          f"Actual: ${row['apy']/1e6:>5.1f}M | "
          f"Expected: ${row['predicted_apy']/1e6:>5.1f}M | "
          f"Value: {row['value_pct']:>6.1f}%")

Value contracts represent competitive advantages. A quarterback earning $20M below market rate provides the team with $20M in cap space to invest elsewhere—roughly enough to sign an elite pass rusher or top cornerback. This is why teams with rookie quarterbacks have such an advantage: they're getting elite QB play at a fraction of market cost.

The Buffalo Bills from 2018-2020 provide a clear example. Josh Allen on his rookie contract ($6M APY) was producing like a $35M QB, providing $29M in excess value. The Bills used this excess cap space to build a strong defense and surround Allen with weapons, reaching the AFC Championship Game. Once Allen's extension kicked in at $43M APY, the Bills faced tougher roster decisions.

Overpays also matter strategically. A quarterback earning $15M more than expected represents $15M that can't be spent improving the roster. However, some "overpays" are strategic necessity—if a team has a franchise QB, they must pay market rate (or above) to retain him, because replacing QB play is extremely difficult.

Market Efficiency Analysis

Examining market efficiency across positions reveals whether certain position markets are systematically mispriced. If models consistently over-predict or under-predict certain positions, it suggests the market values those positions differently than observable characteristics would predict.

This analysis has important strategic implications. If analytics suggest interior defensive linemen are undervalued relative to their impact on winning, teams should invest more heavily at that position. If running backs are overvalued, teams should minimize RB spending and find cheap alternatives.

Positional Market Efficiency

We can build market value models for each position and compare model fit. Positions where models fit poorly suggest more market noise and potential opportunities for analytical advantage.

#| label: fig-market-efficiency-r
#| fig-cap: "Market value vs actual value by position"
#| fig-width: 10
#| fig-height: 8
#| message: false
#| warning: false

# Build market value models for each major position
# Compare model fit across positions to identify market efficiency
position_models <- contracts %>%
  # Focus on positions with sufficient sample size and clear roles
  filter(position %in% c("QB", "WR", "RB", "OL", "DL", "LB", "CB")) %>%

  # Log-transform APY for modeling
  mutate(log_apy = log(apy)) %>%

  # Group by position to build position-specific models
  group_by(position) %>%

  # Only model positions with 20+ observations
  filter(n() >= 20) %>%

  # Nest data for each position
  nest() %>%

  # Fit model for each position
  mutate(
    # Linear regression: log(APY) ~ age + experience + guarantees
    model = map(data, ~lm(log_apy ~ age + experience + guaranteed, data = .x)),

    # Generate predictions for each position
    predictions = map2(model, data, ~{
      .y %>%
        mutate(
          predicted_log_apy = predict(.x),
          predicted_apy = exp(predicted_log_apy),
          residual = apy - predicted_apy
        )
    })
  ) %>%

  # Unnest results
  select(position, predictions) %>%
  unnest(predictions)

# Visualize actual vs predicted for each position
# Points along diagonal indicate good model fit
# Scatter indicates market inefficiency or unmeasured factors
position_models %>%
  ggplot(aes(x = predicted_apy, y = apy)) +

  # Scatter plot of actual vs predicted
  geom_point(alpha = 0.5, color = "steelblue") +

  # Diagonal line represents perfect prediction
  geom_abline(slope = 1, intercept = 0, linetype = "dashed", color = "red") +

  # Separate panel for each position
  facet_wrap(~position, scales = "free", ncol = 3) +

  # Format axes as millions
  scale_x_continuous(labels = scales::dollar_format(scale = 1e-6, suffix = "M")) +
  scale_y_continuous(labels = scales::dollar_format(scale = 1e-6, suffix = "M")) +

  labs(
    title = "Market Value Model Fit by Position",
    subtitle = "Actual APY vs Predicted APY (red line = perfect prediction)",
    x = "Predicted APY",
    y = "Actual APY"
  ) +

  theme_minimal() +
  theme(
    plot.title = element_text(face = "bold", size = 14),
    strip.text = element_text(face = "bold")
  )

#| label: fig-market-efficiency-py
#| fig-cap: "Market value vs actual value by position - Python"
#| fig-width: 10
#| fig-height: 8
#| message: false
#| warning: false

# Build position-specific market models
positions_to_model = ['QB', 'WR', 'RB', 'OL', 'DL', 'LB', 'CB']
position_predictions = []

for pos in positions_to_model:
    # Filter to position
    pos_data = contracts[contracts['position'] == pos].copy()

    # Skip if insufficient sample
    if len(pos_data) < 20:
        continue

    # Prepare features
    pos_data['log_apy'] = np.log(pos_data['apy'])
    X = pos_data[['age', 'experience', 'guaranteed']]
    y = pos_data['log_apy']

    # Fit model
    model = LinearRegression()
    model.fit(X, y)

    # Generate predictions
    pos_data['predicted_log_apy'] = model.predict(X)
    pos_data['predicted_apy'] = np.exp(pos_data['predicted_log_apy'])
    pos_data['residual'] = pos_data['apy'] - pos_data['predicted_apy']

    position_predictions.append(pos_data)

# Combine all position predictions
all_predictions = pd.concat(position_predictions, ignore_index=True)

# Create subplot for each position
fig, axes = plt.subplots(3, 3, figsize=(12, 10))
axes = axes.flatten()

for i, pos in enumerate(positions_to_model):
    if i >= len(axes):
        break

    pos_data = all_predictions[all_predictions['position'] == pos]

    # Scatter plot
    axes[i].scatter(pos_data['predicted_apy']/1e6, pos_data['apy']/1e6,
                    alpha=0.5, color='steelblue')

    # Perfect prediction line
    min_val = min(pos_data['predicted_apy'].min(), pos_data['apy'].min()) / 1e6
    max_val = max(pos_data['predicted_apy'].max(), pos_data['apy'].max()) / 1e6
    axes[i].plot([min_val, max_val], [min_val, max_val],
                 'r--', alpha=0.7, label='Perfect prediction')

    axes[i].set_xlabel('Predicted APY ($M)', fontsize=9)
    axes[i].set_ylabel('Actual APY ($M)', fontsize=9)
    axes[i].set_title(pos, fontsize=11, fontweight='bold')
    axes[i].grid(True, alpha=0.3)

# Remove extra subplots
for i in range(len(positions_to_model), len(axes)):
    fig.delaxes(axes[i])

plt.suptitle('Market Value Model Fit by Position\n'
             'Actual APY vs Predicted APY (red line = perfect prediction)',
             fontsize=14, fontweight='bold')
plt.tight_layout()
plt.show()

These visualizations reveal interesting differences in market efficiency across positions. Some positions show tight clustering around the diagonal (good model fit), while others show more scatter (poor model fit).

Positions with good model fit suggest efficient markets—contracts are predictable based on age, experience, and leverage. Positions with poor model fit suggest either (1) important unmeasured factors affecting contracts, or (2) market inefficiency creating opportunity.

For example, if offensive line contracts show high scatter, it might indicate teams struggle to value OL properly, creating opportunities for teams with superior OL evaluation. If quarterback contracts cluster tightly, it suggests the QB market is efficient with less room for analytical arbitrage.

The residual patterns also matter. If all underpaid players at a position are young and overpaid players are old, it suggests the market undervalues youth. If a specific team consistently gets value contracts at a position, they might have superior evaluation or development.

Position Market Premium

Beyond modeling individual contracts, we can quantify the market premium for each position while controlling for player characteristics. This reveals which positions command the highest salaries independent of age, experience, or guarantees.

#| label: position-premium-r
#| message: false
#| warning: false

# Calculate market premium by position controlling for age and experience
# Uses regression with position dummy variables
position_premium <- contracts %>%
  filter(position %in% c("QB", "WR", "RB", "TE", "OL", "DL", "LB", "CB", "S")) %>%
  mutate(log_apy = log(apy))

# Fit model with position indicators
# Position coefficients show premium relative to reference position
premium_model <- lm(
  log_apy ~ position + age + experience + guaranteed,
  data = position_premium
)

# Extract and interpret position effects
position_effects <- broom::tidy(premium_model) %>%
  filter(str_detect(term, "position")) %>%
  mutate(
    # Clean position names
    position = str_remove(term, "position"),

    # Convert log coefficient to percentage premium
    # exp(coef) - 1 gives percentage change
    premium_pct = (exp(estimate) - 1) * 100
  ) %>%

  # Add reference category (omitted from regression)
  bind_rows(
    tibble(
      term = "position(Reference)",
      position = "CB",  # Reference category
      estimate = 0,
      premium_pct = 0
    )
  ) %>%
  arrange(desc(premium_pct))

# Display position premiums
position_effects %>%
  select(position, premium_pct) %>%
  gt() %>%
  cols_label(
    position = "Position",
    premium_pct = "Market Premium (%)"
  ) %>%
  fmt_number(
    columns = premium_pct,
    decimals = 1
  ) %>%
  tab_header(
    title = "Position Market Premium",
    subtitle = "% premium over reference position (controlling for age, experience, guarantees)"
  )

#| label: position-premium-py
#| message: false
#| warning: false

from sklearn.preprocessing import LabelEncoder

# Filter to positions to analyze
positions_to_analyze = ['QB', 'WR', 'RB', 'TE', 'OL', 'DL', 'LB', 'CB', 'S']
position_premium = contracts[contracts['position'].isin(positions_to_analyze)].copy()
position_premium['log_apy'] = np.log(position_premium['apy'])

# Create dummy variables for positions
# This allows us to estimate position-specific effects
position_dummies = pd.get_dummies(position_premium['position'], prefix='pos')

# Combine position dummies with other features
X = pd.concat([
    position_dummies,
    position_premium[['age', 'experience', 'guaranteed']]
], axis=1)
y = position_premium['log_apy']

# Fit regression model
premium_model = LinearRegression()
premium_model.fit(X, y)

# Extract position effects from coefficients
position_cols = [col for col in X.columns if col.startswith('pos_')]
position_effects = []

for i, col in enumerate(position_cols):
    pos_name = col.replace('pos_', '')
    coef = premium_model.coef_[i]

    # Convert log coefficient to percentage
    premium_pct = (np.exp(coef) - 1) * 100

    position_effects.append({
        'position': pos_name,
        'coefficient': coef,
        'premium_pct': premium_pct
    })

# Sort by premium
position_effects_df = (pd.DataFrame(position_effects)
    .sort_values('premium_pct', ascending=False)
)

print("\nPosition Market Premium:")
print("(% premium controlling for age, experience, guarantees)")
print("="*50)
for _, row in position_effects_df.iterrows():
    print(f"{row['position']:>3} | {row['premium_pct']:>+6.1f}%")

This analysis quantifies exactly how much premium each position commands after accounting for player age, experience, and guarantees. A position with a +50% premium means players at that position earn 50% more than the reference position, all else equal.

The results typically show:

• Quarterbacks: Massive premium (100%+) over other positions
• Pass rushers/LTs: Significant premium (30-50%) reflecting scarcity
• WR/CB: Moderate premium (10-30%) for pass-game importance
• RB/LB: Neutral or negative premium despite traditional importance

These premiums reveal market consensus about positional value. Teams can gain advantages by identifying gaps between market premiums and actual value to wins. If the market pays a 40% premium for position X, but analytics show position Y contributes equally to winning, smart teams invest more in position Y.

Cap Space Allocation Optimization

The ultimate application of salary cap analytics is roster optimization: constructing the best possible team within cap constraints. This is a classic constrained optimization problem—maximize expected performance subject to budget and roster constraints.

While real NFL roster construction involves many factors beyond raw optimization (chemistry, coaching fit, injury risk, future considerations), the optimization framework provides a useful baseline for evaluating allocation decisions.

Portfolio Optimization Approach

We can frame roster construction as portfolio optimization, familiar from finance. Instead of assets (stocks, bonds), we're selecting players. Instead of returns, we're maximizing expected performance (EPA). Instead of budget, we're constrained by salary cap.

The objective function:

$$ \max_{\mathbf{x}} \sum_{i=1}^{N} x_i \cdot \text{EPA}_i $$

Subject to constraints:

$$ \sum_{i=1}^{N} x_i \cdot \text{Salary}_i \leq \text{Cap} $$

$$ \sum_{i \in P} x_i = \text{Required}_P \quad \forall P \in \text{Positions} $$

Where $x_i \in \{0, 1\}$ indicates whether to select player $i$. Additional constraints would include roster size limits, position minimums/maximums, and possibly chemistry or scheme fit requirements.

#| label: roster-optimization-r
#| message: false
#| warning: false
#| eval: false

# Simplified roster optimization example
# Real NFL optimization would include many more constraints and considerations
# This demonstrates the basic approach

library(lpSolve)

# Create player pool for starting offense
# In practice, would use much larger pool with real performance data
player_pool <- contracts %>%
  filter(position %in% c("QB", "RB", "WR", "TE", "OL")) %>%
  sample_n(50) %>%
  mutate(
    # Simulate EPA contribution
    # Better values for cheaper players (creating value)
    # In practice, use actual EPA data from play-by-play
    epa_contribution = rnorm(n(), mean = 20, sd = 10) *
                       (mean(cap_hit_2024) / cap_hit_2024)
  )

# Define optimization problem
n_players <- nrow(player_pool)

# Objective: maximize total EPA contribution
objective <- player_pool$epa_contribution

# Budget constraint
budget_constraint <- player_pool$cap_hit_2024

# Position requirements (simplified 11-man offense)
# 1 QB, 2 RB, 3 WR, 1 TE, 4 OL
position_constraints <- rbind(
  as.numeric(player_pool$position == "QB"),
  as.numeric(player_pool$position == "RB"),
  as.numeric(player_pool$position == "WR"),
  as.numeric(player_pool$position == "TE"),
  as.numeric(player_pool$position == "OL")
)

# Combine constraints into matrix
const_mat <- rbind(
  budget_constraint,
  position_constraints
)

# Constraint directions and right-hand sides
const_dir <- c("<=", "=", "=", "=", "=", "=")
const_rhs <- c(
  50e6,  # $50M budget for these positions
  1,     # 1 QB
  2,     # 2 RB
  3,     # 3 WR
  1,     # 1 TE
  4      # 4 OL
)

# Solve integer programming problem
solution <- lp(
  "max",              # Maximize objective
  objective,          # EPA contribution
  const_mat,          # Constraint matrix
  const_dir,          # Constraint directions
  const_rhs,          # Constraint values
  all.bin = TRUE      # Binary variables (select or not)
)

# Extract selected players
selected_players <- player_pool[solution$solution == 1, ]

cat("Optimal Lineup:\n")
cat("Total EPA:", solution$objval, "\n")
cat("Total Cost:", scales::dollar(sum(selected_players$cap_hit_2024)), "\n\n")

# Display lineup
selected_players %>%
  select(player, position, team, cap_hit_2024, epa_contribution) %>%
  arrange(position) %>%
  print()

#| label: roster-optimization-py
#| message: false
#| warning: false

from scipy.optimize import linprog

# Simplified roster optimization
# Demonstrates approach, not production-ready system
np.random.seed(42)

# Create player pool
player_pool = contracts[
    contracts['position'].isin(['QB', 'RB', 'WR', 'TE', 'OL'])
].sample(50).copy()

# Simulate EPA contribution (inverse to cost creates value opportunities)
player_pool['epa_contribution'] = (
    np.random.normal(20, 10, len(player_pool)) *
    (player_pool['cap_hit_2024'].mean() / player_pool['cap_hit_2024'])
)

# Objective: maximize EPA (negative for minimization algorithm)
c = -player_pool['epa_contribution'].values

# Inequality constraint: budget
A_ub = [player_pool['cap_hit_2024'].values]
b_ub = [50e6]  # $50M budget

# Equality constraints: position requirements
A_eq = [
    (player_pool['position'] == 'QB').astype(int).values,
    (player_pool['position'] == 'RB').astype(int).values,
    (player_pool['position'] == 'WR').astype(int).values,
    (player_pool['position'] == 'TE').astype(int).values,
    (player_pool['position'] == 'OL').astype(int).values,
]
b_eq = [1, 2, 3, 1, 4]  # Position requirements

# Binary constraints (0 or 1)
bounds = [(0, 1) for _ in range(len(player_pool))]

# Solve linear program
# Note: linprog allows fractional solutions; would need integer programming
# for true binary selection (using package like PuLP or Gurobi)
result = linprog(
    c, A_ub=A_ub, b_ub=b_ub, A_eq=A_eq, b_eq=b_eq,
    bounds=bounds, method='highs'
)

if result.success:
    # Round to binary for approximate solution
    selected = np.round(result.x)
    selected_players = player_pool[selected == 1].copy()

    print("\nOptimal Lineup (Approximation):")
    print("="*70)
    print(f"Total EPA: {-result.fun:.1f}")
    print(f"Total Cost: ${selected_players['cap_hit_2024'].sum():,.0f}")
    print(f"\nSelected Players:")
    print("-"*70)

    # Display by position
    for pos in ['QB', 'RB', 'WR', 'TE', 'OL']:
        pos_players = selected_players[selected_players['position'] == pos]
        if len(pos_players) > 0:
            print(f"\n{pos}:")
            for _, p in pos_players.iterrows():
                print(f"  {p['player']:>12} | "
                      f"${p['cap_hit_2024']/1e6:>5.1f}M | "
                      f"EPA: {p['epa_contribution']:>5.1f}")

This optimization approach provides a quantitative framework for roster construction decisions. While simplified, it demonstrates how mathematical optimization can identify efficient allocations that maximize performance within budget constraints.

Real NFL roster optimization would include many additional considerations:

• Multiple years: Optimize across 2-3 year window, not just current season
• Uncertainty: Model player performance uncertainty and injury risk
• Depth: Include requirements for backup players
• Chemistry: Account for position combinations that work well together
• Draft: Incorporate draft picks as cheap talent sources
• Development: Model player improvement/decline trajectories

Despite these complexities, the basic framework remains valuable. It forces explicit articulation of goals (maximize performance), constraints (cap, roster spots), and trade-offs (spending here means not spending there).

Age and Contract Length Analysis

Player age fundamentally shapes contract structure and value. Understanding age curves—how performance changes with age—is essential for optimal contract length decisions. Sign a player too long into their decline years, and the team pays for diminished production. Sign too short, and the player leaves during prime years.

Age Curves by Position

Different positions age differently. Quarterbacks tend to maintain performance longer than running backs. Offensive linemen peak later than skill position players. These position-specific age curves should inform contract length decisions.

#| label: fig-age-curves-r
#| fig-cap: "Contract APY by age and position"
#| fig-width: 10
#| fig-height: 6
#| message: false
#| warning: false

# Visualize how contract value varies with age across positions
# Shows market perception of age-based value curves
contracts %>%
  filter(position %in% c("QB", "WR", "RB", "OL", "DL", "LB")) %>%
  filter(age >= 22, age <= 35) %>%

  ggplot(aes(x = age, y = apy / 1e6, color = position)) +

  # Individual contracts
  geom_point(alpha = 0.3) +

  # LOESS smoothing to show age trends
  # se = TRUE adds confidence bands
  geom_smooth(method = "loess", se = TRUE, linewidth = 1.2) +

  # Format y-axis as millions
  scale_y_continuous(labels = scales::dollar_format(suffix = "M")) +

  scale_color_brewer(palette = "Set2") +

  labs(
    title = "Contract Value by Age and Position",
    subtitle = "APY tends to peak in late 20s, then decline",
    x = "Age",
    y = "Average Annual Value",
    color = "Position"
  ) +

  theme_minimal() +
  theme(
    plot.title = element_text(face = "bold", size = 14),
    legend.position = "right"
  )