{"id":15608686,"url":"https://github.com/ianfab/chess-analysis","last_synced_at":"2025-07-16T11:33:07.965Z","repository":{"id":82394060,"uuid":"579717645","full_name":"ianfab/chess-analysis","owner":"ianfab","description":"Evaluate quality of play metrics for chess","archived":false,"fork":false,"pushed_at":"2023-02-02T22:35:50.000Z","size":24,"stargazers_count":8,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-28T11:50:41.902Z","etag":null,"topics":["acpl","chess","epd","pandas","pgn","python","python-chess","stockfish"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ianfab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-12-18T17:00:57.000Z","updated_at":"2025-02-16T15:21:35.000Z","dependencies_parsed_at":"2023-06-15T11:45:11.539Z","dependency_job_id":null,"html_url":"https://github.com/ianfab/chess-analysis","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ianfab/chess-analysis","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ianfab%2Fchess-analysis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ianfab%2Fchess-analysis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ianfab%2Fchess-analysis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ianfab%2Fchess-analysis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ianfab","download_url":"https://codeload.github.com/ianfab/chess-analysis/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ianfab%2Fchess-analysis/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265506025,"owners_count":23778637,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["acpl","chess","epd","pandas","pgn","python","python-chess","stockfish"],"created_at":"2024-10-03T05:21:54.162Z","updated_at":"2025-07-16T11:33:07.862Z","avatar_url":"https://github.com/ianfab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Chess analysis\n\nThis project analyses chess games using Stockfish and python-chess, and aggregates statistics such as ACPL and related metrics using pandas.\n\nThis can be either used to analyze the quality of play depending on various properties such as Elo, player, etc., or to evaluate the metrics themselves against objective quality of play indicators such as Elo and result.\n\n## Process\n1. `pgn2epd.py` generates an EPD file from a given PGN.\n2. `analyze.py` analyzes positions from an EPD file and annotates them.\n3. `stats.py` aggregates statistics from an annotated EPD file.\n\n## Setup\nThe scripts require python3 as well as the dependencies from the `requirements.txt`. Install them using\n```\npip3 install -r requirements.txt\n```\nIn order to ensure that best and player moves are evaluated within the same search, a [custom version of stockfish](https://github.com/ianfab/Stockfish/tree/ensuremove) and [python-chess](https://github.com/ianfab/python-chess/tree/ensuremove) are used that support this feature.\n\n## Output\nThe main focus of this project is to quantify quality of play using various metrics comparable to but different from average centipawn loss (ACPL). Metrics can have different strengths and weaknesses depending on their design, e.g.:\n* Weighting: Metrics such as (uncapped) ACPL can give extremely large weight to single moves compared to the rest of a game, which can skew results.\n* Bias: Using summative metrics can lead to a strong correlation with game length, which is undesirable.\n* Exploitability: Using averaging can make metrics susceptible to biases by long sequences of moves not affecting the result, e.g., playing on in dead drawn or losing positions.\n\nSome ways to attempt to make metrics more robust are:\n* Capping values/differences can limit the influence of a single move.\n* Using expectation values (EV) and their differences (expected loss, EL) instead of raw centipawn (loss) values transforming to a limited range mitigates the weighting problem.\n* Normalizing by the potential for loss, e.g., dividing by the maximum possible loss, leads to more equal weighting of decisions.\n\nSome abbreviations used in the names of metrics:\n* base metric\n  * CP/CPL: centipawn / centipawn loss\n  * EV/EL: expectation value / expected loss\n* transformation\n  * C: capped\n  * SF: stockfish win-rate model\n  * L: lichess win-rate model\n* aggregation\n  * T: total\n  * A: average\n  * N: normalized\n  * EW: equal weighted\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fianfab%2Fchess-analysis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fianfab%2Fchess-analysis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fianfab%2Fchess-analysis/lists"}