Metadata-Version: 2.1
Name: pgn2data
Version: 0.0.5
Summary: Transforms a chess pgn file into a csv dataset containing game information and move information
Home-page: 
Author: Zaid Qureshi
Author-email: zq99@hotmail.com
License: GPL2
Keywords: CHESS,PGN,NOTATION,DATA,FORSYTH–EDWARDS NOTATION,CSV,DATASET,DATABASE,NORMALIZATION,TABULATION,STRUCTURED DATA
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Education
Classifier: Operating System :: Microsoft :: Windows :: Windows 10
Classifier: License :: OSI Approved :: GNU Lesser General Public License v2 (LGPLv2)
Classifier: Programming Language :: Python :: 3
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
License-File: LICENSE

# 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.7 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")
    result = pgn_data.export()
    result.print_summary()
    
The return value from the export function allows you to check whether the datasets have been created or not.

To group multiple files into the same output file you can do the following:

    pgn_data = PGNData(["file1.pgn","file2.pgn"],"output")
    result = pgn_data.export()
    result.print_summary()
    
The above code will process the two pgn files (file1 and file2) and export them to a file called "output.csv".


## Examples

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

You can also go [here](https://www.kaggle.com/datasets/zq1200/magnus-carlsen-lichess-games-dataset) 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

| Field                 | Description                        |
|-----------------------|------------------------------------|
| game_id               | ID of game generated by process    |
| game_order            | Order of game in PGN file          |
| event                 | Event                              |
| site                  | Site                               |
| date_played           | Date played                        |
| round                 | Round                              |
| white                 | White player                       |
| black                 | Black player                       |
| result                | Result                             |
| white_elo             | White player rating                |
| white_rating_diff     | White rating difference from Black |
| black_elo             | Black player rating                |
| black_rating_diff     | Black rating difference from White |
| white_title           | Player title                       |
| black_title           | Player title                       |
| winner                | Player name                        |
| winner_elo            | Player rating                      |
| loser                 | Losing player                      |
| loser_elo             | Player rating                      |
| winner_loser_elo_diff | Diff in rating                     |
| eco                   | Opening                            |
| termination           | How game ended                     |
| time_control          | Time control                       |
| utc_date              | Date played                        |
| utc_time              | Time played                        |
| variant               | Game type                          |
| ply_count             | Ply Count                          |
| date_created          | Extract date                       |
| file_name             | PGN source file                    |


### Moves File

| Field                          | Description                                                             |
|--------------------------------|-------------------------------------------------------------------------|
| game_id                        | ID of game that maps to games file                                      |
| move_no                        | Order of moves                                                          |
| move_no_pair                   | Chess move number                                                       |
| player                         | Player name                                                             |
| notation                       | Standard notation of move                                               |
| move                           | Before and after piece location                                         |
| from_square                    | Piece location before                                                   |
| to_square                      | Piece location after                                                    |
| piece                          | Initial of piece name                                                   |
| color                          | Piece color                                                             |
| fen                            | Fen position                                                            |
| is_check                       | Is check on board                                                       |
| is_check_mate                  | Is checkmate on board                                                   |
| is_fifty_moves                 | Is 50 move complete                                                     |
| is_fivefold_repetition         | Is 5 fold reptition on board                                            |
| is_game_over                   | Is game over                                                            |
| is_insufficient_material       | Is game over from lack of mating material                               |
| white_count                    | Count of white pieces                                                   |
| black_count                    | Count of black pieces                                                   |
| white_{piece}_count            | Count of white specifed piece                                           |
| black_{piece}_count            | Count of black specifed piece                                           |
| captured_score_for_white       | Total of black pieces captured                                          |
| captured_score_for_black       | Total of white pieces captured                                          |
| fen_row{number}_{colour)_count | Number of pieces for the specified colour on this row of the board      |
| fen_row{number}_{colour}_value | Total value of pieces for the specified colour on this row of the board |
| move_sequence                  | Sequence of moves upto current position                                 |
