gandula

gandula is a Python library developed by the Sports Analytics Lab at the Federal University of Minas Gerais (UFMG) for working with Gradient football tracking and event data.

Gandula is the word for ball boy in Brazilian Portuguese. It originates from the 1930s, from the word "gandulo", that in archaic Portuguese means slacker/beggar. Back in the 30s, the word started to be used to refer to vagabond boys who did nothing else but watch football in the pitches in Rio. These "gandulas" would help by bringing the kicked-out balls. In 1939, Clube de Regatas Vasco da Gama hired the Argentinian striker Bernardo Gandulla, who was known to bring back the ball as fair play. The gandula then got popularized over the country. In our gandula, the ball is the data, and the data scientists/analysts are the stars of the game.

Data Sources

gandula supports two data sources:

• S3 tracking data — Stream or download tracking frames (player/ball positions at 30fps) directly from Gradient's S3 bucket. Requires AWS credentials (PFF_AWS_ACCESS_KEY_ID / PFF_AWS_SECRET_ACCESS_KEY). Each match includes tracking data (.jsonl.bz2), metadata (metadata.json), and rosters (rosters.json).

• Local event data (Gradient v2.6) — Load match events from local JSON files in the Gradient v2.6 format ({game_id}.json). Each file contains possession events with embedded tracking snapshots, video URLs, grades, and more.

Quick Start

Installation (development)

git clone git@github.com:SALabUFMG/gandula.git
cd gandula

Set up the environment with uv:

uv sync

For S3 access:

uv sync --extra s3

For pitch control (requires PyTorch):

uv sync --extra pitch-control

Setup

Create a .env file in the project root with your AWS credentials:

PFF_AWS_ACCESS_KEY_ID='your_access_key'
PFF_AWS_SECRET_ACCESS_KEY='your_secret_key'

Then load them in your shell before running code:

export $(cat .env | xargs)

Or load them in Python:

import os
os.environ['PFF_AWS_ACCESS_KEY_ID'] = 'your_access_key'
os.environ['PFF_AWS_SECRET_ACCESS_KEY'] = 'your_secret_key'

All gandula S3 functions will pick up the credentials automatically.

Usage

The best way to get started is the walkthrough notebook, which covers every major feature end-to-end:

1. Loading event data from Gradient v2.6 JSON files
2. Exploring and filtering events by type
3. Converting events to DataFrames
4. Loading tracking data from S3 (frames, metadata, rosters)
5. Visualizing tracking frames (single frame & animated sequences)
6. Converting frames to DataFrames
7. Joining events with tracking data
8. Exporting frames as GIF, PNG, and MP4
9. Feature engineering (player speed, ball speed)
10. Pitch coordinate transformation
11. Pitch control computation & visualization
12. Accessing video URLs

Quick examples

import gandula

# --- Event data ---
events = gandula.get_events('41177.json')
df = gandula.gradient_events_to_dataframe(events)

# --- S3 tracking data ---
matches = gandula.list_s3_matches(competition_id=1, season='2025-2026')
frames = gandula.get_s3_frames(matches[0])

# --- Visualize ---
gandula.view(frames[0])

# --- Export ---
gandula.export(frames[100:200], fmt='gif', filename='play')

# --- Pitch control ---
from gandula.utils import compute_pitch_control_from_frames

result = compute_pitch_control_from_frames(
    frames,
    attacking_team='home',
    start_frame=frames[100].frame_id,
    end_frame=frames[400].frame_id,
    period=1,
)
gandula.view(result, frame_index=0)

More notebooks

Documentation

• API Reference
• Architecture
• Usage Guide
• Data Models

Development

Install dev dependencies and pre-commit hooks:

uv sync --extra dev
pre-commit install

Run tests:

uv run pytest tests/

License & Copyright

The main image is "Ballkid at soccer, China" by Micah Sittig, licensed under CC BY 2.0