chess_stats

Analyse your chess games and find out what kind of mistakes you actually make. Feed it a PGN export (e.g. from Chess.com or Lichess) and a UCI engine; it replays every game, compares your moves to the engine, and classifies each blunder by tactical theme — hanging piece, fork, pin, skewer, discovered attack, deflection, zwischenzug, missed mate, and more — then writes a CSV you can pivot in any spreadsheet.

Requirements

• Python 3.9+ and python-chess:

  pip install -r requirements.txt

• A UCI engine binary (e.g. Stockfish). It is not bundled — you pass its path on the command line.

Use

python tactics_stats.py <engine_path> <games.pgn> "<your_name>" [think_time] [drop_cp] [mate_max] [threads]

Arg	Meaning	Default
engine_path	Path to the Stockfish/UCI binary	—
games.pgn	Your PGN export	—
your_name	The player name to analyse (matched case-insensitively)	—
think_time	Seconds per position	0.12
drop_cp	Centipawn loss that counts as a mistake	250
mate_max	Max mate distance to flag	3
threads	Engine threads	16

Example:

python tactics_stats.py /usr/bin/stockfish chess_com_games.pgn "MyUsername" 0.2

Results are written to mistakes*.csv (theme, phase, move, eval swing, …).

How it works

For each of your moves the engine is evaluated before and after, the centipawn loss is measured, and any move losing more than drop_cp is tagged with the tactical motif that explains it (using material-imbalance and pattern heuristics). Mistakes are bucketed by game phase (opening / middlegame / endgame) so you can see where and how you tend to go wrong.

Notes

• The detection thresholds (drop_cp, think_time, mate distance) are heuristics — tune them to taste; deeper think_time gives more reliable verdicts but runs slower.
• tactics_stats.py is the current version. Earlier iterations are kept under archive/ for reference.
• Your PGN exports and the generated CSVs are git-ignored (they're your personal data).

License

MIT — see LICENSE.