Salary Cap Analysis Code Examples

Python Example: Salary Cap Analysis

"""
NBA Salary Cap Analysis Tools
Analyze team cap situations, calculate tax bills, model cap scenarios

Install: pip install pandas numpy matplotlib requests beautifulsoup4
"""

import pandas as pd
import numpy as np
import matplotlib.pyplot as plt
import seaborn as sns
from typing import Dict, List, Tuple

# 2023-24 Salary Cap Constants
SALARY_CAP = 136_021_000
LUXURY_TAX = 165_294_000
FIRST_APRON = 172_346_000
SECOND_APRON = 182_794_000
MIN_TEAM_SALARY = 122_418_900

# Tax Rates (Non-Repeater)
TAX_RATES = [
    (5_000_000, 1.50),
    (10_000_000, 1.75),
    (15_000_000, 2.50),
    (20_000_000, 3.25),
    (float('inf'), 3.75)
]

# Repeater Tax Rates
REPEATER_TAX_RATES = [
    (5_000_000, 2.50),
    (10_000_000, 2.75),
    (15_000_000, 3.50),
    (20_000_000, 4.25),
    (float('inf'), 4.75)
]

# Maximum Salaries by Years of Service
MAX_SALARIES = {
    '0-6': 0.25 * SALARY_CAP,
    '7-9': 0.30 * SALARY_CAP,
    '10+': 0.35 * SALARY_CAP
}

# Minimum Salaries by Years of Service (2023-24)
MIN_SALARIES = {
    0: 1_119_563,
    1: 1_836_090,
    2: 1_988_965,
    3: 2_087_519,
    4: 2_162_606,
    5: 2_346_614,
    6: 2_530_680,
    7: 2_714_746,
    8: 2_898_812,
    9: 2_953_694,
    10: 3_196_448
}


def calculate_luxury_tax(team_salary: float, is_repeater: bool = False) -> Dict:
    """
    Calculate luxury tax bill for a team

    Args:
        team_salary: Total team salary
        is_repeater: Whether team is repeater tax offender

    Returns:
        Dictionary with tax details
    """
    if team_salary <= LUXURY_TAX:
        return {
            'overage': 0,
            'tax_bill': 0,
            'total_cost': team_salary,
            'effective_rate': 0
        }

    overage = team_salary - LUXURY_TAX
    tax_bill = 0

    rates = REPEATER_TAX_RATES if is_repeater else TAX_RATES

    previous_threshold = 0
    for threshold, rate in rates:
        if overage <= previous_threshold:
            break

        taxable_amount = min(overage, threshold) - previous_threshold
        tax_bill += taxable_amount * rate

        previous_threshold = threshold

    total_cost = team_salary + tax_bill
    effective_rate = tax_bill / overage if overage > 0 else 0

    return {
        'overage': overage,
        'tax_bill': tax_bill,
        'total_cost': total_cost,
        'effective_rate': effective_rate,
        'repeater': is_repeater
    }


def calculate_max_salary(years_of_service: int, supermax: bool = False) -> float:
    """
    Calculate maximum salary for a player

    Args:
        years_of_service: Player's years in NBA
        supermax: Whether player qualifies for supermax (35%)

    Returns:
        Maximum salary amount
    """
    if supermax:
        return 0.35 * SALARY_CAP

    if years_of_service <= 6:
        return MAX_SALARIES['0-6']
    elif years_of_service <= 9:
        return MAX_SALARIES['7-9']
    else:
        return MAX_SALARIES['10+']


def calculate_cap_hold(previous_salary: float, bird_rights: str = 'full') -> float:
    """
    Calculate cap hold for free agent

    Args:
        previous_salary: Player's previous season salary
        bird_rights: 'full', 'early', or 'non'

    Returns:
        Cap hold amount
    """
    if bird_rights == 'full':
        percentage = 1.90
    elif bird_rights == 'early':
        percentage = 1.30
    else:  # non-bird
        percentage = 1.20

    cap_hold = previous_salary * percentage

    # Cap hold cannot exceed maximum salary
    max_salary = calculate_max_salary(10)  # Use highest max as ceiling

    return min(cap_hold, max_salary)


def project_contract_value(
    starting_salary: float,
    years: int,
    annual_raise: float = 0.08
) -> pd.DataFrame:
    """
    Project multi-year contract values

    Args:
        starting_salary: First year salary
        years: Contract length
        annual_raise: Annual raise percentage (default 8% for Bird)

    Returns:
        DataFrame with year-by-year breakdown
    """
    contract = []

    for year in range(1, years + 1):
        salary = starting_salary * (1 + annual_raise) ** (year - 1)
        contract.append({
            'Year': year,
            'Salary': salary,
            'Cumulative': sum([starting_salary * (1 + annual_raise) ** i
                             for i in range(year)])
        })

    df = pd.DataFrame(contract)
    df['Total_Value'] = df['Cumulative'].iloc[-1]

    return df


def analyze_team_cap_situation(roster_salaries: List[float]) -> Dict:
    """
    Analyze a team's cap situation

    Args:
        roster_salaries: List of player salaries

    Returns:
        Dictionary with cap analysis
    """
    total_salary = sum(roster_salaries)

    cap_space = max(0, SALARY_CAP - total_salary)
    room_exception = 7_700_000 if cap_space > 0 else 0

    # Determine available exceptions
    if total_salary < LUXURY_TAX:
        mle = 12_405_000  # Non-taxpayer MLE
        bae = 4_500_000
    elif total_salary < FIRST_APRON:
        mle = 5_000_000  # Taxpayer MLE
        bae = 0
    else:
        mle = 5_000_000
        bae = 0

    tax_info = calculate_luxury_tax(total_salary)

    return {
        'total_salary': total_salary,
        'cap_space': cap_space,
        'under_cap': total_salary < SALARY_CAP,
        'over_tax': total_salary > LUXURY_TAX,
        'over_first_apron': total_salary > FIRST_APRON,
        'over_second_apron': total_salary > SECOND_APRON,
        'available_mle': mle,
        'available_bae': bae,
        'room_exception': room_exception,
        'tax_bill': tax_info['tax_bill'],
        'total_cost': tax_info['total_cost']
    }


def visualize_luxury_tax_brackets():
    """
    Create visualization of luxury tax brackets
    """
    overages = np.linspace(0, 50_000_000, 1000)
    tax_bills_regular = []
    tax_bills_repeater = []

    for overage in overages:
        salary = LUXURY_TAX + overage

        regular = calculate_luxury_tax(salary, is_repeater=False)
        repeater = calculate_luxury_tax(salary, is_repeater=True)

        tax_bills_regular.append(regular['tax_bill'])
        tax_bills_repeater.append(repeater['tax_bill'])

    fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(15, 6))

    # Tax bill visualization
    ax1.plot(overages / 1e6, np.array(tax_bills_regular) / 1e6,
             label='Non-Repeater', linewidth=2, color='#1f77b4')
    ax1.plot(overages / 1e6, np.array(tax_bills_repeater) / 1e6,
             label='Repeater', linewidth=2, color='#ff7f0e')
    ax1.set_xlabel('Overage (Millions)', fontsize=12)
    ax1.set_ylabel('Tax Bill (Millions)', fontsize=12)
    ax1.set_title('Luxury Tax Bill by Overage Amount', fontsize=14, fontweight='bold')
    ax1.legend()
    ax1.grid(True, alpha=0.3)

    # Total cost visualization
    total_cost_regular = (LUXURY_TAX + overages + np.array(tax_bills_regular)) / 1e6
    total_cost_repeater = (LUXURY_TAX + overages + np.array(tax_bills_repeater)) / 1e6

    ax2.plot(overages / 1e6, total_cost_regular,
             label='Non-Repeater', linewidth=2, color='#1f77b4')
    ax2.plot(overages / 1e6, total_cost_repeater,
             label='Repeater', linewidth=2, color='#ff7f0e')
    ax2.axhline(y=LUXURY_TAX / 1e6, color='red', linestyle='--',
                linewidth=1, label='Tax Threshold')
    ax2.set_xlabel('Overage (Millions)', fontsize=12)
    ax2.set_ylabel('Total Cost (Millions)', fontsize=12)
    ax2.set_title('Total Team Cost (Salary + Tax)', fontsize=14, fontweight='bold')
    ax2.legend()
    ax2.grid(True, alpha=0.3)

    plt.tight_layout()
    plt.savefig('luxury_tax_analysis.png', dpi=300, bbox_inches='tight')
    plt.show()


def compare_signing_scenarios(
    player_salary: float,
    current_team_salary: float,
    is_repeater: bool = False
) -> pd.DataFrame:
    """
    Compare cost of signing player under different tax scenarios

    Args:
        player_salary: Proposed player salary
        current_team_salary: Current team salary before signing
        is_repeater: Repeater tax status

    Returns:
        DataFrame comparing scenarios
    """
    scenarios = []

    # Scenario 1: Don't sign player
    baseline = calculate_luxury_tax(current_team_salary, is_repeater)
    scenarios.append({
        'Scenario': 'No Signing',
        'Team_Salary': current_team_salary,
        'Tax_Bill': baseline['tax_bill'],
        'Total_Cost': baseline['total_cost'],
        'Marginal_Cost': 0
    })

    # Scenario 2: Sign player
    new_salary = current_team_salary + player_salary
    with_player = calculate_luxury_tax(new_salary, is_repeater)
    marginal_cost = with_player['total_cost'] - baseline['total_cost']

    scenarios.append({
        'Scenario': 'Sign Player',
        'Team_Salary': new_salary,
        'Tax_Bill': with_player['tax_bill'],
        'Total_Cost': with_player['total_cost'],
        'Marginal_Cost': marginal_cost
    })

    df = pd.DataFrame(scenarios)
    df['Tax_Multiplier'] = df['Marginal_Cost'] / player_salary

    return df


# Example usage
if __name__ == "__main__":
    print("=== NBA Salary Cap Analysis ===\n")

    # Example 1: Calculate luxury tax
    print("Example 1: Luxury Tax Calculation")
    team_salary = 180_000_000
    tax_info = calculate_luxury_tax(team_salary, is_repeater=False)
    print(f"Team Salary: ${team_salary:,.0f}")
    print(f"Overage: ${tax_info['overage']:,.0f}")
    print(f"Tax Bill: ${tax_info['tax_bill']:,.0f}")
    print(f"Total Cost: ${tax_info['total_cost']:,.0f}")
    print(f"Effective Tax Rate: {tax_info['effective_rate']:.2f}x\n")

    # Example 2: Max contract projection
    print("Example 2: Supermax Contract Projection")
    supermax = project_contract_value(
        starting_salary=0.35 * SALARY_CAP,
        years=5,
        annual_raise=0.08
    )
    print(supermax)
    print(f"\nTotal Contract Value: ${supermax['Total_Value'].iloc[0]:,.0f}\n")

    # Example 3: Team cap situation
    print("Example 3: Team Cap Situation Analysis")
    roster = [45_000_000, 35_000_000, 25_000_000, 18_000_000, 12_000_000,
              8_000_000, 5_000_000, 3_000_000, 2_500_000, 2_000_000,
              1_800_000, 1_500_000]

    cap_situation = analyze_team_cap_situation(roster)
    print(f"Total Salary: ${cap_situation['total_salary']:,.0f}")
    print(f"Cap Space: ${cap_situation['cap_space']:,.0f}")
    print(f"Over Tax Line: {cap_situation['over_tax']}")
    print(f"Available MLE: ${cap_situation['available_mle']:,.0f}")
    print(f"Tax Bill: ${cap_situation['tax_bill']:,.0f}\n")

    # Example 4: Signing scenario comparison
    print("Example 4: Marginal Cost of Signing Player")
    comparison = compare_signing_scenarios(
        player_salary=15_000_000,
        current_team_salary=170_000_000,
        is_repeater=False
    )
    print(comparison)

    # Create visualizations
    print("\nGenerating luxury tax visualization...")
    visualize_luxury_tax_brackets()

    print("\nAnalysis complete!")

R Example: Salary Cap Analysis

# NBA Salary Cap Analysis in R
# Comprehensive tools for cap calculations and team planning
# Install: install.packages(c("tidyverse", "scales", "ggplot2"))

library(tidyverse)
library(scales)
library(ggplot2)

# 2023-24 Salary Cap Constants
SALARY_CAP <- 136021000
LUXURY_TAX <- 165294000
FIRST_APRON <- 172346000
SECOND_APRON <- 182794000
MIN_TEAM_SALARY <- 122418900

# Maximum Salaries
MAX_SALARIES <- list(
  "0-6" = 0.25 * SALARY_CAP,
  "7-9" = 0.30 * SALARY_CAP,
  "10+" = 0.35 * SALARY_CAP
)

#' Calculate luxury tax bill
#'
#' @param team_salary Total team salary
#' @param is_repeater Whether team is repeater offender
#' @return List with tax details
calculate_luxury_tax <- function(team_salary, is_repeater = FALSE) {
  if (team_salary <= LUXURY_TAX) {
    return(list(
      overage = 0,
      tax_bill = 0,
      total_cost = team_salary,
      effective_rate = 0
    ))
  }

  overage <- team_salary - LUXURY_TAX

  # Define tax brackets
  if (is_repeater) {
    brackets <- tibble(
      threshold = c(5e6, 10e6, 15e6, 20e6, Inf),
      rate = c(2.50, 2.75, 3.50, 4.25, 4.75)
    )
  } else {
    brackets <- tibble(
      threshold = c(5e6, 10e6, 15e6, 20e6, Inf),
      rate = c(1.50, 1.75, 2.50, 3.25, 3.75)
    )
  }

  # Calculate progressive tax
  tax_bill <- 0
  previous_threshold <- 0

  for (i in 1:nrow(brackets)) {
    if (overage <= previous_threshold) break

    taxable_amount <- min(overage, brackets$threshold[i]) - previous_threshold
    tax_bill <- tax_bill + (taxable_amount * brackets$rate[i])

    previous_threshold <- brackets$threshold[i]
  }

  total_cost <- team_salary + tax_bill
  effective_rate <- if (overage > 0) tax_bill / overage else 0

  return(list(
    overage = overage,
    tax_bill = tax_bill,
    total_cost = total_cost,
    effective_rate = effective_rate,
    repeater = is_repeater
  ))
}


#' Calculate maximum salary
#'
#' @param years_of_service Player's NBA years
#' @param supermax Whether player qualifies for supermax
#' @return Maximum salary amount
calculate_max_salary <- function(years_of_service, supermax = FALSE) {
  if (supermax) {
    return(0.35 * SALARY_CAP)
  }

  if (years_of_service <= 6) {
    return(MAX_SALARIES[["0-6"]])
  } else if (years_of_service <= 9) {
    return(MAX_SALARIES[["7-9"]])
  } else {
    return(MAX_SALARIES[["10+"]])
  }
}


#' Project contract value over multiple years
#'
#' @param starting_salary First year salary
#' @param years Contract length
#' @param annual_raise Annual raise percentage
#' @return Tibble with year-by-year breakdown
project_contract <- function(starting_salary, years, annual_raise = 0.08) {
  tibble(
    Year = 1:years,
    Salary = starting_salary * (1 + annual_raise)^(Year - 1)
  ) %>%
    mutate(
      Cumulative = cumsum(Salary),
      Total_Value = last(Cumulative)
    )
}


#' Analyze team cap situation
#'
#' @param roster_salaries Vector of player salaries
#' @return List with cap analysis
analyze_team_cap <- function(roster_salaries) {
  total_salary <- sum(roster_salaries)

  cap_space <- max(0, SALARY_CAP - total_salary)

  # Determine available exceptions
  if (total_salary < LUXURY_TAX) {
    mle <- 12405000  # Non-taxpayer MLE
    bae <- 4500000
  } else if (total_salary < FIRST_APRON) {
    mle <- 5000000   # Taxpayer MLE
    bae <- 0
  } else {
    mle <- 5000000
    bae <- 0
  }

  tax_info <- calculate_luxury_tax(total_salary)

  list(
    total_salary = total_salary,
    cap_space = cap_space,
    under_cap = total_salary < SALARY_CAP,
    over_tax = total_salary > LUXURY_TAX,
    over_first_apron = total_salary > FIRST_APRON,
    over_second_apron = total_salary > SECOND_APRON,
    available_mle = mle,
    available_bae = bae,
    tax_bill = tax_info$tax_bill,
    total_cost = tax_info$total_cost
  )
}


#' Visualize luxury tax structure
visualize_tax_brackets <- function() {
  # Generate data
  overages <- seq(0, 50e6, length.out = 1000)

  tax_data <- map_dfr(overages, ~{
    regular <- calculate_luxury_tax(LUXURY_TAX + .x, is_repeater = FALSE)
    repeater <- calculate_luxury_tax(LUXURY_TAX + .x, is_repeater = TRUE)

    tibble(
      Overage = .x,
      Regular_Tax = regular$tax_bill,
      Repeater_Tax = repeater$tax_bill,
      Regular_Total = regular$total_cost,
      Repeater_Total = repeater$total_cost
    )
  })

  # Tax bill plot
  p1 <- tax_data %>%
    pivot_longer(
      cols = c(Regular_Tax, Repeater_Tax),
      names_to = "Type",
      values_to = "Tax_Bill"
    ) %>%
    mutate(Type = str_remove(Type, "_Tax")) %>%
    ggplot(aes(x = Overage / 1e6, y = Tax_Bill / 1e6, color = Type)) +
    geom_line(size = 1.5) +
    scale_color_manual(values = c("Regular" = "#1f77b4", "Repeater" = "#ff7f0e")) +
    labs(
      title = "Luxury Tax Bill by Overage Amount",
      x = "Overage (Millions)",
      y = "Tax Bill (Millions)",
      color = "Tax Status"
    ) +
    theme_minimal() +
    theme(
      plot.title = element_text(size = 14, face = "bold"),
      legend.position = "top"
    )

  # Total cost plot
  p2 <- tax_data %>%
    pivot_longer(
      cols = c(Regular_Total, Repeater_Total),
      names_to = "Type",
      values_to = "Total_Cost"
    ) %>%
    mutate(Type = str_remove(Type, "_Total")) %>%
    ggplot(aes(x = Overage / 1e6, y = Total_Cost / 1e6, color = Type)) +
    geom_line(size = 1.5) +
    geom_hline(yintercept = LUXURY_TAX / 1e6, linetype = "dashed",
               color = "red", size = 0.8) +
    scale_color_manual(values = c("Regular" = "#1f77b4", "Repeater" = "#ff7f0e")) +
    labs(
      title = "Total Team Cost (Salary + Tax)",
      x = "Overage (Millions)",
      y = "Total Cost (Millions)",
      color = "Tax Status"
    ) +
    theme_minimal() +
    theme(
      plot.title = element_text(size = 14, face = "bold"),
      legend.position = "top"
    )

  # Combine plots
  gridExtra::grid.arrange(p1, p2, ncol = 2)

  ggsave("luxury_tax_visualization.png",
         gridExtra::arrangeGrob(p1, p2, ncol = 2),
         width = 14, height = 6, dpi = 300)
}


#' Compare marginal cost of signing player
#'
#' @param player_salary Proposed player salary
#' @param current_salary Current team salary
#' @param is_repeater Repeater status
compare_signing_scenarios <- function(player_salary, current_salary, is_repeater = FALSE) {
  baseline <- calculate_luxury_tax(current_salary, is_repeater)
  with_player <- calculate_luxury_tax(current_salary + player_salary, is_repeater)

  marginal_cost <- with_player$total_cost - baseline$total_cost
  tax_multiplier <- marginal_cost / player_salary

  tibble(
    Scenario = c("No Signing", "Sign Player"),
    Team_Salary = c(current_salary, current_salary + player_salary),
    Tax_Bill = c(baseline$tax_bill, with_player$tax_bill),
    Total_Cost = c(baseline$total_cost, with_player$total_cost),
    Marginal_Cost = c(0, marginal_cost),
    Tax_Multiplier = c(0, tax_multiplier)
  )
}


# Example usage
main <- function() {
  cat("=== NBA Salary Cap Analysis ===\n\n")

  # Example 1: Luxury tax calculation
  cat("Example 1: Luxury Tax Calculation\n")
  team_salary <- 180e6
  tax_info <- calculate_luxury_tax(team_salary, is_repeater = FALSE)

  cat(sprintf("Team Salary: $%s\n", dollar(team_salary)))
  cat(sprintf("Overage: $%s\n", dollar(tax_info$overage)))
  cat(sprintf("Tax Bill: $%s\n", dollar(tax_info$tax_bill)))
  cat(sprintf("Total Cost: $%s\n", dollar(tax_info$total_cost)))
  cat(sprintf("Effective Rate: %.2fx\n\n", tax_info$effective_rate))

  # Example 2: Supermax projection
  cat("Example 2: Supermax Contract Projection\n")
  supermax <- project_contract(
    starting_salary = 0.35 * SALARY_CAP,
    years = 5,
    annual_raise = 0.08
  )
  print(supermax)
  cat(sprintf("\nTotal Value: $%s\n\n", dollar(supermax$Total_Value[1])))

  # Example 3: Team cap analysis
  cat("Example 3: Team Cap Situation\n")
  roster <- c(45e6, 35e6, 25e6, 18e6, 12e6, 8e6, 5e6, 3e6, 2.5e6, 2e6, 1.8e6, 1.5e6)

  cap_situation <- analyze_team_cap(roster)
  cat(sprintf("Total Salary: $%s\n", dollar(cap_situation$total_salary)))
  cat(sprintf("Cap Space: $%s\n", dollar(cap_situation$cap_space)))
  cat(sprintf("Over Tax: %s\n", cap_situation$over_tax))
  cat(sprintf("Available MLE: $%s\n", dollar(cap_situation$available_mle)))
  cat(sprintf("Tax Bill: $%s\n\n", dollar(cap_situation$tax_bill)))

  # Example 4: Signing comparison
  cat("Example 4: Marginal Cost Analysis\n")
  comparison <- compare_signing_scenarios(
    player_salary = 15e6,
    current_salary = 170e6,
    is_repeater = FALSE
  )
  print(comparison)

  # Visualizations
  cat("\nGenerating visualizations...\n")
  visualize_tax_brackets()

  cat("\nAnalysis complete!\n")
}

# Run analysis
main()