Chapter 1
The Question
On June 13, 2026, the New York Knicks won the NBA championship in San Antonio, 94–90, taking the Finals four games to one. On the morning of that game we knew every game played so far that season: who played in it, for how long, and what happened while they were on the floor. How many points should we have expected each team to score?
That is the whole question this book answers, for every game on every day. Everything else, the ratings, the priors, the projected minutes, is there to answer it well. We start by making the question precise, then split it into two smaller ones that are easier to answer, and end the chapter with a map of the rest of the book.
1.1 What we predict
Definition 1.1 (Prediction). A game g is played on a day t_g between two teams, A and B. A prediction for g is a pair of numbers (\hat S_A, \hat S_B), the points we expect each team to score, computed from the games played before day t_g and nothing else.
From the pair we get the expected margin \hat S_A - \hat S_B and total \hat S_A + \hat S_B, and in Chapter 8 a probability that A wins.1 Expected is meant in the probabilist’s sense: \hat S_A is our estimate of \mathbb{E}[S_A], the mean of the score S_A over the games that could happen tonight. A refresher: for a random variable X taking values x with probabilities p(x), \mathbb{E}[X] = \sum_x x\,p(x); expectation is linear, so \mathbb{E}[S_A - S_B] = \mathbb{E}[S_A] - \mathbb{E}[S_B]. The final score is a long way from certain. The margin of an NBA game varies by about 14 points around anything a model can predict, so the goal isn’t to be right but to be less wrong, on average, than the alternatives.
The restriction to earlier games is the most important rule in the book. A model that peeks at the game it predicts, even a little, looks better than it is, and the program is built so that it can’t (Section 1.5).
1.2 Possessions and efficiency
A basketball game is a sequence of possessions. One team has the ball until it scores, misses and the other team rebounds, or turns it over; then the other team has it. A miss that the shooting team rebounds itself doesn’t end anything: the possession goes on, and a team that misses three times and scores on a putback has had one possession, worth two points.
Definition 1.2 (Possession). A team’s possession starts when it gains control of the ball and ends when the other team does. Its efficiency e in a game is its points per 100 possessions: a team scoring S points on P possessions has e = 100 S / P.
Since possessions alternate, the two teams in a game have almost the same number of them.2 Not exactly the same: whoever has the ball first in a period may also have it last. Over the 2016–2027 seasons, the two teams’ counts in a game never differ by more than 4. Call that number P, the game’s pace. Then the score splits into a product:
In the Finals clincher, San Antonio had 90 possessions and scored 90 points, an efficiency of 100.0, and New York scored 94 on 91, or 103.3. Both are far below the league’s regular-season average of 114.5, and so is the pace: about 90 possessions against the league’s 100. Finals games are slow, and Finals defenses are good.
This is an identity, not a model: any score can be written this way. Its value is that the two factors depend on different things. The pace P belongs to the game, since both teams share the same possessions, and it depends on how fast both teams like to play. The efficiency e_A depends on how good A’s offense is and how good B’s defense is. So we can predict them separately: pace from how fast the two teams’ games have been, and efficiency from the players on the floor. In 2026, Miami played the fastest, at 104.1 possessions per 48 minutes, and Boston the slowest, at 95.4; but Boston had the best offense, 119.5 points per 100 possessions, so the slow pace wasn’t hurting it. The best defense was Detroit’s, allowing 108.8.
Figure 1.1 shows the two factors over the last decade. Pace has been steady near 100 possessions a game. Efficiency has risen by nine points per 100 possessions, and it moves within a season too, so a model needs a sense of how many points the league scores right now, apart from how good any one team is. We return to this in Chapter 5.
Most of the book is about efficiency, since it’s where the teams differ most. A typical difference between two teams’ efficiencies is several points per 100 possessions, worth several points of margin, while their paces differ by a few possessions, worth only a fraction of a point of margin (Exercise 1.2).
1.3 Why players, not teams
The simplest model of efficiency gives each team an offensive rating
and a defensive rating, and says that A’s efficiency against B is the league’s average plus A’s offensive rating minus B’s defensive
one.3 This is the model behind Ken Pomeroy’s college basketball ratings, kenpom.com, and yarapm uses it as a baseline: the team model.
Fit to every game so far, it does well. But a team isn’t a fixed thing.
A star sits out with a sprained ankle, a trade sends two starters away,
a coach rests everyone on the second night of a back-to-back. A team’s
rating is an average over the lineups it has used, and tonight’s may be
different.
Golden State in 2026 is a clean example. Stephen Curry played 43 of the Warriors’ 82 regular-season games. They outscored their opponents by 4.0 points a game when Curry played and were outscored by 5.5 when Curry didn’t.4 A raw with-and-without split like this isn’t a fair measure of a player: other players were hurt at the same time, the schedule differed, and 39 games is a small sample. Chapter 3 is about doing it properly. But the size of the swing is the point here. A team rating sees a team that’s about even, -0.5 a game, and predicts every game as if the Warriors were that team. They never were: on any given night they were either a good team or a bad one, and whether Curry was on the injury report said which.
So yarapm rates players instead, and builds each team from the players expected to play tonight, weighted by how many minutes each will play. A player’s rating goes with them when they’re traded, and a missing player is simply left out. The price is that rating players is much harder than rating teams: there are about 450 of them in a season against 30 teams, and they play in groups of five.
| model | margin RMSE | log loss |
|---|---|---|
| home court only | 14.98 | 0.687 |
team ratings (team) |
13.93 | 0.636 |
| player ratings, who plays guessed | 13.71 | 0.624 |
| player ratings, who plays known | 13.58 | 0.613 |
Table 1.1 is the payoff. Predicting every game with only a home-court edge misses the margin by about 15 points. Rating teams cuts that to 13.9, and rating players to 13.7, or 13.6 when we know who will play. These differences look small, but most of the 13.6 is the randomness of a single game, which no model can remove. Even a model allowed to cheat, by using player ratings fit to the whole season including the games it predicts, only gets to 13.06. Against that floor, the step from teams to players is a good share of the error that can be removed at all.
1.4 The plan of the book
Figure 1.2 shows how the pieces fit. The raw material is play-by-play data: who was on the floor for each stretch of each game, and what happened. Chapter 2 cuts each game into lineup segments, stretches with the same ten players on the floor. Chapter 3 and Chapter 4 fit player ratings to them by regression, Chapter 5 adds the weighting that lets old games count less, and Chapter 6 gives every player a starting guess from box-score statistics. Chapter 7 combines the ratings with projected minutes and pace into an expected score, Chapter 8 measures how good the predictions are, and Chapter 9 follows the ratings day by day through ten seasons.
1.5 The no-peeking rule
Every model in this book is judged the same way. For each day of a season, we fit the model on the games before that day, predict that day’s games, and compare the predictions to what happened. This is called walk-forward testing, and it’s the only kind of testing that tells us how the model will do on games that haven’t happened yet. Any setting of the model, such as how fast old games are forgotten, is chosen by its walk-forward results on the 2021–2024 seasons, and the 2025–2026 seasons were held back and scored once, at the end, to check that the choices weren’t tuned to the noise in the four tuning seasons.
In the code. The data comes from nba_data, a separate
project that publishes NBA data as Parquet files with a DuckDB catalog.
connect() attaches it as nba,
so every query reads nba.<table>, and what yarapm
builds goes under out/, one Parquet file per season.
The no-peeking rule is enforced by a class: a model is fit on a History, whose every table is filtered to
games before the day being predicted, and that’s all it can see. Which
games count at all (regular season, play-in, playoffs and the Cup final,
but not preseason or the All-Star game) is decided in yarapm/games.py, which also treats the 2020
games in the Orlando “bubble” as played on a neutral court.
1.6 Notation
We use these symbols throughout. Ratings are in points per 100 possessions, so a rating of +2 means two more points per 100 possessions than average.
| symbol | meaning |
|---|---|
| i, j | players |
| s | a lineup segment, a stretch of a game with the same ten players |
| O_s, D_s | the five players on offense and on defense in segment s |
| n_s, y_s | the offense’s possessions and points in segment s |
| o_i, d_i | player i’s offensive and defensive ratings |
| \mu | the league’s average points per 100 possessions |
| P | a game’s pace, possessions per team |
| \lambda | a ridge penalty, in possessions (Chapter 4) |
Exercises
Exercise 1.1. A team scores 112 points on 98 possessions, and its opponent scores 104 on 97. What are their efficiencies? If both had had exactly 98 possessions at those efficiencies, what would the margin have been?
Exercise 1.2. Suppose both teams have P possessions. Show from Equation (1.1) that the margin is P(e_A - e_B)/100 and the total is P(e_A + e_B)/100. If e_A - e_B = 6, how much does the expected margin change when the pace goes from 96 to 104? Which team should want a faster game, the better one or the worse one?
Exercise 1.3. Why can’t two teams’ possession counts in a game differ by more than a few? What would have to happen for them to differ by two in one period?
Exercise 1.4. With DuckDB, attach nba_data’s catalog,
ATTACH 'https://basketball-data.billmill.org/nba/nba.duckdb' AS nba (READ_ONLY);and compute the league’s points per 100 possessions in the 2027
season so far from nba.team_game_logs (columns
season, pts and poss). Is it
higher or lower than 2026’s 114.5? (Filter on season: other
filters read every season’s file.)