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.
โ๏ธ 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:
{
"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:
- The color of the player (
wfor white andbfor black)
- The state of the moved pieces before and after the move:
- For example, a white knight moving from e2 to g3 would be represented as:
โe2โg3 - If a piece change during the move, like a white pawn becoming a white queen, it would be represented as:
โe7โe8 - If multiple pieces are moved, like in a white kingside castling, it would be represented as:
โe1โg1โh1โf1
xif a piece is captured during the move andx*if the capture is en passant
+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"><0.01 %</td> </tr> <tr> <td align="left"><b>Games Of GMs</b></td> <td align="center">62</td> <td align="center"><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:
pip install datasetsfrom datasets import load_dataset
dataset = load_dataset('angeluriot/chess_games')
for game in dataset['train']:
print(game['moves_san'])
break<br/>
๐ Example
{
"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
