mclovin 1.0.0__py3-none-any.whl

mclovin/basketball/box_metrics.py

@@ -0,0 +1,916 @@
+"""
+box_metrics.py
+==============
+
+All-in-one box-score metrics and the usage/rate family.
+
+Contents
+--------
+`add_box_plus_minus_linear`  Daniel Myers' simplified linear BPM
+`add_player_efficiency_rating` John Hollinger's PER (needs LeagueContext)
+`add_game_score`             Hollinger's Game Score
+`add_performance_impact_estimator` / `add_team_impact_estimator`  PIE / TIE
+`add_true_shooting_pct`      TS%
+`add_usage_rate`             Usage% (team context)
+`add_assist_pct`             AST% (team context)
+`add_rebound_pct`            TRB%/ORB%/DRB% (team context)
+`add_steal_pct` / `add_block_pct`  STL%/BLK% (team context)
+
+A note on what these are for
+----------------------------
+BPM, PER and Win Shares are *descriptive* summaries of what a player did.
+The draft-prediction literature (see `draft.py`) consistently finds that the
+component rates (steal rate, block rate, assist-to-turnover, free-throw
+percentage) carry more predictive signal about NBA outcomes than the
+all-in-one composites do. Use the composites as features and as scouting
+context, not as the whole model.
+
+Defence caveat, in Myers' own words: box-score defensive estimates are weak,
+so treat DBPM as a guide rather than ground truth, and discount it for
+players known to be much better or worse defenders than their box line.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+import numpy as np
+import pandas as pd
+
+from ..core import (
+    ComputationReport,
+    MetricSpec,
+    Reliability,
+    require_columns,
+    safe_divide,
+)
+from .coefficients import fta_coefficient
+from ..schema import SchemaResolver
+
+# ---------------------------------------------------------------------------
+# Box Plus/Minus (Daniel Myers)
+# ---------------------------------------------------------------------------
+
+#: Myers' published **simplified linear** BPM coefficients, per 100 team
+#: possessions. Source: Basketball-Reference "About Box Plus/Minus (BPM)"
+#: (Myers, Feb 2020) and godismyjudgeok.com/DStats/box-plusminus/.
+#:
+#: IMPORTANT: the full BPM 2.0 uses position- and role-dependent coefficients
+#: with interaction terms that are only partially published. This linear
+#: version is the one Myers explicitly offers for small samples and for
+#: reimplementation. Results approximate but do not reproduce
+#: Basketball-Reference's published BPM.
+#:
+#: Note the steal coefficient (1.3571) is by far the largest positive weight,
+#: which is mechanically consistent with the independent draft-research
+#: finding that steal rate is an unusually strong predictor of NBA success.
+BPM_LINEAR_COEFFICIENTS: dict[str, float] = {
+    "PTS": 0.7008,
+    "TPA": -0.4155,
+    "TWOPA": -0.5424,
+    "FTA": -0.2589,
+    "OREB": 0.1398,
+    "DREB": 0.3444,
+    "AST": 0.3846,
+    "STL": 1.3571,
+    "BLK": 0.6475,
+    "TOV": -0.9347,
+    "PF": -0.5153,
+}
+
+#: Intercept term applied per 100 possessions.
+BPM_LINEAR_INTERCEPT: float = -0.0650
+
+BPM_LINEAR_SPEC = MetricSpec(
+    name="BPM_LINEAR",
+    requires=("PTS", "TPA", "TWOPA", "FTA", "OREB", "DREB", "AST", "STL", "BLK", "TOV"),
+    source="Myers, D. (2020), 'About Box Plus/Minus (BPM)', Basketball-Reference",
+    description="Points above league average per 100 possessions (simplified linear BPM).",
+    notes=(
+        "Approximation of BPM 2.0. The full model uses position/role-dependent "
+        "coefficients that are only partially published. Scale: +8 MVP-level, "
+        "+4 all-star consideration, 0 solid starter, -2 replacement level."
+    ),
+)
+
+#: Replacement level on the BPM scale, per Myers. VORP is measured against it.
+BPM_REPLACEMENT_LEVEL: float = -2.0
+
+
+#: Default team possessions per 40 minutes for NCAA play, used to estimate
+#: team possessions while a player was on the floor when no pace data exists.
+#: Division I pace has hovered around 67-70 possessions per 40 minutes in the
+#: shot-clock era; KenPom publishes the exact figure by season and team.
+DEFAULT_NCAA_PACE: float = 68.0
+DEFAULT_NBA_PACE: float = 100.0
+
+
+def add_box_plus_minus_linear(
+    df: pd.DataFrame,
+    resolver: Optional[SchemaResolver] = None,
+    poss_col: Optional[str] = None,
+    minutes_col: Optional[str] = None,
+    pace: Optional[float] = None,
+    level: str = "ncaa",
+    center: bool = True,
+    new_col: str = "BPM_LINEAR",
+    report: Optional[ComputationReport] = None,
+) -> pd.DataFrame:
+    """Myers' simplified linear Box Plus/Minus.
+
+    BPM estimates a player's contribution in **points above league average per
+    100 team possessions**, with replacement level at -2.0. It was built by
+    regressing box-score inputs against long-run RAPM, so it is best
+    understood as a box-score approximation of RAPM (which itself needs
+    play-by-play lineup data and is not computable from box scores at all).
+
+    The denominator matters
+    -----------------------
+    Myers' coefficients are calibrated against **team possessions while the
+    player was on the floor**, not the possessions the player personally
+    used. A player uses roughly a fifth of his team's possessions, so
+    substituting individual possessions inflates every per-100 rate about
+    fivefold and (because the shot-attempt coefficients are negative) drives
+    BPM violently negative. This function therefore estimates::
+
+        team_poss_on_floor = minutes_played * (pace / game_minutes)
+
+    Parameters
+    ----------
+    poss_col : explicit team-possessions-on-floor column. Use this when you
+        have real team pace data, since it is strictly better than the estimate.
+    minutes_col : minutes column. Defaults to the canonical MIN.
+    pace : team possessions per regulation game. Defaults to a league-average
+        assumption (68 NCAA, 100 NBA); supply the team's real pace when known.
+    center : re-centre so the minutes-weighted mean is 0.0 (default True).
+        BPM is *defined* as points above **league average**, so a zero mean is
+        part of the specification, not a cosmetic adjustment. Myers' published
+        coefficients are NBA-calibrated; applied to NCAA data they produce a
+        constant offset that centring removes. Note this centres against
+        whatever rows you pass, so it equals the true league average only if
+        the DataFrame is the full league. Pass the whole season, not a
+        subset, and re-use the same offset for train and test.
+
+    Warning
+    -------
+    If your dataset already provides a BPM column (BartTorvik's `bpm`), prefer
+    it, since it is computed with the full position/role model against proper
+    team context. Use this function when you need BPM on data that lacks one,
+    and label the result as an approximation.
+    """
+    r = resolver if resolver is not None else SchemaResolver(df.columns)
+    out = df.copy()
+    game_minutes = 40.0 if level.lower() == "ncaa" else 48.0
+    assumed_pace = pace if pace is not None else (
+        DEFAULT_NCAA_PACE if level.lower() == "ncaa" else DEFAULT_NBA_PACE
+    )
+
+    required = list(BPM_LINEAR_COEFFICIENTS.keys())
+    hard_required = [k for k in required if k != "PF"]
+    require_columns(r, hard_required, "add_box_plus_minus_linear")
+
+    pace_source = "supplied possessions column"
+    if poss_col is not None and poss_col in out.columns:
+        possessions = pd.to_numeric(out[poss_col], errors="coerce")
+    else:
+        if minutes_col is not None and minutes_col in out.columns:
+            minutes = pd.to_numeric(out[minutes_col], errors="coerce")
+        elif r.has("MIN"):
+            minutes = pd.to_numeric(r.get(out, "MIN"), errors="coerce")
+        else:
+            raise KeyError(
+                "add_box_plus_minus_linear needs minutes (canonical MIN) to "
+                "estimate team possessions on the floor, or an explicit "
+                "poss_col. Supply one of them."
+            )
+        possessions = minutes * (assumed_pace / game_minutes)
+        pace_source = f"estimated from minutes at pace={assumed_pace}"
+
+    contribution = pd.Series(0.0, index=out.index)
+    used, skipped = [], []
+    for canonical, coefficient in BPM_LINEAR_COEFFICIENTS.items():
+        if not r.has(canonical):
+            skipped.append(canonical)
+            continue
+        contribution = contribution + coefficient * pd.to_numeric(
+            r.get(out, canonical), errors="coerce"
+        ).fillna(0.0)
+        used.append(canonical)
+
+    per_100 = safe_divide(contribution, possessions) * 100.0
+    raw = per_100 + BPM_LINEAR_INTERCEPT
+
+    offset = 0.0
+    if center:
+        weights = pd.to_numeric(
+            r.get(out, "MIN") if r.has("MIN") else pd.Series(1.0, index=out.index),
+            errors="coerce",
+        ).fillna(0.0)
+        finite = np.isfinite(raw) & (weights > 0)
+        if finite.any() and weights[finite].sum() > 0:
+            offset = float(np.average(raw[finite], weights=weights[finite]))
+    out[new_col] = raw - offset
+
+    if report is not None:
+        detail = (
+            f"Linear approximation of BPM 2.0. Terms used: {len(used)}. "
+            f"Possessions {pace_source}."
+        )
+        if center:
+            detail += f" Centred to zero mean (offset {offset:.2f})."
+        if skipped:
+            detail += f" Missing (treated as zero): {skipped}."
+        report.record(BPM_LINEAR_SPEC, Reliability.APPROXIMATED, detail)
+    return out
+
+
+def add_vorp(
+    df: pd.DataFrame,
+    resolver: Optional[SchemaResolver] = None,
+    bpm_col: str = "BPM",
+    minutes_share_col: Optional[str] = None,
+    team_games: Optional[float] = None,
+    season_games: float = 32.0,
+    new_col: str = "VORP",
+    report: Optional[ComputationReport] = None,
+) -> pd.DataFrame:
+    """Value Over Replacement Player.
+
+        VORP = (BPM - (-2.0)) * (share of team minutes played) * (team games / season games)
+
+    Replacement level is -2.0 BPM (Myers); a full team of replacement players
+    wins roughly 14 NBA games. The minutes-share term converts a rate into a
+    volume statistic: a +4 BPM player who plays 10% of minutes contributes
+    far less than one who plays 80%.
+
+    Parameters
+    ----------
+    minutes_share_col : fraction (0-1) or percentage (0-100) of team minutes.
+        BartTorvik's `Min_per` (canonical MIN_PCT) is exactly this; if values
+        exceed 1.0 they are assumed to be percentages and divided by 100.
+    season_games : games in a full season (NCAA ~32, NBA 82).
+    """
+    r = resolver if resolver is not None else SchemaResolver(df.columns)
+    out = df.copy()
+
+    if bpm_col not in out.columns:
+        if r.has("BPM"):
+            bpm = r.get(out, "BPM")
+        else:
+            raise KeyError(
+                f"add_vorp needs a BPM column ('{bpm_col}' not found and canonical "
+                f"BPM unresolvable). Compute add_box_plus_minus_linear first."
+            )
+    else:
+        bpm = pd.to_numeric(out[bpm_col], errors="coerce")
+
+    if minutes_share_col is not None and minutes_share_col in out.columns:
+        share = pd.to_numeric(out[minutes_share_col], errors="coerce")
+    elif r.has("MIN_PCT"):
+        share = pd.to_numeric(r.get(out, "MIN_PCT"), errors="coerce")
+    else:
+        raise KeyError(
+            "add_vorp needs a minutes-share column (canonical MIN_PCT, e.g. "
+            "BartTorvik's 'Min_per')."
+        )
+
+    if share.max(skipna=True) is not np.nan and share.max(skipna=True) > 1.0:
+        share = share / 100.0
+
+    games_factor = 1.0 if team_games is None else (team_games / season_games)
+    out[new_col] = (bpm - BPM_REPLACEMENT_LEVEL) * share * games_factor
+
+    if report is not None:
+        spec = MetricSpec(
+            name=new_col,
+            requires=("BPM", "MIN_PCT"),
+            source="Basketball-Reference, 'NBA Win Shares' / VORP definition",
+            description="Points above a -2.0 BPM replacement player, scaled by playing time.",
+            notes="Replacement level -2.0 BPM per Myers.",
+        )
+        report.record(spec, Reliability.APPROXIMATED if team_games is None else Reliability.EXACT)
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Player Efficiency Rating (John Hollinger)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class LeagueContext:
+    """League-wide totals required by PER's unadjusted stage.
+
+    PER is defined relative to league averages, so it simply cannot be
+    computed from player rows alone. Supply these from a season-level
+    aggregate (Sports-Reference publishes them per season).
+
+    Attributes are league TOTALS for the season, not per-game averages.
+    """
+
+    lg_pts: float
+    lg_fga: float
+    lg_fgm: float
+    lg_fta: float
+    lg_ftm: float
+    lg_ast: float
+    lg_orb: float
+    lg_trb: float
+    lg_tov: float
+    lg_pf: float
+    lg_pace: Optional[float] = None
+    label: str = ""
+
+    @property
+    def value_of_possession(self) -> float:
+        """VOP = lgPTS / (lgFGA - lgORB + lgTOV + 0.44*lgFTA)."""
+        denom = self.lg_fga - self.lg_orb + self.lg_tov + 0.44 * self.lg_fta
+        return self.lg_pts / denom if denom else 0.0
+
+    @property
+    def defensive_rebound_pct(self) -> float:
+        """DRB% = (lgTRB - lgORB) / lgTRB."""
+        return (self.lg_trb - self.lg_orb) / self.lg_trb if self.lg_trb else 0.7
+
+    @property
+    def factor(self) -> float:
+        """factor = 2/3 - (0.5 * (lgAST/lgFG)) / (2 * (lgFG/lgFT))."""
+        if not self.lg_fgm or not self.lg_ftm:
+            return 2.0 / 3.0
+        return (2.0 / 3.0) - (0.5 * (self.lg_ast / self.lg_fgm)) / (
+            2.0 * (self.lg_fgm / self.lg_ftm)
+        )
+
+
+PER_SPEC = MetricSpec(
+    name="PER",
+    requires=("MIN", "TPM", "AST", "FGM", "FGA", "FTM", "FTA", "TOV", "REB", "OREB", "STL", "BLK", "PF"),
+    requires_team=("TM_AST", "TM_FG"),
+    source="Hollinger, J.; formula per Basketball-Reference",
+    description="Per-minute production, pace-adjusted, normalised so league average = 15.00.",
+    notes=(
+        "Requires league totals (LeagueContext) AND team AST/FG. Widely "
+        "criticised as usage- and offence-biased with weak defensive content. "
+        "Useful as a feature, poor as a target."
+    ),
+)
+
+
+def add_player_efficiency_rating(
+    df: pd.DataFrame,
+    league: LeagueContext,
+    resolver: Optional[SchemaResolver] = None,
+    team_pace_col: Optional[str] = None,
+    normalise: bool = True,
+    new_col: str = "PER",
+    report: Optional[ComputationReport] = None,
+) -> pd.DataFrame:
+    """Hollinger's Player Efficiency Rating.
+
+    Three stages: unadjusted PER (uPER) -> pace-adjusted (aPER) -> normalised
+    so the minutes-weighted league average is exactly 15.00.
+
+    uPER (per Basketball-Reference)::
+
+        uPER = (1/MP) * [ 3P
+                        + (2/3)*AST
+                        + (2 - factor*(TmAST/TmFG))*FG
+                        + FT*0.5*(1 + (1 - TmAST/TmFG) + (2/3)*(TmAST/TmFG))
+                        - VOP*TOV
+                        - VOP*DRB%*(FGA - FG)
+                        - VOP*0.44*(0.44 + 0.56*DRB%)*(FTA - FT)
+                        + VOP*(1 - DRB%)*(TRB - ORB)
+                        + VOP*DRB%*ORB
+                        + VOP*STL
+                        + VOP*DRB%*BLK
+                        - PF*((lgFT/lgPF) - 0.44*(lgFTA/lgPF)*VOP) ]
+
+    Parameters
+    ----------
+    league : LeagueContext with season-wide totals.
+    team_pace_col : if supplied (and league.lg_pace set), applies the pace
+        adjustment aPER = (lgPace/TmPace) * uPER. Omitted -> uPER is used and
+        the result is flagged APPROXIMATED.
+    normalise : rescale so the minutes-weighted mean is 15.00. Note this
+        normalises against *this dataset*, which equals the true league
+        average only if the dataset is the full league.
+    """
+    r = resolver if resolver is not None else SchemaResolver(df.columns)
+    out = df.copy()
+
+    require_columns(
+        r,
+        ["MIN", "TPM", "AST", "FGM", "FGA", "FTM", "FTA", "TOV", "REB", "OREB", "STL", "BLK"],
+        "add_player_efficiency_rating",
+    )
+
+    vop = league.value_of_possession
+    drb_pct = league.defensive_rebound_pct
+    factor = league.factor
+
+    mp = pd.to_numeric(r.get(out, "MIN"), errors="coerce")
+    tpm = pd.to_numeric(r.get(out, "TPM"), errors="coerce").fillna(0.0)
+    ast = pd.to_numeric(r.get(out, "AST"), errors="coerce").fillna(0.0)
+    fgm = pd.to_numeric(r.get(out, "FGM"), errors="coerce").fillna(0.0)
+    fga = pd.to_numeric(r.get(out, "FGA"), errors="coerce").fillna(0.0)
+    ftm = pd.to_numeric(r.get(out, "FTM"), errors="coerce").fillna(0.0)
+    fta = pd.to_numeric(r.get(out, "FTA"), errors="coerce").fillna(0.0)
+    tov = pd.to_numeric(r.get(out, "TOV"), errors="coerce").fillna(0.0)
+    trb = pd.to_numeric(r.get(out, "REB"), errors="coerce").fillna(0.0)
+    orb = pd.to_numeric(r.get(out, "OREB"), errors="coerce").fillna(0.0)
+    stl = pd.to_numeric(r.get(out, "STL"), errors="coerce").fillna(0.0)
+    blk = pd.to_numeric(r.get(out, "BLK"), errors="coerce").fillna(0.0)
+    pf = pd.to_numeric(r.get(out, "PF"), errors="coerce").fillna(0.0) if r.has("PF") else pd.Series(0.0, index=out.index)
+
+    # Team assist ratio: exact if team totals present, else league average.
+    team_context_exact = not r.missing(["TM_AST", "TM_FG"])
+    if team_context_exact:
+        tm_ast_ratio = safe_divide(r.get(out, "TM_AST"), r.get(out, "TM_FG"))
+    else:
+        lg_ratio = league.lg_ast / league.lg_fgm if league.lg_fgm else 0.0
+        tm_ast_ratio = pd.Series(lg_ratio, index=out.index)
+
+    foul_term = (
+        (league.lg_ftm / league.lg_pf) - 0.44 * (league.lg_fta / league.lg_pf) * vop
+        if league.lg_pf
+        else 0.0
+    )
+
+    raw = (
+        tpm
+        + (2.0 / 3.0) * ast
+        + (2.0 - factor * tm_ast_ratio) * fgm
+        + ftm * 0.5 * (1.0 + (1.0 - tm_ast_ratio) + (2.0 / 3.0) * tm_ast_ratio)
+        - vop * tov
+        - vop * drb_pct * (fga - fgm)
+        - vop * 0.44 * (0.44 + 0.56 * drb_pct) * (fta - ftm)
+        + vop * (1.0 - drb_pct) * (trb - orb)
+        + vop * drb_pct * orb
+        + vop * stl
+        + vop * drb_pct * blk
+        - pf * foul_term
+    )
+    uper = safe_divide(raw, mp, fill=np.nan)
+
+    paced = uper
+    pace_applied = False
+    if team_pace_col is not None and team_pace_col in out.columns and league.lg_pace:
+        paced = uper * safe_divide(
+            pd.Series(league.lg_pace, index=out.index),
+            pd.to_numeric(out[team_pace_col], errors="coerce"),
+            fill=1.0,
+        )
+        pace_applied = True
+
+    if normalise:
+        weights = mp.fillna(0.0)
+        weighted_mean = (
+            np.average(paced.fillna(0.0), weights=weights) if weights.sum() > 0 else np.nan
+        )
+        out[new_col] = paced * (15.0 / weighted_mean) if weighted_mean else paced
+    else:
+        out[new_col] = paced
+
+    if report is not None:
+        reliability = (
+            Reliability.EXACT
+            if (team_context_exact and pace_applied)
+            else Reliability.APPROXIMATED
+        )
+        detail_bits = []
+        if not team_context_exact:
+            detail_bits.append("team AST/FG substituted with league average")
+        if not pace_applied:
+            detail_bits.append("no pace adjustment applied")
+        if normalise:
+            detail_bits.append("normalised against this dataset, not the true league")
+        report.record(PER_SPEC, reliability, "; ".join(detail_bits))
+    return out
+
+
+GAME_SCORE_SPEC = MetricSpec(
+    name="GAME_SCORE",
+    requires=("PTS", "FGM", "FGA", "FTA", "FTM", "OREB", "DREB", "STL", "AST", "BLK", "TOV"),
+    source="Hollinger, J.; Basketball-Reference glossary",
+    description="Single-number box-score summary scaled roughly like points (10 = solid).",
+    notes="Simple and transparent; no team or league context required.",
+)
+
+
+def add_game_score(
+    df: pd.DataFrame,
+    resolver: Optional[SchemaResolver] = None,
+    new_col: str = "GAME_SCORE",
+    report: Optional[ComputationReport] = None,
+) -> pd.DataFrame:
+    """Hollinger's Game Score::
+
+        GmSc = PTS + 0.4*FG - 0.7*FGA - 0.4*(FTA - FT) + 0.7*ORB + 0.3*DRB
+               + STL + 0.7*AST + 0.7*BLK - 0.4*PF - TOV
+
+    Calibrated so ~10 is a solid outing and ~40 is outstanding. Fully
+    computable from an individual box score, which makes it a useful,
+    honest baseline when team context is unavailable.
+    """
+    r = resolver if resolver is not None else SchemaResolver(df.columns)
+    out = df.copy()
+    require_columns(
+        r,
+        ["PTS", "FGM", "FGA", "FTA", "FTM", "OREB", "DREB", "STL", "AST", "BLK", "TOV"],
+        "add_game_score",
+    )
+
+    g = lambda name: pd.to_numeric(r.get(out, name), errors="coerce").fillna(0.0)
+    pf = g("PF") if r.has("PF") else pd.Series(0.0, index=out.index)
+
+    out[new_col] = (
+        g("PTS")
+        + 0.4 * g("FGM")
+        - 0.7 * g("FGA")
+        - 0.4 * (g("FTA") - g("FTM"))
+        + 0.7 * g("OREB")
+        + 0.3 * g("DREB")
+        + g("STL")
+        + 0.7 * g("AST")
+        + 0.7 * g("BLK")
+        - 0.4 * pf
+        - g("TOV")
+    )
+
+    if report is not None:
+        report.record(GAME_SCORE_SPEC, Reliability.EXACT)
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Performance/Team Impact Estimator (NBA.com)
+# ---------------------------------------------------------------------------
+
+PIE_SPEC = MetricSpec(
+    name="PIE",
+    requires=("PTS", "FGM", "FGA", "FTM", "FTA", "DREB", "OREB", "AST", "STL", "BLK", "TOV"),
+    source="NBA.com Advanced Stats glossary, 'Performance Impact Estimator'",
+    description="Single-number estimate of a player's or team's overall statistical output in a game.",
+    notes=(
+        "PIE = PTS + FGM + FTM - FGA - FTA + DREB + 0.5*OREB + AST + STL "
+        "+ 0.5*BLK - PF - TOV. Unlike Game Score, it has no tuned "
+        "coefficients: it is a plain sum of positive box-score contributions "
+        "minus negative ones (missed shots, missed free throws, fouls, "
+        "turnovers). Mainly useful as the input to add_team_impact_estimator."
+    ),
+)
+
+
+def add_performance_impact_estimator(
+    df: pd.DataFrame,
+    resolver: Optional[SchemaResolver] = None,
+    new_col: str = "PIE",
+    report: Optional[ComputationReport] = None,
+) -> pd.DataFrame:
+    """Performance Impact Estimator (PIE)::
+
+        PIE = PTS + FGM + FTM - FGA - FTA + DREB + 0.5*OREB
+              + AST + STL + 0.5*BLK - PF - TOV
+
+    Fully computable from a single row's own box score (player or team); no
+    team or opponent context required. On its own PIE is not very meaningful,
+    since it has no fixed scale; it exists as the building block for
+    `add_team_impact_estimator`, which expresses it as a share of the total
+    production in the game.
+    """
+    r = resolver if resolver is not None else SchemaResolver(df.columns)
+    out = df.copy()
+    require_columns(
+        r,
+        ["PTS", "FGM", "FGA", "FTM", "FTA", "DREB", "OREB", "AST", "STL", "BLK", "TOV"],
+        "add_performance_impact_estimator",
+    )
+
+    g = lambda name: pd.to_numeric(r.get(out, name), errors="coerce").fillna(0.0)
+    pf = g("PF") if r.has("PF") else pd.Series(0.0, index=out.index)
+
+    out[new_col] = (
+        g("PTS")
+        + g("FGM")
+        + g("FTM")
+        - g("FGA")
+        - g("FTA")
+        + g("DREB")
+        + 0.5 * g("OREB")
+        + g("AST")
+        + g("STL")
+        + 0.5 * g("BLK")
+        - pf
+        - g("TOV")
+    )
+
+    if report is not None:
+        report.record(PIE_SPEC, Reliability.EXACT)
+    return out
+
+
+TIE_SPEC = MetricSpec(
+    name="TIE",
+    requires=("PTS", "FGM", "FGA", "FTM", "FTA", "DREB", "OREB", "AST", "STL", "BLK", "TOV"),
+    requires_team=(
+        "OPP_PTS", "OPP_FG", "OPP_FGA", "OPP_FTM", "OPP_FTA",
+        "OPP_DRB", "OPP_ORB", "OPP_AST", "OPP_STL", "OPP_BLK", "OPP_TOV",
+    ),
+    source="NBA.com Advanced Stats glossary, 'Team Impact Estimator'",
+    description="A player's or team's PIE as a share of the combined PIE produced by both sides.",
+    notes="TIE = PIE / (PIE + OppPIE). 0.50 is an even statistical split.",
+)
+
+
+def add_team_impact_estimator(
+    df: pd.DataFrame,
+    resolver: Optional[SchemaResolver] = None,
+    pie_col: Optional[str] = None,
+    new_col: str = "TIE",
+    report: Optional[ComputationReport] = None,
+) -> pd.DataFrame:
+    """Team Impact Estimator: TIE = PIE / (PIE + OppPIE).
+
+    Rescales PIE into a share (0-1) of the combined production in the game:
+    0.50 is an even split, above it means winning the statistical battle.
+    **Requires the opponent's full box score**, since the opponent's PIE is
+    computed directly from OPP_PTS, OPP_FG, OPP_FGA, OPP_FTM, OPP_FTA,
+    OPP_DRB, OPP_ORB, OPP_AST, OPP_STL, OPP_BLK, OPP_TOV (and OPP_PF if
+    fouls are tracked), the same "eight factors"-style opponent context
+    `four_factors.py` uses for the defensive Four Factors.
+
+    Parameters
+    ----------
+    pie_col : an existing PIE column to reuse instead of recomputing it.
+        Defaults to computing PIE fresh via `add_performance_impact_estimator`.
+    """
+    r = resolver if resolver is not None else SchemaResolver(df.columns)
+    out = df.copy()
+
+    if pie_col is not None and pie_col in out.columns:
+        pie = pd.to_numeric(out[pie_col], errors="coerce")
+    else:
+        out = add_performance_impact_estimator(out, resolver=r)
+        pie = out["PIE"]
+
+    opp_required = [
+        "OPP_PTS", "OPP_FG", "OPP_FGA", "OPP_FTM", "OPP_FTA",
+        "OPP_DRB", "OPP_ORB", "OPP_AST", "OPP_STL", "OPP_BLK", "OPP_TOV",
+    ]
+    require_columns(r, opp_required, "add_team_impact_estimator")
+
+    g = lambda name: pd.to_numeric(r.get(out, name), errors="coerce").fillna(0.0)
+    opp_pf = g("OPP_PF") if r.has("OPP_PF") else pd.Series(0.0, index=out.index)
+
+    opp_pie = (
+        g("OPP_PTS")
+        + g("OPP_FG")
+        + g("OPP_FTM")
+        - g("OPP_FGA")
+        - g("OPP_FTA")
+        + g("OPP_DRB")
+        + 0.5 * g("OPP_ORB")
+        + g("OPP_AST")
+        + g("OPP_STL")
+        + 0.5 * g("OPP_BLK")
+        - opp_pf
+        - g("OPP_TOV")
+    )
+
+    out[new_col] = safe_divide(pie, pie + opp_pie)
+
+    if report is not None:
+        report.record(TIE_SPEC, Reliability.EXACT)
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Shooting efficiency and the usage/rate family
+# ---------------------------------------------------------------------------
+
+TS_SPEC = MetricSpec(
+    name="TS_PCT_CALC",
+    requires=("PTS", "FGA", "FTA"),
+    source="Basketball-Reference glossary; Oliver (2004)",
+    description="True shooting %: scoring efficiency including threes and free throws.",
+    notes="TS% = PTS / (2 * (FGA + c*FTA)). c = 0.44 NBA, 0.475 NCAA.",
+)
+
+
+def add_true_shooting_pct(
+    df: pd.DataFrame,
+    resolver: Optional[SchemaResolver] = None,
+    level: str = "ncaa",
+    new_col: str = "TS_PCT_CALC",
+    report: Optional[ComputationReport] = None,
+) -> pd.DataFrame:
+    """TS% = PTS / (2 * (FGA + c*FTA)).
+
+    The most complete single measure of scoring efficiency, since it accounts
+    for two-pointers, threes and free throws in one number. Prefer the
+    dataset's own TS% column when present.
+    """
+    r = resolver if resolver is not None else SchemaResolver(df.columns)
+    out = df.copy()
+    c = fta_coefficient(level)
+    require_columns(r, ["PTS", "FGA", "FTA"], "add_true_shooting_pct")
+
+    pts, fga, fta = r.get(out, "PTS"), r.get(out, "FGA"), r.get(out, "FTA")
+    out[new_col] = safe_divide(pts, 2.0 * (fga + c * fta))
+
+    if report is not None:
+        report.record(TS_SPEC, Reliability.EXACT)
+    return out
+
+
+USAGE_SPEC = MetricSpec(
+    name="USG_PCT_CALC",
+    requires=("FGA", "FTA", "TOV", "MIN"),
+    requires_team=("TM_MP", "TM_FGA", "TM_FTA", "TM_TOV"),
+    source="Basketball-Reference glossary",
+    description="Share of team possessions a player used while on the floor.",
+    notes="Requires team totals. Without them, use possessions-used per minute instead.",
+)
+
+
+def add_usage_rate(
+    df: pd.DataFrame,
+    resolver: Optional[SchemaResolver] = None,
+    level: str = "ncaa",
+    new_col: str = "USG_PCT_CALC",
+    report: Optional[ComputationReport] = None,
+) -> pd.DataFrame:
+    """Usage% = 100 * ((FGA + c*FTA + TOV) * (TmMP/5)) / (MP * (TmFGA + c*TmFTA + TmTOV)).
+
+    **Requires team totals.** BartTorvik supplies `usg` precomputed, so prefer
+    that. This exists for datasets that carry team aggregates.
+    """
+    r = resolver if resolver is not None else SchemaResolver(df.columns)
+    out = df.copy()
+    c = fta_coefficient(level)
+    require_columns(
+        r, ["FGA", "FTA", "TOV", "MIN", "TM_MP", "TM_FGA", "TM_FTA", "TM_TOV"], "add_usage_rate"
+    )
+
+    player_poss = r.get(out, "FGA") + c * r.get(out, "FTA") + r.get(out, "TOV")
+    team_poss = r.get(out, "TM_FGA") + c * r.get(out, "TM_FTA") + r.get(out, "TM_TOV")
+    out[new_col] = 100.0 * safe_divide(
+        player_poss * (r.get(out, "TM_MP") / 5.0), r.get(out, "MIN") * team_poss
+    )
+
+    if report is not None:
+        report.record(USAGE_SPEC, Reliability.EXACT)
+    return out
+
+
+def add_assist_pct(
+    df: pd.DataFrame,
+    resolver: Optional[SchemaResolver] = None,
+    new_col: str = "AST_PCT_CALC",
+    report: Optional[ComputationReport] = None,
+) -> pd.DataFrame:
+    """AST% = 100 * AST / (((MP / (TmMP/5)) * TmFG) - FG).
+
+    Share of teammate field goals a player assisted while on the floor.
+    **Requires team totals.**
+    """
+    r = resolver if resolver is not None else SchemaResolver(df.columns)
+    out = df.copy()
+    require_columns(r, ["AST", "MIN", "FGM", "TM_MP", "TM_FG"], "add_assist_pct")
+
+    mp, tm_mp, tm_fg = r.get(out, "MIN"), r.get(out, "TM_MP"), r.get(out, "TM_FG")
+    denom = safe_divide(mp, tm_mp / 5.0) * tm_fg - r.get(out, "FGM")
+    out[new_col] = 100.0 * safe_divide(r.get(out, "AST"), denom)
+
+    if report is not None:
+        spec = MetricSpec(
+            name=new_col,
+            requires=("AST", "MIN", "FGM"),
+            requires_team=("TM_MP", "TM_FG"),
+            source="Basketball-Reference glossary",
+            description="Share of teammate field goals assisted while on court.",
+        )
+        report.record(spec, Reliability.EXACT)
+    return out
+
+
+def add_rebound_pct(
+    df: pd.DataFrame,
+    resolver: Optional[SchemaResolver] = None,
+    which: str = "total",
+    new_col: Optional[str] = None,
+    report: Optional[ComputationReport] = None,
+) -> pd.DataFrame:
+    """Rebound percentage: share of available rebounds captured on court.
+
+        TRB% = 100 * (TRB * (TmMP/5)) / (MP * (TmTRB + OppTRB))
+        ORB% = 100 * (ORB * (TmMP/5)) / (MP * (TmORB + OppDRB))
+        DRB% = 100 * (DRB * (TmMP/5)) / (MP * (TmDRB + OppORB))
+
+    **Requires team and opponent totals.**
+
+    Parameters
+    ----------
+    which : {"total", "offensive", "defensive"}
+    """
+    r = resolver if resolver is not None else SchemaResolver(df.columns)
+    out = df.copy()
+
+    config = {
+        "total": ("REB", ["TM_TRB", "OPP_TRB"], "TRB_PCT_CALC"),
+        "offensive": ("OREB", ["TM_ORB", "OPP_DRB"], "ORB_PCT_CALC"),
+        "defensive": ("DREB", ["TM_DRB", "OPP_ORB"], "DRB_PCT_CALC"),
+    }
+    if which not in config:
+        raise ValueError(f"which must be one of {sorted(config)}, got {which!r}")
+
+    stat, team_terms, default_name = config[which]
+    target = new_col or default_name
+    require_columns(r, [stat, "MIN", "TM_MP"] + team_terms, f"add_rebound_pct({which})")
+
+    available = r.get(out, team_terms[0]) + r.get(out, team_terms[1])
+    out[target] = 100.0 * safe_divide(
+        r.get(out, stat) * (r.get(out, "TM_MP") / 5.0), r.get(out, "MIN") * available
+    )
+
+    if report is not None:
+        spec = MetricSpec(
+            name=target,
+            requires=(stat, "MIN"),
+            requires_team=tuple(["TM_MP"] + team_terms),
+            source="Basketball-Reference glossary; Oliver (2004)",
+            description=f"Share of available {which} rebounds captured while on court.",
+        )
+        report.record(spec, Reliability.EXACT)
+    return out
+
+
+def add_steal_pct(
+    df: pd.DataFrame,
+    resolver: Optional[SchemaResolver] = None,
+    new_col: str = "STL_PCT_CALC",
+    report: Optional[ComputationReport] = None,
+) -> pd.DataFrame:
+    """STL% = 100 * (STL * (TmMP/5)) / (MP * OppPoss).
+
+    Share of opponent possessions ending in a steal by this player.
+    **Requires team minutes and opponent possessions.**
+
+    Worth computing carefully: steal rate is one of the strongest known
+    college-to-NBA predictors (see `draft.py` and Vashro's work), and Myers'
+    BPM assigns it the largest positive coefficient of any box-score term.
+    """
+    r = resolver if resolver is not None else SchemaResolver(df.columns)
+    out = df.copy()
+    require_columns(r, ["STL", "MIN", "TM_MP", "OPP_POSS"], "add_steal_pct")
+
+    out[new_col] = 100.0 * safe_divide(
+        r.get(out, "STL") * (r.get(out, "TM_MP") / 5.0),
+        r.get(out, "MIN") * r.get(out, "OPP_POSS"),
+    )
+
+    if report is not None:
+        spec = MetricSpec(
+            name=new_col,
+            requires=("STL", "MIN"),
+            requires_team=("TM_MP", "OPP_POSS"),
+            source="Basketball-Reference glossary",
+            description="Share of opponent possessions ended by a steal.",
+            notes="Strong NBA-success predictor in the draft literature.",
+        )
+        report.record(spec, Reliability.EXACT)
+    return out
+
+
+def add_block_pct(
+    df: pd.DataFrame,
+    resolver: Optional[SchemaResolver] = None,
+    new_col: str = "BLK_PCT_CALC",
+    report: Optional[ComputationReport] = None,
+) -> pd.DataFrame:
+    """BLK% = 100 * (BLK * (TmMP/5)) / (MP * (OppFGA - Opp3PA)).
+
+    Share of opponent two-point attempts blocked. **Requires team minutes and
+    opponent shooting totals.** Block rate carries much of height's predictive
+    value for interior prospects.
+    """
+    r = resolver if resolver is not None else SchemaResolver(df.columns)
+    out = df.copy()
+    require_columns(r, ["BLK", "MIN", "TM_MP", "OPP_FGA", "OPP_TPA"], "add_block_pct")
+
+    two_pt_attempts = r.get(out, "OPP_FGA") - r.get(out, "OPP_TPA")
+    out[new_col] = 100.0 * safe_divide(
+        r.get(out, "BLK") * (r.get(out, "TM_MP") / 5.0), r.get(out, "MIN") * two_pt_attempts
+    )
+
+    if report is not None:
+        spec = MetricSpec(
+            name=new_col,
+            requires=("BLK", "MIN"),
+            requires_team=("TM_MP", "OPP_FGA", "OPP_TPA"),
+            source="Basketball-Reference glossary",
+            description="Share of opponent two-point attempts blocked.",
+        )
+        report.record(spec, Reliability.EXACT)
+    return out