Getting Started
Need a very quick introduction to Glass Onion? Here's an example of identifier synchronization across two public datasets for the 2023-2024 1. Bundesliga season: Statsbomb and Impect. If you're already familiar with how Glass Onion works, feel free to move on to the integration guide, where you can learn how to make Glass Onion part of a production workflow.
Installing Glass Onion
The easiest way to install Glass Onion is via uv or pip.
The installation guide has more options if you need them.
Example: Player Synchronization
Loading data
First, let's use kloppy to retrieve sample data for a given match from both Impect and Statsbomb. For simplicity, we've picked out the August 19, 2023 fixture between Bayer Leverkusen and RB Leipzig from both datasets.
We can pull out the player information from both of these event datasets into Pandas dataframes. For each, we'll have to iterate through the teams and pull specific fields for each of the players.
Assigning unified team identifiers
We need to unify team identifiers across these two dataframes so Glass Onion can properly use team_id in its synchronization logic. With just two teams, we can do this manually (as below) by simply setting RB Leipzig's team_id to RBL and Bayer Leverkusen's to B04. If we wanted to do this across the entire competition, we could build a more complex workflow with Glass Onion.
Wrapping in PlayerSyncableContent
Now, we just have to wrap these two dataframes in PlayerSyncableContent instances so they can be used in PlayerSyncEngine.
Using PlayerSyncEngine
Once you have two PlayerSyncableContent instances, you can now synchronize them with PlayerSyncEngine.synchronize!
result is a PlayerSyncableContent object, so you can view the dataframe containing synchronized identifiers by dumping out its data field:
| jersey_number | team_id | player_name | impect_player_id | statsbomb_player_id | provider |
|---|---|---|---|---|---|
| 1 | B04 | Lukas Hradecky | 1030 | 8667 | impect |
| 10 | B04 | Florian Wirtz | 64023 | 40724 | impect |
| 10 | RBL | Emil Forsberg | 355 | 5625 | impect |
| 11 | B04 | Nadiem Amiri | 1286 | 8403 | impect |
| 11 | RBL | Timo Werner | 1017 | 5557 | impect |
result.data to link the Impect and Statsbomb datasets together.
Future: Using the synced identifiers
Let's say you want to compare a player's Statsbomb Shot xG to their Impect Packing xG. We'll need to parse out both KPIs from their JSON files:
| impect_match_id | impect_player_id | impect_packing_xg |
|---|---|---|
| 122839 | 355 | 0.01708 |
| 122839 | 1017 | 0.13579 |
| 122839 | 1132 | 0.48393 |
| 122839 | 1174 | 0.00439 |
| 122839 | 1235 | 0.00155 |
| statsbomb_match_id | statsbomb_player_id | statsbomb_shot_xg |
|---|---|---|
| 3895052 | 10336 | 0.127063 |
| 3895052 | 16275 | 1.084519 |
| 3895052 | 16532 | 0.092469 |
| 3895052 | 196651 | 0.024261 |
| 3895052 | 32289 | 0.213704 |
But once we have both datasets, we can join them easily:
| player_name | team_id | jersey_number | impect_player_id | statsbomb_player_id | impect_packing_xg | statsbomb_shot_xg |
|---|---|---|---|---|---|---|
| Loïs Openda | RBL | 17 | 2735 | 16275 | 1.25466 | 1.084519 |
| Yussuf Poulsen | RBL | 9 | 1132 | 5536 | 0.48393 | 0.314084 |
| Timo Werner | RBL | 11 | 1017 | 5557 | 0.13579 | 0.042124 |
| Dani Olmo | RBL | 7 | 5658 | 16532 | 0.11369 | 0.092469 |
| Benjamin Henrichs | RBL | 39 | 1303 | 8211 | 0.08574 | 0.167162 |