Forward Contextual RAPM

Forward Contextual RAPM is the current gold-standard preseason model in this project. It retains an interpretable, one-number additive value for every player while carrying a separate nonlinear estimate of lineup composition from one completed season into the next. On the frozen 2025-26 regular-season holdout, it has the best game-margin RMSE, team net-rating error, and Pythagorean win-total error in the Frozen Preseason Leaderboard.

It is intentionally not one 30-season pooled nonlinear model. The state is updated one completed season at a time. That keeps both the player prior and the lineup-composition function on the same forward-looking information boundary.

Model State

For each season \(t\), the model maintains three pieces of state:

• \(\mu_{i,t}\): player \(i\)'s preseason RAPM prior.
• \(\beta_{i,t}\): player \(i\)'s completed-season additive coefficient.
• \(g_t(z)\): a nonlinear home-minus-away lineup-composition correction, where \(z\) is built from the two five-player lineups' trait profiles.

The published player ranking is \(\beta_{i,t}\), carried forward as the additive part of \(\mu_{i,t+1}\). The model does not try to allocate \(g_t\) to individual players because its value depends on the five-player combination. For example, the same high-usage guard can receive a different contextual correction next to four shooters than next to another ball-dominant creator.

Training Data And Player Profiles

The additive fit uses regular-season reconstructed stints. A row is a fixed home/away lineup interval with target \(y_{s,t}\), the home team's net rating over the stint, and weight \(w_{s,t}\), the number of possessions in that stint. The signed RAPM design vector \(x_{s,t}\) has \(+1\) for each home player and \(-1\) for each away player.

Every player in a season also receives a leakage-safe trait profile. Returning players use their immediately preceding season's possession-native box-score rates. Each rate is stabilized toward the historical league rate with 300 pseudo-possessions:

The raw profile contains three-point attempts and makes, assists, turnovers, usage events, offensive and defensive rebounds, steals, and blocks per 100 possessions. A first-season player has no previous NBA rates, so the profile is a draft-cohort profile blended toward the historical low-exposure replacement profile. The blend weight is the same forward exposure-gate probability used by the cold-start RAPM prior. Thus cold-start profiles are explicit estimates, not silent zero fills.

How This Differs From A Typical Box-Score Prior

Most box-score RAPM priors predict a single prior value for each player:

That scalar becomes the prior mean for player \(i\)'s RAPM coefficient. The box score is therefore answering a player-level question: how valuable should this player be expected to be in an average lineup context?

Forward Contextual RAPM does not turn these rates into another permanent player rating. It preserves the forward RAPM and cold-start state as the additive player prior, then uses the rate profiles only to construct a lineup-level term:

The correction belongs to the combination of five players, not to a single player. It can therefore represent diminishing returns and complements. A second high-usage player may have a different correction beside four shooters than beside another ball-dominant creator; an extra shooter may matter more in a lineup whose bottom two shooters are weak; and rebounding can saturate rather than rising linearly with each player's individual rebound rate.

This makes the box-score layer a structured lineup-synergy model rather than a conventional box-score prior. The distinction also preserves interpretability: the published player ranking remains the additive RAPM state, while \(g_t\) is reported and applied only when evaluating a concrete lineup.

Lineup Context Function

For a home lineup \(H\) and away lineup \(A\), \(z=\phi(H,A)\) contains home-minus-away differences in the nine player-rate totals above plus eleven composition summaries:

• Bottom-two three-point makes and the number of credible shooters.
• Top-two assists and concentration of usage in the top two players.
• Square-root transformed offensive and defensive rebounding totals.
• Counts and weights of imputed/replacement profiles.
• Shooting-by-usage, shooter-by-passing, and rebounding-by-usage interactions.

This construction deliberately captures diminishing and complementary lineup properties without pretending that a player has a fixed interaction value. For example, bottom-two shooting can distinguish a five-player unit with no credible floor spacing from one whose total shooting is carried by only one elite shooter.

The current contextual function is a possession-weighted spline Ridge model:

h applies a quadratic spline basis with four knots to each feature, then standardizes the expanded columns and fits Ridge regression. The large fixed alpha is a conservative first-pass regularizer. It shrinks nonlinear effects heavily while still allowing smooth saturation and interaction patterns. Alpha tuning is deliberately deferred until this state-transition design has been validated on additional frozen seasons.

Seasonal Transition

For season \(t\), the completed prior-season function \(g_{t-1}\) is scored on season-\(t\) preseason profiles and subtracted from each raw stint target:

The player coefficients are then fit with prior-centered, possession-weighted Ridge:

\(\lambda_t\) is held to the already-published season-specific value selected by the forward exposure-gated RAPM run. Holding that schedule fixed isolates the impact of the new contextual state transition instead of retuning two sources of regularization simultaneously.

After season \(t\) completes, the model computes raw residuals \(y_{s,t}-\hat a_t-x_{s,t}^{\mathsf T}\hat\beta_t\) and fits \(g_t\) to those residuals. The resulting \(\hat\beta_t\) and \(g_t\) become the state used for season \(t+1\). Returning players receive their completed \(\hat\beta_t\) as the next prior; first-season players use the forward exposure-gated cold-start prior. The first two historical seasons bootstrap the system before a completed context function exists.

This sequencing is the essential distinction: history influences the present only through repeated state updates, not because the model trains a pooled cross-era context function and applies it retrospectively.

Frozen Forecast Boundary

The 2025-26 holdout is scored using only:

• Completed 2024-25 player coefficients and cold-start state.
• The completed \(g_{2024-25}\) lineup-context function.
• 2025-26 pre-season player profiles, constructed from data through 2024-25.
• Realized 2025-26 lineups and possession exposure under the leaderboard's explicit oracle-allocation contract.

No 2025-26 regular-season or playoff result enters a 2025-26 prediction. The run fits and stores \(g_{2025-26}\) only after the frozen predictions are created, so that function is available for the 2026-27 state. A synthetic three-season regression test enforces this order: the 2025-26 evaluator must receive \(g_{2024-25}\), not \(g_{2025-26}\).

First Recursive Exemplar

artifacts/models/forward_contextual_rapm/2025-26/forward-contextual-rapm-2025-26-20260807T055233Z-b4da0c2c/ rolls the state from 1996-97 through 2025-26. For this controlled first pass, each RAPM season uses the already-published forward-RAPM lambda schedule and each contextual residual uses fixed Ridge alpha 10,000. Contextual alpha tuning is intentionally deferred so this experiment isolates the state transition.

The frozen 2025-26 forecast uses only the completed 2024-25 contextual model, 2024-25 player state, and 2025-26 preseason profiles.

A dedicated regression test enforces this boundary: the evaluator must receive g_2024-25; the subsequently fitted g_2025-26 may be stored for 2026-27 but cannot score the 2025-26 holdout.

The possession RMSE regression means this is not an unconditional replacement for every use case. The substantially better game, team NetRtg, and win-total results make it the project gold standard for its current oracle-lineup preseason contract. It still requires replication across additional frozen target seasons before claiming a general performance advantage.

Outputs

historical_player_coefficients.parquet and season_player_priors.parquet record the recursive player state. season_context_models.joblib stores one completed contextual model per season; season_context_metadata.parquet records its fixed alpha and fit diagnostics. Frozen possession, game, team NetRtg, and Pythagorean-win outputs use the standard leaderboard contract. The separate forward_contextual_rankings artifact records the completed additive player state used for the following season's public rankings.

2025-26 Lineup Context Case Study

These examples use the frozen g_2024-25 context function and 2025-26 preseason profiles. The context scores do not use 2025-26 point outcomes, but this retrospective case study does use the five-man units, opponent matchups, games, and possession exposure that actually occurred in 2025-26. It is therefore a frozen score conditional on realized lineup allocation, not a preseason forecast of which units would play.

Actual-matchup context is the possession-weighted correction in the unit's real 2025-26 opponents. Standardized context instead averages an orientation-symmetrized correction against the possession-weighted distribution of the 25 established units in this study, excluding the unit's own team:

All values are net-rating points per 100 possessions. Frozen additive is the preseason player-prior difference; frozen full adds frozen matchup context and the realized home/road mix. Observed NetRtg is descriptive and is not used to select or fit the frozen state.

Retrospective State Update

The same realized units can also be scored after 2025-26 concludes. Completed additive replaces the preseason player priors with the completed 2025-26 player coefficients. Completed full additionally replaces g_2024-25 with the completed g_2025-26 contextual function. Both completed columns are in-sample descriptive estimates: they use 2025-26 outcomes during fitting and must not be interpreted as a second forecast.

For a realized home/away stint \(s\), the two full estimates are:

The tables possession-weight these signed stint estimates over each unit's realized 2025-26 matchups. Thus the difference between the two full columns is the season's combined player-state and contextual-state revision.

The error summary is possession-weighted across the established units in these tables; it is a compact accounting of how the fitted season revised the frozen expectation, rather than an independent validation result.

Worked Context Decomposition

The highest-ranked unit is the LAC lineup of James Harden / Kawhi Leonard / Kris Dunn / Ivica Zubac / John Collins (614 possessions, 24 games). Its frozen standardized context effect is +2.60 points per 100 possessions.

For each original feature \(k\), the spline-Ridge pipeline produces five basis contributions. They are summed into \(q_k(L,O)\), then the displayed component is the possession-weighted orientation-symmetrized attribution:

Focal minus reference is the focal lineup's possession-weighted raw feature difference against the same realized 2025-26 reference units. Contribution is the model's nonlinear net-rating attribution, not a causal or individual-player credit. The total row exactly equals the unit's standardized context score.

Response Curves For Diminishing-Return Candidates

These curves isolate the frozen orientation-symmetrized spline component for relative usage events and relative defensive rebounds. Zero means equal focal and opponent feature values, and all other contextual features are held at zero. The blue band marks the 5th-to-95th percentile range observed when applying the model to 2025-26 stints; the orange line marks the Clippers unit's focal-minus-reference contrast. A flattening curve within the blue band is evidence that the fitted contextual residual is saturating for that feature.

For a single relative feature value \(z\), the plotted response is \(r_k(z)=[q_k(z)-q_k(-z)]/2\). This is the same orientation convention used by the standardized-context attribution, evaluated with every other contextual feature held at zero.

Interpretation

For usage events, the frozen component is approximately linear across the observed application band: it moves from -2.20 at the 5th-percentile difference (-25.29) to +2.19 at the 95th percentile (+25.65). The Clippers unit's relative usage contrast of +3.31 maps to an isolated response of +0.32. This frozen model does not show strong usage saturation in its observed application range.

Defensive rebounding is more nonlinear. Within the observed band, its largest positive component is +0.30 near a relative difference of +6.31, then it falls to +0.18 at the 95th-percentile difference (+7.77). The Clippers contrast is +6.05, with an isolated response of +0.29. That shape is consistent with diminishing marginal contextual value, but it is not a causal estimate of rebounding value.

The attribution table averages this response over each actual reference lineup, whereas the orange line evaluates it at the average raw feature contrast. With a nonlinear spline, \(\mathbb{E}[r_k(Z)]\) need not equal \(r_k(\mathbb{E}[Z])\), so those two displayed values need not match.

Table Definitions

• Rank: rank by frozen standardized context, used only to select the positive and negative examples.
• Poss. and Games: realized 2025-26 shared exposure for the five-player unit; both are eligibility filters, not model inputs.
• Standardized context: frozen g_2024-25 averaged over the established-unit opponent distribution of established lineups that actually appeared in 2025-26. It answers how favorable the unit's composition is against a shared realized reference schedule, not against a synthetic average lineup.
• Frozen matchup context: frozen g_2024-25 averaged only over the opponents the unit actually faced in 2025-26. It is the context component of Frozen full.
• Frozen additive: the signed sum of the five preseason player priors minus the five opposing preseason player priors, averaged over actual matchups.
• Frozen full: frozen additive value, frozen matchup context, and the unit's realized home/road mix. This is the frozen forecast for its realized allocation.
• Completed additive: the same additive calculation after replacing preseason priors with completed 2025-26 player coefficients.
• Completed matchup context: completed g_2025-26 averaged over the unit's actual 2025-26 opponents.
• Completed full: completed additive value, completed matchup context, and the same realized home/road mix. It is an in-sample retrospective estimate.
• Observed NetRtg: the unit's possession-weighted realized net rating in those same matchups. It is an outcome, never an input to the frozen forecast.

Eligibility: at least 250 shared possessions and 20 games. The tables are sortable.

Immutable case-study artifact: artifacts/models/forward_contextual_case_study/2025-26/forward-contextual-case-study-2025-26-20260807T213817Z-df8ecb4f.

The tables are ranked only by Standardized context: the frozen, opponent-standardized contextual effect. Frozen matchup context, the full model estimates, and Observed NetRtg do not determine rank.

Largest Positive Frozen Context Effects

Largest Negative Frozen Context Effects

2026-27 Player Rankings

These are the top 100 player priors carried from the completed 2025-26 forward contextual RAPM state. They are predictions for the next regular season, not retrospective rankings.

The one-number value is the model's additive player component. The completed lineup-context function g_2025-26 remains a separate lineup-level term, so it is not assigned to individual players. The table covers players who appeared in 2025-26; it does not yet add the incoming rookie class or account for offseason roster moves.

The table is sortable by every column. Adjustment is the completed-season movement from the preseason prior that entered the fit; interpret limited exposure alongside possession count.

Immutable ranking artifact: artifacts/models/forward_contextual_rankings/2026-27/forward-contextual-rankings-2026-27-20260807T130321Z-442539da.