Team Ai
Datasetpublic

angeluriot/chess_games

โ™Ÿ๏ธ Chess games The Chess games dataset is a collection of high level chess games for training machine learning models. ๐Ÿ“Š Overview The dataset is composed of 14M chess games from high level players for a total of 1.2B moves played between 1600 and 2024 (although most of them are recent): The mean ELO of the players is 2388: The mean number of moves per game is 84 (with a maximum of 692 moves): Most of the games were ended by aโ€ฆ See the full description on the dataset page: https://huggingface.co/datasets/angeluriot/chess_games.

sourceHugging Facemitupdated 2y agoView on Hugging Face
4likes403downloads
Dataset Card

โ™Ÿ๏ธ Chess games

The **Chess games dataset** is a collection of high level chess games for training machine learning models.

<p align="center"> <img src="resources/misc/thumbnail.png" width="750"> </p>

<br/>

๐Ÿ“Š Overview

The dataset is composed of 14M chess games from high level players for a total of 1.2B moves played between 1600 and 2024 (although most of them are recent):

<p align="center"> <img src="resources/misc/dates.png" width="575"> </p>

The mean ELO of the players is 2388:

<p align="center"> <img src="resources/misc/elos.png" width="575"> </p>

The mean number of moves per game is 84 (with a maximum of 692 moves):

<p align="center"> <img src="resources/misc/moves.png" width="575"> </p>

Most of the games were ended by a resignation or a draw agreement:

<p align="center"> <img src="resources/misc/ends.png" width="725"> </p>

<br/>

๐Ÿ—ƒ๏ธ Data Structure

Each record in the dataset follows the structure below:

json
{
    "date": "date of the game (string like 'YYYY.MM.DD' or null)",
    "white_elo": "ELO of the white player (int or null)",
    "black_elo": "ELO of the black player (int or null)",
    "end_type": "how the game ended (string in ['resignation', 'checkmate', 'insufficient_material', 'draw_agreement', 'stalemate', 'fivefold_repetition', 'seventyfive_moves'])",
    "winner": "the winner of the game (string in ['white', 'black'] or null)",
    "moves_san": [
        "move in Standard Algebraic Notation (string, ex: 'Nxg3+')",
        ...
    ],
    "moves_uci": [
        "move in Universal Chess Interface (string, ex: 'h5f4')",
        ...
    ],
    "moves_custom": [
        "move in a custom notation for easier processing (string, ex: 'w.โ™˜e2โ™˜g3.x.+')",
        ...
    ],
    "source": "The source of the game (string)"
}

<br/>

๐Ÿ“ Custom move notation

The moves_custom field is a custom notation that gives more information about the moves, it's composed of 4 parts separated by a dot:

  1. 1.The color of the player (w for white and b for black)
  1. 1.The state of the moved pieces before and after the move:
  2. 2.For example, a white knight moving from e2 to g3 would be represented as: โ™˜e2โ™˜g3
  3. 3.If a piece change during the move, like a white pawn becoming a white queen, it would be represented as: โ™™e7โ™›e8
  4. 4.If multiple pieces are moved, like in a white kingside castling, it would be represented as: โ™”e1โ™”g1โ™–h1โ™–f1
  1. 1.x if a piece is captured during the move and x* if the capture is en passant
  1. 1.+ if the move is a check and +# for checkmate

An impossible move with every parts could look like this: w.โ™”e1โ™”g1โ™–h1โ™–f1.x*.+#

<br/>

๐Ÿ”— Sources

The table below shows the distribution of the games in the dataset by source:

<table> <thead> <tr> <th align="center">Source</th> <th align="center">Games</th> <th align="center">Ratio</th> </tr> </thead> <tbody> <tr> <td align="left"><b><a href="https://lichess.org/team/lichess-elite-database">Lichess Elite Database</a></b></td> <td align="center">5,525,245</td> <td align="center">38.94 %</td> </tr> <tr> <td align="left"><b><a href="https://lumbrasgigabase.com/en/">Lumbras Giga Base</a></b></td> <td align="center">3,701,341</td> <td align="center">26.09 %</td> </tr> <tr> <td align="left"><b><a href="https://www.pgnmentor.com/">PGN Mentor</a></b></td> <td align="center">3,431,537</td> <td align="center">24.19 %</td> </tr> <tr> <td align="left"><b><a href="https://theweekinchess.com/">The Week in Chess</a></b></td> <td align="center">858,163</td> <td align="center">6.05 %</td> </tr> <tr> <td align="left"><b>Masters</b></td> <td align="center">322,166</td> <td align="center">2.27 %</td> </tr> <tr> <td align="left"><b><a href="https://lichess.org/broadcast">Lichess Broadcast</a></b></td> <td align="center">105,329</td> <td align="center">0.74 %</td> </tr> <tr> <td align="left"><b><a href="https://chessok.com/">Chess OK</a></b></td> <td align="center">62,895</td> <td align="center">0.44 %</td> </tr> <tr> <td align="left"><b><a href="https://www.saund.co.uk/britbase/">BritBase</a></b></td> <td align="center">60,148</td> <td align="center">0.42 %</td> </tr> <tr> <td align="left"><b>KingBase</b></td> <td align="center">59,317</td> <td align="center">0.42 %</td> </tr> <tr> <td align="left"><b>Convekta</b></td> <td align="center">37,536</td> <td align="center">0.26 %</td> </tr> <tr> <td align="left"><b>Chess Nostalgia</b></td> <td align="center">24,592</td> <td align="center">0.17 %</td> </tr> <tr> <td align="left"><b><a href="https://www.chessopolis.com/">Chessopolis</a></b></td> <td align="center">123</td> <td align="center">&#60;0.01 %</td> </tr> <tr> <td align="left"><b>Games Of GMs</b></td> <td align="center">62</td> <td align="center">&#60;0.01 %</td> </tr> <tr> <th align="left"><b>Total</b></th> <th align="center"><b>14,188,454</b></th> <th align="center"><b>100.00 %</b></th> </tr> </table>

Special thanks to <b><a href="https://lumbrasgigabase.com/en/">Lumbras Giga Base</a></b> for collecting the other sources, the games of this dataset are directly taken from their website.

<br/>

๐Ÿ› ๏ธ Usage

The **Chess games dataset** is mainly intended for training machine learning models, but it can also be used for other purposes like data analysis or data visualization.

The simplest way to use the dataset is to load it directly from the Hugging Face library:

console
pip install datasets
py
from datasets import load_dataset

dataset = load_dataset('angeluriot/chess_games')

for game in dataset['train']:
    print(game['moves_san'])
    break

<br/>

๐Ÿ“‘ Example

json
{
    "date": "2024.08.05",
    "white_elo": "2012",
    "black_elo": "1846",
    "end_type": "checkmate",
    "winner": "black",
    "moves_san": [
        "a3", "d5", "Nf3", "Nf6", "g3", "g6", "Bg2", "Bg7", "O-O", "O-O", "d3", "Nbd7", "Nbd2", "e5", "e4", "dxe4", "dxe4", "Re8", "Qe2", "Qe7", "b3", "Nc5", "Bb2", "Nfd7", "Rfd1", "Nf8", "Nc4", "f6", "Nfd2", "Be6", "Ne3", "c6", "a4", "Bf7", "Ndc4", "Red8", "b4", "Rxd1+", "Qxd1", "Rd8", "Qe2", "Nce6", "c3", "Nd7", "Ba3", "Nb6", "Nb2", "Qc7", "a5", "Nc8", "Nbc4", "Bf8", "Bc1", "h5", "h4", "Nd6", "Nb2", "Nb5", "Bd2", "Kh7", "Be1", "Bh6", "Nbc4", "Bf8", "Bf1", "Be7", "Qc2", "Kg7", "Nb2", "Nd6", "Rd1", "Bf8", "Nbc4", "Nb5", "Ra1", "Be7", "Na3", "Nd6", "Qb1", "Bf8", "Nec4", "Nxc4", "Nxc4", "Qd7", "a6", "b6", "Bh3", "Qe8", "Ne3", "Kh7", "Bf1", "Bh6", "Nc4", "Nc7", "Qc2", "Qd7", "Nb2", "Ne6", "Bc4", "Qe8", "Rd1", "Kg8", "Rxd8", "Qxd8", "b5", "cxb5", "Bxb5", "Nc5", "Qe2", "Kh7", "f3", "Qc8", "Bf2", "Bf8", "Kg2", "Be6", "Be3", "Be7", "Kf2", "Kg7", "Kg2", "Bh3+", "Kh2", "Be6", "Nd1", "Bf7", "Nf2", "Be6", "Nd1", "Bf7", "Bf2", "Nb3", "Qd3", "Bc5", "Be1", "Qc7", "Ne3", "Bxe3", "Qxe3", "Qc5", "Qxc5", "Nxc5", "Bf2", "Ne6", "c4", "Nc7", "Be3", "Be6", "Kg2", "Kf7", "Kf2", "Ke7", "Ke1", "Bc8", "Ba4", "Bxa6", "c5", "b5", "Bb3", "Bc8", "c6", "a6", "Bc5+", "Ke8", "Bb6", "Be6", "Bxc7", "Bxb3", "Kd2", "Ke7", "f4", "exf4", "gxf4", "Be6", "Kc3", "Bh3", "e5", "Bg2", "Bd6+", "Ke6", "c7", "Bb7", "Kb4", "fxe5", "fxe5", "Bc8", "Ka5", "Kd5", "Kb6", "b4", "Bxb4", "Kxe5", "Ka7", "g5", "hxg5", "h4", "Kb8", "Be6", "c8=Q", "Bxc8", "Kxc8", "h3", "Kc7", "Kf5", "Bd6", "a5", "g6", "Kxg6", "Kb6", "a4", "Kb5", "a3", "Bxa3", "h2", "Bc5", "h1=Q", "Kb6", "Qd5", "Kb5", "Kf5", "Kb6", "Ke6", "Kb5", "Qb3+", "Kc6", "Qc4", "Kb6", "Kd7", "Bf2", "Qb3+", "Ka7", "Qa2+", "Kb8", "Kc6", "Ba7", "Qg8#"
    ],
    "moves_uci": [
        "a2a3", "d7d5", "g1f3", "g8f6", "g2g3", "g7g6", "f1g2", "f8g7", "e1g1", "e8g8", "d2d3", "b8d7", "b1d2", "e7e5", "e2e4", "d5e4", "d3e4", "f8e8", "d1e2", "d8e7", "b2b3", "d7c5", "c1b2", "f6d7", "f1d1", "d7f8", "d2c4", "f7f6", "f3d2", "c8e6", "c4e3", "c7c6", "a3a4", "e6f7", "d2c4", "e8d8", "b3b4", "d8d1", "e2d1", "a8d8", "d1e2", "c5e6", "c2c3", "f8d7", "b2a3", "d7b6", "c4b2", "e7c7", "a4a5", "b6c8", "b2c4", "g7f8", "a3c1", "h7h5", "h2h4", "c8d6", "c4b2", "d6b5", "c1d2", "g8h7", "d2e1", "f8h6", "b2c4", "h6f8", "g2f1", "f8e7", "e2c2", "h7g7", "c4b2", "b5d6", "a1d1", "e7f8", "b2c4", "d6b5", "d1a1", "f8e7", "c4a3", "b5d6", "c2b1", "e7f8", "e3c4", "d6c4", "a3c4", "c7d7", "a5a6", "b7b6", "f1h3", "d7e8", "c4e3", "g7h7", "h3f1", "f8h6", "e3c4", "e6c7", "b1c2", "e8d7", "c4b2", "c7e6", "f1c4", "d7e8", "a1d1", "h7g8", "d1d8", "e8d8", "b4b5", "c6b5", "c4b5", "e6c5", "c2e2", "g8h7", "f2f3", "d8c8", "e1f2", "h6f8", "g1g2", "f7e6", "f2e3", "f8e7", "g2f2", "h7g7", "f2g2", "e6h3", "g2h2", "h3e6", "b2d1", "e6f7", "d1f2", "f7e6", "f2d1", "e6f7", "e3f2", "c5b3", "e2d3", "e7c5", "f2e1", "c8c7", "d1e3", "c5e3", "d3e3", "c7c5", "e3c5", "b3c5", "e1f2", "c5e6", "c3c4", "e6c7", "f2e3", "f7e6", "h2g2", "g7f7", "g2f2", "f7e7", "f2e1", "e6c8", "b5a4", "c8a6", "c4c5", "b6b5", "a4b3", "a6c8", "c5c6", "a7a6", "e3c5", "e7e8", "c5b6", "c8e6", "b6c7", "e6b3", "e1d2", "e8e7", "f3f4", "e5f4", "g3f4", "b3e6", "d2c3", "e6h3", "e4e5", "h3g2", "c7d6", "e7e6", "c6c7", "g2b7", "c3b4", "f6e5", "f4e5", "b7c8", "b4a5", "e6d5", "a5b6", "b5b4", "d6b4", "d5e5", "b6a7", "g6g5", "h4g5", "h5h4", "a7b8", "c8e6", "c7c8q", "e6c8", "b8c8", "h4h3", "c8c7", "e5f5", "b4d6", "a6a5", "g5g6", "f5g6", "c7b6", "a5a4", "b6b5", "a4a3", "d6a3", "h3h2", "a3c5", "h2h1q", "b5b6", "h1d5", "b6b5", "g6f5", "b5b6", "f5e6", "b6b5", "d5b3", "b5c6", "b3c4", "c6b6", "e6d7", "c5f2", "c4b3", "b6a7", "b3a2", "a7b8", "d7c6", "f2a7", "a2g8"
    ],
    "moves_custom": [
        "w.โ™™a2โ™™a3..", "b.โ™Ÿd7โ™Ÿd5..", "w.โ™˜g1โ™˜f3..", "b.โ™žg8โ™žf6..", "w.โ™™g2โ™™g3..", "b.โ™Ÿg7โ™Ÿg6..", "w.โ™—f1โ™—g2..", "b.โ™f8โ™g7..", "w.โ™”e1โ™”g1โ™–h1โ™–f1..", "b.โ™še8โ™šg8โ™œh8โ™œf8..", "w.โ™™d2โ™™d3..", "b.โ™žb8โ™žd7..", "w.โ™˜b1โ™˜d2..", "b.โ™Ÿe7โ™Ÿe5..", "w.โ™™e2โ™™e4..", "b.โ™Ÿd5โ™Ÿe4.x.", "w.โ™™d3โ™™e4.x.", "b.โ™œf8โ™œe8..", "w.โ™•d1โ™•e2..", "b.โ™›d8โ™›e7..", "w.โ™™b2โ™™b3..", "b.โ™žd7โ™žc5..", "w.โ™—c1โ™—b2..", "b.โ™žf6โ™žd7..", "w.โ™–f1โ™–d1..", "b.โ™žd7โ™žf8..", "w.โ™˜d2โ™˜c4..", "b.โ™Ÿf7โ™Ÿf6..", "w.โ™˜f3โ™˜d2..", "b.โ™c8โ™e6..", "w.โ™˜c4โ™˜e3..", "b.โ™Ÿc7โ™Ÿc6..", "w.โ™™a3โ™™a4..", "b.โ™e6โ™f7..", "w.โ™˜d2โ™˜c4..", "b.โ™œe8โ™œd8..", "w.โ™™b3โ™™b4..", "b.โ™œd8โ™œd1.x.+", "w.โ™•e2โ™•d1.x.", "b.โ™œa8โ™œd8..", "w.โ™•d1โ™•e2..", "b.โ™žc5โ™že6..", "w.โ™™c2โ™™c3..", "b.โ™žf8โ™žd7..", "w.โ™—b2โ™—a3..", "b.โ™žd7โ™žb6..", "w.โ™˜c4โ™˜b2..", "b.โ™›e7โ™›c7..", "w.โ™™a4โ™™a5..", "b.โ™žb6โ™žc8..", "w.โ™˜b2โ™˜c4..", "b.โ™g7โ™f8..", "w.โ™—a3โ™—c1..", "b.โ™Ÿh7โ™Ÿh5..", "w.โ™™h2โ™™h4..", "b.โ™žc8โ™žd6..", "w.โ™˜c4โ™˜b2..", "b.โ™žd6โ™žb5..", "w.โ™—c1โ™—d2..", "b.โ™šg8โ™šh7..", "w.โ™—d2โ™—e1..", "b.โ™f8โ™h6..", "w.โ™˜b2โ™˜c4..", "b.โ™h6โ™f8..", "w.โ™—g2โ™—f1..", "b.โ™f8โ™e7..", "w.โ™•e2โ™•c2..", "b.โ™šh7โ™šg7..", "w.โ™˜c4โ™˜b2..", "b.โ™žb5โ™žd6..", "w.โ™–a1โ™–d1..", "b.โ™e7โ™f8..", "w.โ™˜b2โ™˜c4..", "b.โ™žd6โ™žb5..", "w.โ™–d1โ™–a1..", "b.โ™f8โ™e7..", "w.โ™˜c4โ™˜a3..", "b.โ™žb5โ™žd6..", "w.โ™•c2โ™•b1..", "b.โ™e7โ™f8..", "w.โ™˜e3โ™˜c4..", "b.โ™žd6โ™žc4.x.", "w.โ™˜a3โ™˜c4.x.", "b.โ™›c7โ™›d7..", "w.โ™™a5โ™™a6..", "b.โ™Ÿb7โ™Ÿb6..", "w.โ™—f1โ™—h3..", "b.โ™›d7โ™›e8..", "w.โ™˜c4โ™˜e3..", "b.โ™šg7โ™šh7..", "w.โ™—h3โ™—f1..", "b.โ™f8โ™h6..", "w.โ™˜e3โ™˜c4..", "b.โ™že6โ™žc7..", "w.โ™•b1โ™•c2..", "b.โ™›e8โ™›d7..", "w.โ™˜c4โ™˜b2..", "b.โ™žc7โ™že6..", "w.โ™—f1โ™—c4..", "b.โ™›d7โ™›e8..", "w.โ™–a1โ™–d1..", "b.โ™šh7โ™šg8..", "w.โ™–d1โ™–d8.x.", "b.โ™›e8โ™›d8.x.", "w.โ™™b4โ™™b5..", "b.โ™Ÿc6โ™Ÿb5.x.", "w.โ™—c4โ™—b5.x.", "b.โ™že6โ™žc5..", "w.โ™•c2โ™•e2..", "b.โ™šg8โ™šh7..", "w.โ™™f2โ™™f3..", "b.โ™›d8โ™›c8..", "w.โ™—e1โ™—f2..", "b.โ™h6โ™f8..", "w.โ™”g1โ™”g2..", "b.โ™f7โ™e6..", "w.โ™—f2โ™—e3..", "b.โ™f8โ™e7..", "w.โ™”g2โ™”f2..", "b.โ™šh7โ™šg7..", "w.โ™”f2โ™”g2..", "b.โ™e6โ™h3..+", "w.โ™”g2โ™”h2..", "b.โ™h3โ™e6..", "w.โ™˜b2โ™˜d1..", "b.โ™e6โ™f7..", "w.โ™˜d1โ™˜f2..", "b.โ™f7โ™e6..", "w.โ™˜f2โ™˜d1..", "b.โ™e6โ™f7..", "w.โ™—e3โ™—f2..", "b.โ™žc5โ™žb3..", "w.โ™•e2โ™•d3..", "b.โ™e7โ™c5..", "w.โ™—f2โ™—e1..", "b.โ™›c8โ™›c7..", "w.โ™˜d1โ™˜e3..", "b.โ™c5โ™e3.x.", "w.โ™•d3โ™•e3.x.", "b.โ™›c7โ™›c5..", "w.โ™•e3โ™•c5.x.", "b.โ™žb3โ™žc5.x.", "w.โ™—e1โ™—f2..", "b.โ™žc5โ™že6..", "w.โ™™c3โ™™c4..", "b.โ™že6โ™žc7..", "w.โ™—f2โ™—e3..", "b.โ™f7โ™e6..", "w.โ™”h2โ™”g2..", "b.โ™šg7โ™šf7..", "w.โ™”g2โ™”f2..", "b.โ™šf7โ™še7..", "w.โ™”f2โ™”e1..", "b.โ™e6โ™c8..", "w.โ™—b5โ™—a4..", "b.โ™c8โ™a6.x.", "w.โ™™c4โ™™c5..", "b.โ™Ÿb6โ™Ÿb5..", "w.โ™—a4โ™—b3..", "b.โ™a6โ™c8..", "w.โ™™c5โ™™c6..", "b.โ™Ÿa7โ™Ÿa6..", "w.โ™—e3โ™—c5..+", "b.โ™še7โ™še8..", "w.โ™—c5โ™—b6..", "b.โ™c8โ™e6..", "w.โ™—b6โ™—c7.x.", "b.โ™e6โ™b3.x.", "w.โ™”e1โ™”d2..", "b.โ™še8โ™še7..", "w.โ™™f3โ™™f4..", "b.โ™Ÿe5โ™Ÿf4.x.", "w.โ™™g3โ™™f4.x.", "b.โ™b3โ™e6..", "w.โ™”d2โ™”c3..", "b.โ™e6โ™h3..", "w.โ™™e4โ™™e5..", "b.โ™h3โ™g2..", "w.โ™—c7โ™—d6..+", "b.โ™še7โ™še6..", "w.โ™™c6โ™™c7..", "b.โ™g2โ™b7..", "w.โ™”c3โ™”b4..", "b.โ™Ÿf6โ™Ÿe5.x.", "w.โ™™f4โ™™e5.x.", "b.โ™b7โ™c8..", "w.โ™”b4โ™”a5..", "b.โ™še6โ™šd5..", "w.โ™”a5โ™”b6..", "b.โ™Ÿb5โ™Ÿb4..", "w.โ™—d6โ™—b4.x.", "b.โ™šd5โ™še5.x.", "w.โ™”b6โ™”a7..", "b.โ™Ÿg6โ™Ÿg5..", "w.โ™™h4โ™™g5.x.", "b.โ™Ÿh5โ™Ÿh4..", "w.โ™”a7โ™”b8..", "b.โ™c8โ™e6..", "w.โ™™c7โ™•c8..", "b.โ™e6โ™c8.x.", "w.โ™”b8โ™”c8.x.", "b.โ™Ÿh4โ™Ÿh3..", "w.โ™”c8โ™”c7..", "b.โ™še5โ™šf5..", "w.โ™—b4โ™—d6..", "b.โ™Ÿa6โ™Ÿa5..", "w.โ™™g5โ™™g6..", "b.โ™šf5โ™šg6.x.", "w.โ™”c7โ™”b6..", "b.โ™Ÿa5โ™Ÿa4..", "w.โ™”b6โ™”b5..", "b.โ™Ÿa4โ™Ÿa3..", "w.โ™—d6โ™—a3.x.", "b.โ™Ÿh3โ™Ÿh2..", "w.โ™—a3โ™—c5..", "b.โ™Ÿh2โ™›h1..", "w.โ™”b5โ™”b6..", "b.โ™›h1โ™›d5..", "w.โ™”b6โ™”b5..", "b.โ™šg6โ™šf5..", "w.โ™”b5โ™”b6..", "b.โ™šf5โ™še6..", "w.โ™”b6โ™”b5..", "b.โ™›d5โ™›b3..+", "w.โ™”b5โ™”c6..", "b.โ™›b3โ™›c4..", "w.โ™”c6โ™”b6..", "b.โ™še6โ™šd7..", "w.โ™—c5โ™—f2..", "b.โ™›c4โ™›b3..+", "w.โ™”b6โ™”a7..", "b.โ™›b3โ™›a2..+", "w.โ™”a7โ™”b8..", "b.โ™šd7โ™šc6..", "w.โ™—f2โ™—a7..", "b.โ™›a2โ™›g8..+#"
    ],
    "source": "LichessBroadcast"
}

<br/>

๐Ÿ™ Credits

  • โ€”**Angel Uriot**: the creator of the project
  • โ€”**Lumbras Giga Base**: for collecting the games of the dataset
  • โ€”All the original sources of the games, see the **Sources** section for more information
  • โ€”All the players featured in the games of the dataset