NBA Free Agent Valuation Model

The CBA bounds every salary from both sides. A max contract is capped at 25, 30 or 35% of the cap depending on service and awards, and nothing can be signed below the veteran minimum. A player worth 40% of the cap is paid 35%, so the recorded salary is a bound, not a price. Train an ordinary regression on those rows and it learns to predict the bound.

The chart holds every negotiated first-year contract the model trains on. Height is what the player was paid; position across is the Stage 1 latent value, what the model thinks an open market with no CBA would pay. In the middle the two agree and the points follow the diagonal. At the top, max deals stack on their tier ceilings while the latent keeps going. At the bottom, minimum deals stack on the floor, and their latents split: about half sit below it, held up by the rule, and the rest spread to the right, players the market would have paid more who took the minimum anyway. That second group is not censoring, and it comes back under Limits.

Salaries come from Basketball Reference and Spotrac cap hits, the impact metrics DARKO, LEBRON and LAKER from nbarapm.com, and the bounds from the CBA itself. Stats lag salary by one season on purpose: a contract signed in July is priced on the season that just ended.

Years two and later of a contract are CBA escalators, rookie deals are slotted by draft position, and partial-season pay depends on the signing date. None of those is a price the market set, so each filter below removes one of them. Thresholds are shares of the cap, never dollar figures, because the minimum and the max move with the cap.

A feature must exist before the contract is signed and must not be derived from the salary. Each one entered through the same gate: rerun cross-validation on identical folds with and without it, and require the fold-by-fold improvement to clear t > 2.

The bars show how far each feature moves a prediction on average, as mean absolute SHAP in dollars over the training contracts. Minutes per game dominates on its own; the market trajectory and the Kalman quality estimate are the two engineered features that come next.

Stage 1 is XGBoost, 500 trees of depth 4, with the loss replaced on censored rows. Grabit (Sigrist & Hirnschall, 2019) comes from credit-risk modelling and uses a censored-normal likelihood. For a max contract the observed salary is only a lower bound on the latent value, so the gradient never drags the prediction down to it. For a minimum deal the observation is an upper bound, and the gradient is mirrored.

Move the prediction. Squared error always pulls it back to the observed salary. Grabit pushes while the prediction sits at or below the bound and lets go above it; σ = 2% of the cap sets how wide that hand-off is.

The trees are not the whole of Stage 1. Two linear terms enter as the base margin, so the trees fit what is left around them: one for players bought out of money they were still owed, one for players likely to sign a max. Each coefficient is a censored-likelihood fit on out-of-fold predictions inside every training slice.

Stage 2 maps the latent value to a legal price: nothing above the player’s tier ceiling, nothing below the league floor. Both bounds are knowable before the market opens, the ceiling from service years and awards, the floor from season and experience. The clip never reads the observed salary.

Until v6.3.0 Stage 2 also pushed likely-max players toward the ceiling after the fit, behind a P(max) ≥ 0.52 gate, because a clip can only cap from above. The P(max) term in Stage 1 replaced it. The lift is now fitted, the censored loss and the trees see it, and a knife-edge gate no longer decides who gets it.

Some limits exist only once you know how a deal was signed. An extension’s first year is capped at 140% of prior salary (120% before the 2023 CBA) or the same multiple of the league’s average salary, whichever is greater. Early Bird and Non-Bird deals have their own ceilings. A team holding a player’s Bird rights pays a retention premium that no performance feature can see.

Stage 3 applies these in a fixed order: a per-route offset, the mechanism cap, the extension cap, then the [floor, ceiling] clip again. Every cap can only lower a prediction, and the final clip means no correction can price a contract the CBA would not allow.

Decisions use repeated grouped CV: five folds of players, never rows, so one player’s contracts never sit on both sides of a split. Each of ten seeds deals the players by a fixed hash of its own partition, so adding a row never moves anyone else. Deltas are paired by fold, because fold-to-fold spread dwarfs seed-to-seed spread.

Forecasting is measured on its own by rolling origin, because that is what inference does: train on every season before T, predict T. A 15% confirmation split of players stays out of every selection decision.

The remaining error is mostly not a modelling problem. It is information the public data does not hold.