pgn2data

This library converts chess pgn files into CSV tabulated data sets.

A pgn file can contain one or multiple chess games. The library parses the pgn file and creates two csv files:

• Games file: contains high level information (e.g. date, site, event, score, players etc...)

• Moves file: contains the moves for each game (e.g. notation, squares, fen position, is in check etc...)

The two files can be mapped together using a GUID which the process inserts into both files.

Installation

The library requires Python 3.10 or later.

To install, type the following command on the python terminal:

pip install pgn2data

Implementation

Here is a basic example of how to convert a PGN file:

from converter.pgn_data import PGNData

pgn_data = PGNData("tal_bronstein_1982.pgn")
pgn_data.export()

The following is an example of grouping multiple files into the same output file ("output.csv").

pgn_data = PGNData(["file1.pgn","file2.pgn"],"output")
pgn_data.export()

The export function has a return object which allows you to quickly check the size and location of the files created:

pgn_data = PGNData("tal_bronstein_1982.pgn")
result = pgn_data.export()
result.print_summary()

If you want to check if the files have been created before doing further processing you can do the following:

pgn_data = PGNData("tal_bronstein_1982.pgn")
result = pgn_data.export()
if result.is_complete:
    print("Files created!")
else:
    print("Files not created!")

Pandas

The result object also provides methods to import the created files into pandas dataframes:

pgn_data = PGNData("tal_bronstein_1982.pgn")
result = pgn_data.export()
if result.is_complete:
    
    # read the games file
    games_df = result.get_games_df()
    print(games_df.head())
    
    # read the moves file
    moves_df = result.get_moves_df()
    print(moves_df.head())
    
    # read both files joined together
    combined_df = result.get_combined_df()
    print(combined_df.head())

Game information

To output the game information only, you can do the following:

from converter.pgn_data import PGNData

pgn_data = PGNData("tal_bronstein_1982.pgn")
pgn_data.export(moves_required=False)

Examples

The folder 'samples' in this repository, has some examples of the output from the library.

You can also go here to see a Kaggle project that converted all of Magnus Carlsen's online Bullet games into CSV format.

Columns

This is a full list of the columns in each output file:

Games File

Moves File

Contributions and testing

Contributions are welcome. Bug fixes and new functionality should include appropriate tests demonstrating the expected behaviour.

From the repository root, run:

from testing.tests import run_all_tests
run_all_tests()

The tests use PGN fixtures in testing/pgn and write generated files to testing/exports. Existing files in testing/exports are deleted before the tests run.

Add new checks to the relevant test class and ensure they are called by the test runner. Regression fixtures for GitHub issues belong in testing/pgn/issues, using filenames such as reported_issue_02.pgn.

Acknowledgements

This project makes use of the python-chess library.