Graphs

Converting NFL tracking data to graph structures.

class unravel.american_football.AmericanFootballGraphConverter[source]

Bases: DefaultGraphConverter

Convert NFL Big Data Bowl tracking data to graph structures for GNN training.

This class transforms American Football tracking data from Polars DataFrames into graph representations suitable for Graph Neural Networks (GNNs). Each frame becomes a graph with players and the football as nodes, with edges representing spatial relationships or team affiliations.

The converter supports two GNN frameworks: - PyTorch Geometric (recommended) via to_pytorch_graphs() - Spektral (deprecated, Python 3.11 only) via to_spektral_graphs()

Graph Structure:

Nodes: Players (22 total: 11 offense + 11 defense) and football
Node Features: Position, velocity, acceleration, orientation, direction, height, weight, position type (12+ default features)
Edges: Defined by adjacency_matrix_type (team-based, spatial, or dense)
Edge Features: Distances, angles, relative velocities, orientations (7 default features)
Global Features: Optional play-level features attached to football node
Labels: Play outcome or custom labels (e.g., yards gained, tackle probability)

The graph structure captures: - Offensive and defensive formations - Player movements and accelerations - Spatial relationships between players - Position-specific information (QB, WR, CB, etc.) - Body orientations and movement directions - Anthropometric data (height, weight)

Parameters:

dataset (BigDataBowlDataset) – Preprocessed NFL tracking data with player positions, velocities, and play information.
chunk_size (int, optional) – Number of frames to process per batch for memory efficiency. Defaults to 2000.
attacking_non_qb_node_value (float, optional) – Node feature value (0-1) assigned to offensive players who are not the quarterback. Used to distinguish QB from other offensive players in node features. Defaults to 0.1.
graph_feature_cols (Optional[List[str]], optional) – List of column names containing graph-level features (e.g., win probability, expected points) to attach to the football node. These columns must have the same value for all nodes in each frame. Defaults to None (no graph features).
**kwargs – Additional parameters passed to DefaultGraphConverter, including: - adjacency_matrix_type: Edge connectivity pattern - label_col: Column name for graph labels - graph_id_col: Column name for graph identifiers - prediction: Whether in prediction mode (no labels)

dataset

Processed tracking data from BigDataBowlDataset.

Type:: pl.DataFrame

settings

Configuration with pitch dimensions, adjacency patterns, and feature settings.

Type:: AmericanFootballGraphSettings

label_column

Name of the label column for supervised learning.

Type:: str

graph_id_column

Name of the graph ID column for batching.

Type:: str

Raises:

Exception – If dataset is not an instance of BigDataBowlDataset.
Exception – If label_column or graph_id_column are not strings.
Exception – If label_column is missing when not in prediction mode.
Exception – If graph_id_column is missing from dataset.
Exception – If attacking_non_qb_node_value is not float or int.
Exception – If frames with missing football or insufficient players are detected.

Example

>>> from unravel.american_football.dataset import BigDataBowlDataset
>>> from unravel.american_football.graphs import AmericanFootballGraphConverter
>>>
>>> # Load Big Data Bowl data
>>> dataset = BigDataBowlDataset(
...     tracking_file_path="tracking.csv",
...     players_file_path="players.csv",
...     plays_file_path="plays.csv"
... )
>>>
>>> # Add labels and graph IDs
>>> dataset.add_dummy_labels()
>>> dataset.add_graph_ids()
>>>
>>> # Initialize converter
>>> converter = AmericanFootballGraphConverter(
...     dataset=dataset,
...     adjacency_matrix_type="delaunay",
...     label_col="label",
...     graph_id_col="graph_id"
... )
>>>
>>> # Convert to PyTorch Geometric format
>>> pyg_dataset = converter.to_pytorch_graphs()
>>> print(f"Number of graphs: {len(pyg_dataset)}")
>>> print(f"Node features: {pyg_dataset[0].x.shape}")
>>> print(f"Edge features: {pyg_dataset[0].edge_attr.shape}")
>>>
>>> # Add graph-level features (e.g., expected points)
>>> # First, join expected points to dataset
>>> dataset.data = dataset.data.join(
...     expected_points_df,
...     on=["game_id", "play_id"],
...     how="left"
... )
>>> converter = AmericanFootballGraphConverter(
...     dataset=dataset,
...     graph_feature_cols=["expected_points", "win_probability"]
... )
>>> pyg_dataset = converter.to_pytorch_graphs()

Note

The converter automatically filters out frames with missing footballs or insufficient players (< 10 per frame).
Node ordering: Offensive players (sorted by ascending team_id sort), then defensive players, then football (always last).
The QB receives a special node feature value (1.0), while other offensive players receive attacking_non_qb_node_value (default 0.1).
Graph-level features must be constant within each frame. If they vary, a ValueError is raised.
Position names are encoded as one-hot vectors in node features.

Warning

Spektral support is deprecated and only works on Python 3.11. Use PyTorch Geometric for new projects.