Stats
Screen states, calculation rules, data sources, and progress behavior for repertoire analysis.
Purpose and access
Stats evaluate a saved study against a selected pool of real games. The studied side is assumed to remember and always play its prepared move. Opponent replies are weighted by their frequency in the selected Lirep or Lichess Explorer source.
The Stats page requires Lichess sign-in. Show a sign-in prompt when signed out and “Study not found” when a requested ID is unavailable to the account.
Study cards
- The home page groups study cards by studied side. Each card shows the study name, its expected result (the expected score and the expected evaluation, as in “57.4% / +0.31”, with a dash for one not calculated yet), its opening moves, and under them its number of moves and lines. The community leaderboards show their studies in the same cards, with the rank, the author, the value they rank by in bold, and the calculation settings folded under the result. In place of the opening moves, a small board shows the starting position (the moves to it on a line under it) and, while the mouse is over the card, plays the main line: at each branching, the move with the most moves prepared after it.
- Every card's Stats button opens the study's Stats page, including cards without a calculated score. Calculations are started from the Stats page; the cards have no Calculate/Recalculate button or job sequence.
Study detail screen
Open at stat.html?id={studyId}. From top to bottom: the header, the calculation settings, the expected score, its coverage chart, the expected evaluation, and practice knowledge.
- Header: the study's badge: a piece in its tier's colour, the piece from the expected evaluation (a pawn under +0.25, then a knight, bishop, rook, queen from +0.90 and the king from +1.00; the pawn while not calculated). Click it for the legend of both, study name, Playing White/Black badge, the custom starting point if one is set, and links to edit the study and to practice it. The tier is by expected score, by side. For White: Legendary at 60%+, Brilliant at 59%+, Gold at 57%+, Silver at 54%+, Bronze at 52%+ (about White's average in the Explorer), no tier below; Black's thresholds are 4 points lower (Bronze at 48%, Silver at 50%…).
- Calculation settings: one panel holding every input of both calculations. Collapsed, it shows a one-line summary (e.g. “Lichess · 2000+ · blitz, rapid · Explorer results · Stockfish depth 16”) and an Edit button. Expanded, it shows the Opening Explorer settings, which weight the opponent's replies for both results; the end-of-prep value of the expected score (Explorer results, Stockfish, or Hybrid; see the three values; saved with the study's settings, and also chosen in the editor's settings, whose live figures follow it); and the Stockfish depth (Quick 8, Balanced 12, Thorough 16), used for the expected evaluation and for the expected score when Stockfish values lines' ends. Like the end-of-prep value, the depth is saved with the study's settings (
explorerSettings.depth) and shared with the editor, whose figures and suggested moves use it; a study saved before it existed uses this browser's default (Thorough 16 unless another was chosen), and its results calculated at another depth show as out of date until recalculated. Save saves the settings as the study's (the editor's, too), and closes the panel; results calculated with other settings then show as out of date. A calculation also saves the settings it runs with first. Below it, Recalculate runs both calculations with the settings shown, one after the other, and a line says whether the results are up to date. - Expected score: the score as a percentage (a win = 1, a draw = 0.5, a loss = 0, from the studied side's point of view), the win/draw/loss split (only with Explorer values), the settings, end-of-prep value and depth, position count (and, with the Stockfish fallback, how many positions Stockfish valued) and time it was calculated with.
- Coverage: a card of its own under the expected score, whose calculation produces it; it is out of date whenever the expected score is.
- Expected evaluation: a weighted Stockfish score in pawns, shown from White's point of view as on Lichess (−0.40 is Black's advantage, also in a Black study), with two decimals and a sign, or “White mates” / “Black mates” for capped mate values; the settings, depth and time it was calculated with. If end positions lacked an engine evaluation, they contribute 0.00 and the card says how many. Older server-calculated summaries are marked as legacy until recalculated.
- Practice knowledge: average recall across positions, or a note when there is no practice data, with a link to practice.
Each result has its own Recalculate button, shows “Not calculated yet” when empty, and shows two status lines:
- Out of date, when the settings currently in the panel differ from the ones it was calculated with (Explorer settings; the end-of-prep value for the expected score; the depth for the expected evaluation, and for the expected score when Stockfish values lines' ends), or when the moves or starting point changed since. Changing a setting only marks results out of date; nothing recalculates until a Recalculate button is pressed. Moves are compared through a fingerprint of the tree (every move, in order, and the starting point; not comments) that the backend returns as
movesFingerprintand stores with each result. Results saved before fingerprints existed are not flagged for moves. - Leaderboard status: its rank on the community leaderboard (among results from the same Explorer, so a result from the 2016 sample gets its rank in that view), or why it is not listed (study not shared, one player's games, depth below 12 or unknown, or outside the top ten).
Calculation definitions
Expected score and coverage
The opponent's weights are exclusively Opening Explorer-derived; the value of each line's end depends on the end-of-prep value setting (leafValue): explorer (the default), stockfish, or explorer-stockfish. Walk from the effective starting node. A line ends with its last answered move and, with explorer, counts with that move's own Explorer W/D/L result, as listed in the position before it; an opponent move in the tree without a prepared answer is ignored, as if it weren't there. At an opponent turn, fetch that position's move list and weight each listed move by its game count divided by the total listed games: recurse into replies the tree answers; any other reply ends that branch with its own W/D/L result. At a studied-side turn, follow its sole prepared move; if no opponent reply after it is answered, the line ends with it (its own result; if Explorer doesn't list it, neutral expected score .5). A terminal result inside the tree is exact (win 1, draw .5, loss 0). The starting position with nothing prepared counts its own Explorer result; with no Explorer games, use neutral expected score .5.
With stockfish, a line's end is worth the local Stockfish evaluation, at the selected depth, of the position the line's last move leads to, converted to an expected score by \(1/(1+e^{-0.00368208\,c})\), with \(c\) in centipawns from the studied side's point of view; a position without a usable engine score counts as 0.00. Where an opponent position inside the tree has no Explorer games, that position is evaluated. A line ending with the studied side's move is valued before the opponent's reply, not after each Explorer reply: one evaluation per line, and the opponent's likely mistakes on that move don't count. With explorer-stockfish, a line's end uses the Explorer row when it has at least 100 games (MIN_LEAF_GAMES; 50 until October 2026: a Hybrid score saved without its threshold, leafGames, used 50 and is marked out of date), Stockfish's value otherwise (and where an opponent position has no Explorer games). Stockfish values carry no W/D/L split: winRate and lossProbability are then null and only the score is saved. Evaluations share the browser's per-FEN, per-depth cache with the expected evaluation. Explained with diagrams and a worked example.
Interpretation caveat: after play leaves your study, Explorer results reflect what players in the selected pool actually did next, including any prepared follow-up: an average over all players reaching the position, not over unprepared ones, so it tends to overstate your score. Stockfish values avoid that bias but can differ widely from how humans score.
Coverage tracks probability mass that remains inside the tree under the same opponent move weights. Start at 1.0. Studied-side moves preserve mass; opponent moves split it by frequency; mass on a reply the tree doesn't answer (absent, or present without a prepared answer) exits the book. Record the remaining mass after each opponent move. Thus coverage can only drop on opponent replies. The tooltip also reports the number of tree moves/branches represented at that depth, a structural count rather than a weighted count.
Expected evaluation
The expected score's walk with the stockfish end-of-prep value (same lines' ends, same evaluated positions), averaging the evaluations in centipawns instead of the converted scores; calculateExpectedScore returns it as evalCp. A line ending with the studied side's move is evaluated in the position after that move; a reply the tree doesn't answer, in the position after the reply; an opponent position with no Explorer games, in that position. Each evaluation is capped at ±1,000 centipawns (EVAL_CAP_CP): a forced mate, or checkmate on the board, counts as ±1,000; draws are 0. The expected score converts the uncapped evaluations. Saved evaluations carry evalMethod 3; earlier ones are shown out of date (“the calculation method changed”) and left off the leaderboard until recalculated: method 2 didn't cap evaluations (mates counted ±100,000), and method 1 (missing) also evaluated the positions after each Explorer reply to a studied-side move instead. Store evaluations in White's POV, then convert to the studied side's POV for the result (saved and ranked as such: the leaderboard puts the best for the studied side first). Display cp as pawns (cp / 100) in White's POV (formatExpectedEval).
Explorer move lists are capped by Lichess (roughly the top dozen moves), so rare omitted moves are not separately modeled. A custom start node changes the calculation root only; it does not trim or renumber the tree. Coverage move numbers are relative to that start node and the chart identifies which opponent move each point follows.
Calculations
The two results are calculated independently; each updates its own fields and timestamp without clearing the other. Recalculate runs both in turn; each result's own button runs it alone. All buttons are disabled while a calculation runs; on failure, the message shows beside the result's progress bar and the buttons come back. Both calculations save the settings they used as the study's Explorer settings.
Expected score
Runs in the browser (frontend/src/expectedScore.ts): the weighted tree walk for the score, its win/draw/loss probabilities and coverage, with Explorer data from the browser. Stockfish starts only when a line's end needs it (end-of-prep value stockfish or explorer-stockfish), one position at a time, reusing cached evaluations. Progress is estimated from the tree's size, because the number of positions is not known in advance. The results, the end-of-prep value, the Stockfish depth (when Stockfish values lines' ends), the number of positions Stockfish valued and the Explorer settings used go to POST /api/studies/{id}/expected-score, which checks their ranges and saves them with the moves fingerprint (as leafValue, scoreDepth and stockfishLeaves). A changed end-of-prep value, or a changed depth when Stockfish values lines' ends, marks the score out of date.
Explorer requests
Both calculations, and the Explorer panels, ask Lichess's Explorer directly from the browser with the user's own token (from GET /api/lichess-token, scope preference:read only), so each user's requests count against their own Lichess rate limit instead of all sharing the server's. Requests are paced: one at a time, at least 500 ms apart; after an HTTP 429, everything waits 60 seconds, then a calculation's request retries once while its progress label says so, and a panel's request fails at once with a wait-a-minute message. Panel requests go ahead of a calculation's queued ones. Responses are cached in the browser's IndexedDB for a year (24 hours for the player database). Since the browser calculates the results, the server cannot verify them beyond their ranges. See doc/explorer-cache.md.
Expected evaluation
Runs in the browser. First discover the positions where lines end with a walk that doesn't evaluate (stockfishPositions), starting at the effective starting node: it follows prepared moves and fetches opponent replies from the Explorer; terminal positions need no engine score. Reuse this account's cached FEN evaluations at the selected depth on this device and run local Stockfish only for missing FENs; results at different depths are cached separately. Store each completed White-POV centipawn value in browser IndexedDB immediately, so interrupted runs can resume. Live Study/Practice analysis keeps its fixed default depth.
Then perform the Explorer-weighted tree walk locally. A position without a usable engine score contributes 0.00 and is counted in evalMisses; there is no Cloud Eval fallback. Send evalCp, evalMisses, the Stockfish depth, the method (3), and the selected explorerSettings to synchronous POST /api/studies/{id}/expected-eval. The backend saves the summary, the depth, the settings (as evalSettings, apart from the expected score's) and the moves fingerprint, not per-position evaluations. The page opens with the study's depth (see the calculation settings above).
The community page's leaderboards have a Metric switch (Expected score / Expected evaluation) next to the Explorer data one; the expected-evaluation view ranks by expected evaluation. It lists only evaluations at depth 12 (Balanced) or more, under the same Explorer rules as the score leaderboard: never one player's games, and one Explorer's results at a time. Both leaderboards rank Lichess's Explorer results by default; when some shared study has results from the local Lirep Explorer (the 2016 sample), an “Explorer data” switch (Lichess / 2016 sample) shows those ranked on their own, since the two aren't comparable. Evaluations saved before the depth was recorded, or with an older method than 3, are not ranked until recalculated.
The expected-score view ranks scores together however lines' ends were valued; a row's settings say when Stockfish valued them, alone or as a fallback, and at what depth. Scores saved before the setting existed count as Explorer values. Scores valued with Stockfish are ranked only at depth 12 or more.
Explorer settings
Each study saves its own Explorer settings, shown and editable on its Stats page and in the study page's Explorer panel. Expected score, coverage and expected evaluation are all calculated from the Explorer data these settings select, and the community leaderboards show, next to each result, the settings it was calculated with.
Data source
- Lirep: Lirep's own copy of Lichess's open-source opening explorer, seeded with games from Lichess's public database (released under CC0). It currently holds the rated standard games from February to April 2016, about 16.7 million games. It has no rate limit, its responses are not cached because they never change, and it has no Masters database. The data is a subset: two months of mostly 2016-era play, so move frequencies may differ from today's. Lirep is offered only when the server has its local explorer configured.
- Lichess: Lichess's hosted opening explorer, with its full and up-to-date databases. It is rate-limited and requires Lichess sign-in, so it is queried from the user's browser with their own token, paced and cached as described under Explorer requests.
Database
- Players: games between Lichess players, filtered by rating and speed. Available from both sources.
- Masters: over-the-board games by strong players (rated 2200 FIDE and above). Only from Lichess; it disables the rating and speed controls, which do not filter it.
- Player: one named player's games as the studied side (like the Player tab of Lichess's explorer), defaulting to the signed-in account. Always queried from Lichess, whatever the source setting; it disables only the rating control. Scores calculated from it are not ranked on the community leaderboard, since they describe one player rather than the whole pool.
Rating and speed
- For Players, select a fixed rating threshold; that bucket and every higher bucket are included. A new study starts at 1600+, as the Browse page's openings are calculated with; it's a one-time default like any other saved setting. A study saved before the threshold was always stored counts as 1400+.
- Bullet, Blitz, Rapid, and Classical checkboxes; default to Blitz (as the Browse page's openings are calculated with), and always require at least one speed.
When settings take effect
Changing the controls on the Stats page alone does not trigger calculation. The next expected-score or expected-evaluation calculation sends the selected settings and saves them as the study's new settings (not a temporary preview), so subsequent views and calculations use them.
Coverage chart and caching
Render a responsive line chart with percentage on the vertical axis and the studied opponent's move number on the horizontal axis. The chart stops at the last move still reached by at least 0.5% of games, so a deep tree doesn't end in a long flat line at zero. Hovering near the line shows opponent move number, coverage percentage, and number of remembered moves at that depth. If no coverage is stored, show an explanatory empty state and require recalculation to populate it.
Lichess Explorer responses are cached in the browser's IndexedDB, per browser profile, for a year (24 hours for the player database); local Lirep explorer responses are not cached. Per-user rating buckets persist in backend SQLite. Engine evaluations are keyed by username, FEN, and search depth in browser IndexedDB, per account and per device, not synced. Clearing browser data forces recomputation; when IndexedDB is unavailable (including private modes that block it), evaluations last only for the current page/tab visit. On loading a study, legacy server-side evals.byNode values are imported into the local FEN cache at the old default depth where absent. An older database may still contain the unused cloud_eval_cache table, but new databases do not create it. The /api/studies/{id}/evals and /api/eval-cache/lookup endpoints have been removed.
Interpretation and limits
- Expected score with Explorer values reports game results, not engine quality. It can disagree with expected evaluation; this is intentional.
- All results assume perfect memorization and one prepared move at each studied-side decision. They do not model mistakes by the user.
- Opponent frequencies reflect the selected current pool, not move quality. Sparse data, capped move lists, and changes in current ratings affect estimates.
- Local Stockfish is fixed-depth and runs on the user's device. Missing local evaluations contribute 0 and are reported; no Cloud Eval fallback is used.
- Recalculation is manual because Explorer requests and local engine searches may take time; changed settings or moves only mark results out of date. Both calculations persist the selected Explorer settings.