Full example of formation identification

[Regista6]

https://arxiv.org/pdf/2506.23843

Hello,

I was wondering if you have an end-to-end example or script available that reproduces the output images shown in the paper (e.g., the one below).

A working code sample that takes inputs and generates these results would be incredibly helpful for better understanding and replicating the method.

Thank you!

[UnravelSports]

@Regista6 I was about to leave for the rest of the day, but want to help you further. So I quickly pulled some stuff together. Unfortunately, it's not all totally working, but I think you should be able to figure it out.

from unravel.soccer import KloppyPolarsDataset, EFPI

from kloppy import sportec

kloppy_dataset = sportec.load_open_tracking_data()
kloppy_polars_dataset = KloppyPolarsDataset(
    kloppy_dataset=kloppy_dataset
)

model = EFPI(dataset=kloppy_polars_dataset)
model.fit(
    # Default 65 formations , or specify a subset (e.g. ["442" , "433"])
    formations=None,
    # specific time intervals (e.g. 1m, 1m14s, 2m30s etc.), or specify "possession", "period" or "frame".
    every="5m",
    substitutions="drop",
    change_threshold=0.1,
    change_after_possession=True,
)

Now, once the model is fit you can access the data in model.output this is a Polars dataframe.

The code I can find for a similar plot is:

import polars as pl
import matplotlib.pyplot as plt
import numpy as np

segment_id = f"{every}_id"
team_id = "365"
# Convert to pandas
df = (
    positions.unique([segment_id, "team_id", "formation", "period_id"])
    .sort([segment_id])
    .filter(pl.col("team_id") == team_id)
)
if every in ["frame", "possession"]:
    df = df.with_columns(
        [
            # Convert timedelta to total minutes for plotting
            (pl.col("segment_start_timestamp").dt.total_seconds() / 60).alias(
                "segment_minutes"
            )
        ]
    )
else:
    df = df.with_columns(
        [
            # Convert timedelta to total minutes for plotting
            (pl.col(segment_id).dt.total_seconds() / 60).alias("segment_minutes")
        ]
    )

df_pandas = df.to_pandas()

# Get unique formations and sort them alphabetically
formation_order = sorted(df_pandas["formation"].unique())

# Create a mapping from formation to numeric position
formation_to_position = {formation: i for i, formation in enumerate(formation_order)}

# Add position column to dataframe
df_pandas["formation_position"] = df_pandas["formation"].map(formation_to_position)

# Rest of your plotting code stays the same...

# Get unique periods and sort them
periods = sorted(df_pandas["period_id"].unique())

# Create subplots side by side
fig, axes = plt.subplots(1, len(periods), figsize=(6 * len(periods), 7), sharey=True)

# If only one period, make axes a list for consistency
if len(periods) == 1:
    axes = [axes]

for i, period in enumerate(periods):
    ax = axes[i]

    # Filter data for current period
    period_data = df_pandas[df_pandas["period_id"] == period]

    # Plot attacking and non-attacking points separately for different colors
    attacking = period_data[period_data["is_attacking"] == True]
    not_attacking = period_data[period_data["is_attacking"] == False]

    # Use formation_position for y-axis instead of formation string
    ax.scatter(
        attacking["segment_minutes"],
        attacking["formation_position"],
        c="#B71222",
        label="Attacking",
        alpha=1,
        zorder=3,
    )
    ax.scatter(
        not_attacking["segment_minutes"],
        not_attacking["formation_position"],
        c="#212844",
        label="Defending",
        alpha=1,
        zorder=3,
    )

    # Customize each subplot
    ax.grid(True)
    ax.set_title(f"Period {period}")

    # Set x-axis ticks every 10 minutes
    x_min = period_data["segment_minutes"].min()
    x_max = period_data["segment_minutes"].max()

    # Create ticks every 10 minutes
    x_ticks = np.arange(0, x_max + 5, 5)
    ax.set_xticks(x_ticks)
    ax.set_xticklabels([f"{int(tick)}'" for tick in x_ticks])

    # Set y-axis to use the ordered formations
    ax.set_yticks(range(len(formation_order)))
    ax.set_yticklabels(formation_order)

    if i == 0:  # Only set ylabel for the first subplot
        # ax.set_ylabel('Formation')
        ax.legend(loc="upper left")

# Adjust layout to prevent overlap
plt.tight_layout()

# Save the figure
plt.savefig(
    f"{team_id}-{how}-{every}-{change_threshold}.png", dpi=300, bbox_inches="tight"
)

Here positions is most likely very similar to model.output.

I hope this helps! If you are able to pull it all together, please share it here so others can be helped too!

For this specific example (since we're using Sportec open data and not PFF open data) the "365" team id is incorrect. You can find the correct team ids in the model.output dataframe or in the kloppy meta data

Note: We're sorting the formations alphabetically, not sure if that's what you prefer, might need to change that.