Usage

To use pitchly in a project:

import pitchly

As of now , pitchly works only with Metrica Sports data format (old and new EPTS FIFA). So the recommended starting point for now is from pitchly.metrica import ...

Data Loading

kloppy is used to load the tracking and event data from Metrica. Click here for the sample open data

import glob
import kloppy

# match directory
match_dir = "/match/folder/with/metrica/data/"

# tracking data [METRICA]
metadata_file = glob.glob(f"{match_dir}/*metadata*")[0]  # xml file
tracking_file = glob.glob(f"{match_dir}/*tracking*")[0]  # txt file

dataset = kloppy.load_epts_tracking_data(raw_data_filename=tracking_file, metadata_filename=metadata_file, options=None)

metadata = dataset.metadata
tracking_dataset = kloppy.to_pandas(dataset)

# event data [METRICA]
events_file = glob.glob(f"{match_dir}/*events*")[0]  # txt file

event_dataset = kloppy.load_metrica_json_event_data(
    raw_data_filename=events_file, metadata_filename=metadata_file, options=None
)

Basic Football Pitch

pitchly can be used to plot a basic football pitch (currently Metrica data dimensions) and building further on it as needed.

from pitchly.pitch import Pitch

pitch = Pitch()
fig = pitch.plot_pitch()

This is however not needed for any further plots as demonstrated below.

Tracking Data

# import the pitchly wrapper for metrica tracking data
from pitchly.metrica import TrackingData

# feed the loaded data
data = TrackingData(tracking_dataset,metadata)

Plot Frame by FrameID

data.plot_frame(frameID=3264)

Plot Frame by Time

data.plot_frame(time='17:20')

Plot Sequence by FrameIDs

You can plot a sequence of frames with a slider to animate/track an event.

data.plot_sequence(f0=15850,f1=15950)

Plot Sequence by Time

Or use the start time and end time for an interval sequence.

data.plot_sequence(t0='72',t1='72:06')

Pitch Control

The pitch control is calculated by adapting Laurie Shaw’s work on William Spearman’s model. Since generating pitch control visualization on the fly gets sluggish, it is recommended to proceed with slight patience using the sliders (the pitch control overlay reloads with a tiny delay for every frame). The example shown here is for a very small time range (5 seconds / 125 frames) and generating the viz takes 7 minutes.

data.plot_sequence(t0='72',t1='72:05', pitch_control = True)

Generating pitch control overlay for individual frame/time inputs is fairly faster.

data.plot_frame(time='17:20', pitch_control = True)

Event Data

# import the pitchly wrapper for metrica event data
from pitchly.metrica import EventData

# feed the loaded data
data = EventData(event_dataset.events)

You can now plot various events cumulatively from the match by calling for type

Shots

data.plot(type="shots")

You can set trace=True to see the trace of the shots

Goals

data.plot(type="goals")

You can set trace=True to see the trace of the goals

Corners

data.plot(type="corners")

Freekicks

data.plot(type="freekicks")

You can set trace=True to see the trace of the freekicks

Challenges

data.plot(type="challenges")

Challenges do not have trace option

Recoveries

data.plot(type="recoveries")

Recoveries do not have trace option

Shot Assists

data.plot(type="shot_assists")

You can set trace=True to see the trace of the shot assists

Assists

data.plot(type="assists")

You can set trace=True to see the trace of the assists

Passes

data.plot(type="passes")

Passers

data.plot(type="passers")

Receivers

data.plot(type="receivers")

Plot Event by Index

You can plot a specific event with its chain as follows:

data.plot(index=3478)

In order to know the index, you can browse the subset of choice using a kloppy helper:

kloppy.to_pandas(data.get_shots(),
                 additional_columns={'index_to_plot': lambda row: row.raw_event['index']}).set_index('index_to_plot')

Old Metrica Format (csv)

The older samples of Metrica data follow the .csv format and they can be loaded and used with pitchly in the following way:

import glob
from pitchly.utils import load_data
from pitchly.metrica_old import TrackingData,EventData

# match directory
match_dir = "/match/folder/with/metrica/data/"

# load the data
tracking_home, tracking_away, events = load_data(match_dir)

# tracking
data = TrackingData(tracking_home, tracking_away)
data.plot_sequence(...)

# events
data = data = EventData(events)
data.plot(type="shots", trace=True)