SkillCorner Open Data

The src/ directory provides reusable Python modules for loading, processing, and visualizing SkillCorner data. It is organized into three main functional areas:

• data/: Handles data ingestion and loading (e.g., basic_loading.py for match metadata and tracking data).
• features/: Contains logic for feature engineering and data aggregation (e.g., DynamicEventsAggregator.py and PhasesOfPlayAggregator.py).
• visualization/: Provides reusable plotting and reporting functions (e.g., head2head_viz.py for player/team comparisons and sectioned_summary_table_viz.py for metric organization).

For practical implementation examples, refer to the Learning Paths in the Tutorials section.

The repository is organized into several key directories for accessing different types of football data:

• data/matches.json: Contains basic match information. Use this to find the id of a specific match.
• data/matches/{id}/: A folder for each match containing:
  • {id}_match.json: Lineup information, time played, referee, pitch size, etc.
  • {id}_tracking_extrapolated.jsonl: Tracking data for players and the ball.
  • {id}_dynamic_events.csv: Game Intelligence dynamic events.
  • {id}_phases_of_play.csv: Game Intelligence Phases of Play framework.
• data/aggregates/: CSV files containing season-level aggregated data (Physical, Off-Ball Runs, and Passing) for the AUS 1 League 2024/2025.

The repository includes two specialized CSV data layers derived from Game Intelligence:

Dynamic Event Data ({id}_dynamic_events.csv)

• Each row corresponds to a unique event_id (unique only within a single game).
• Events are categorized into 4 subcategories.
• Warning: The x/y attributes for events are not scaled to standard pitch size and require manual adjustment to match your coordinate system.

Phases of Play Data ({id}_phases_of_play.csv)

• Each row represents the start and end frames of a specific phase.
• Captures the concurrent attacking and defending phases.
• Phases are only defined when the ball is in play; no phase is recorded when the ball is out of play.
• Every in-possession phase has a corresponding out-of-possession phase.

Season-level aggregates are provided at the player-season level and include metrics across three categories:

1. Physical: Includes metrics like PSV99, high-intensity counts, and distance covered.
2. Off-Ball Runs (OBR): Tactical metrics identifying types of runs and their outcomes.
3. Passing: Aggregated passing volume and efficiency metrics.

Note: These datasets are filtered to include only performances where the player played more than 60 minutes.

To account for league intensity and 'dead time', you can normalize metrics per 60 minutes of Ball In Play (BIP) time.

BIP is the sum of TIP (Team In Possession) and OTIP (Opponent Team In Possession) minutes.

Formula: (metric_tip + metric_otip) * 60 / (minutes_tip + minutes_otip)

# Example from Tutorial Part 2
physical_df['hi_count_p60_bip'] = (
    (physical_df['hi_count_full_tip'] + physical_df['hi_count_full_otip']) * 60 /
    (physical_df['minutes_full_tip'] + physical_df['minutes_full_otip'])
)

Phases of play data can be loaded either from the SkillCorner API using the client or from local CSV files if using the open-source data distribution.

When using the API, use client.get_dynamic_events(MATCH_ID) to retrieve the data as a byte stream, which can then be read by pandas.read_csv via BytesIO.

import pandas as pd
from io import BytesIO

# Option 1: Load from SkillCorner API
# events_df = pd.read_csv(BytesIO(client.get_dynamic_events(MATCH_ID)))

# Option 2: Load from local Open Source CSV
match_id = 1886347
phases_df = pd.read_csv(f"../../../data/matches/{match_id}/{match_id}_phases_of_play.csv")

Tutorials are located in the notebooks/tutorials folder and are organized into four progressive paths:

• Path 01: Getting Started with SkillCorner Data: Foundational performance data and basic normalization.
• Path 02: Working with Game Intelligence & Dynamic Events: Contextual data layers (Dynamic Events, Phases of Play, Off-ball Runs, etc.).
• Path 03: Basics of Tracking: Working with raw X/Y coordinates and spatial data formats.
• Path 04: Visualization Bank: Advanced visualizations.

Online versions of the Tracking and Visualization notebooks are also available via Google Colab.

To ensure statistical significance and minimize tactical noise when analyzing player performance, apply the following thresholds:

• Minimum Games: Filter for players with at least 5 games played.
• Minimum Minutes: Focus on performances of 60+ minutes to decouple a player's true capability from tactical shifts or short energy bursts typical of substitute appearances.

# filtering in the aggregate file
reliable_players = physical_df[physical_df['count_match'] >= 5]

To compare players fairly despite varying minutes played, normalize cumulative metrics to a Per 90 (P90) basis.

Match Level

For a single match, use the formula: (metric * 90) / time_played.

Aggregate Level (Season/Career)

When calculating season or career averages, do not average individual P90 values. Instead, use the ratio of the average metric to the average minutes played to prevent skewing from short substitute appearances.

Formula: (AVG(metric) * 90) / AVG(time_played)

# Formula: (metric * 90) / time_played
physical_df['hi_count_p90'] = (physical_df['hi_count_full_all'] / physical_df['minutes_full_all']) * 90