Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,155 @@
+---
+tags:
+- pytorch
+- pytorch-geometric
+- xG
+- football
+- soccer
+- expected-goals
+- gnn
+- heterogeneous-graph
+- graph-neural-network
+- binary-classification
+- one-graph-architecture
+library_name: pytorch
+---
+
+# Heterogeneous GNN xG Prediction Model (Focal Loss, One Graph Architecture)
+
+This is a Heterogeneous Graph Neural Network (GNN) model trained to predict Expected Goals (xG) in football/soccer using a single persistent graph with shot-indexed edges.
+
+## Model Description
+
+- **Architecture**: Heterogeneous GNN with GAT attention layers
+- **Graph Structure**: One persistent graph with all nodes, shot-specific edge masking
+  - **Nodes**: shooter (player embeddings, 496 total), goal (learnable embedding), goalkeeper (learnable embedding)
+  - **Edges**: 4 edge types (bidirectional shooter↔goal and shooter↔goalkeeper)
+  - **Global Features**: 18 shot-level contextual features
+- **Hidden Dimensions**: 64
+- **Number of Layers**: 3 GAT layers
+- **Attention Heads**: 4
+- **Dropout Rate**: 0.3
+- **Framework**: PyTorch Geometric
+- **Loss Function**: Focal Loss (alpha=0.8773, gamma=2.0)
+
+## Performance Metrics
+
+- **Test Loss**: 0.08266454190015793
+- **Test AUC**: 0.609370231628418
+- **Test Accuracy**: 0.14332698285579681
+- **Test F1**: 0.2105599045753479
+
+## Global Features (18 features)
+
+The model uses the following contextual features for each shot:
+
+- ball_closer_than_gk
+- body_part_name_Left Foot
+- body_part_name_Other
+- body_part_name_Right Foot
+- goal_dist_to_gk
+- minute
+- nearest_opponent_dist
+- nearest_teammate_dist
+- opponents_within_5m
+- play_pattern_name_From Counter
+- play_pattern_name_From Free Kick
+- play_pattern_name_From Goal Kick
+- play_pattern_name_From Keeper
+- play_pattern_name_From Kick Off
+- play_pattern_name_From Throw In
+- play_pattern_name_Other
+- play_pattern_name_Regular Play
+- teammates_within_5m
+
+## Graph Structure
+
+### Persistent Nodes
+1. **Shooter Nodes**: 496 player embeddings (dimension: 64)
+2. **Goal Node**: 1 learnable goal representation (dimension: 64)
+3. **Goalkeeper Node**: 1 learnable goalkeeper representation (dimension: 64)
+
+### Edge Types (with attributes, shot-indexed)
+1. **shooter → goal**: Distance (meters) + Angle to goal (radians)
+2. **goal → shooter**: Reverse edges with same attributes
+3. **shooter → goalkeeper**: Distance to goalkeeper (meters)
+4. **goalkeeper → shooter**: Reverse edges with same attributes
+
+All edges are indexed by shot_idx for efficient masking during prediction.
+
+## Usage
+
+```python
+import torch
+from torch_geometric.data import HeteroData
+from huggingface_hub import hf_hub_download
+import importlib.util
+import json
+
+# Download files
+model_path = hf_hub_download(repo_id="rokati/focal_gnn_one_graph", filename="best_gnn_model.pth")
+architecture_path = hf_hub_download(repo_id="rokati/focal_gnn_one_graph", filename="model_architecture.py")
+config_path = hf_hub_download(repo_id="rokati/focal_gnn_one_graph", filename="config.json")
+
+# Load configuration
+with open(config_path, 'r') as f:
+    config = json.load(f)
+
+# Load architecture
+spec = importlib.util.spec_from_file_location("model_architecture", architecture_path)
+model_module = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(model_module)
+
+# Create model instance
+model = model_module.XGNet(
+    num_players=config['num_players'],
+    hid=config['hidden_dim'],
+    p=config['dropout_rate'],
+    heads=config['num_heads'],
+    num_layers=config['num_layers'],
+    use_norm=config['use_norm'],
+    num_global_features=config['num_global_features']
+)
+
+# Load weights
+model.load_state_dict(torch.load(model_path, map_location=torch.device('cpu')))
+model.eval()
+
+# Prepare persistent graph (build once with all players/shots)
+# Then predict by passing the graph and shot_idx:
+with torch.no_grad():
+    xg_prediction = torch.sigmoid(model(graph, shot_idx)).item()
+```
+
+## Training Details
+
+The model was trained with:
+- **Loss Function**: Focal Loss (addresses class imbalance)
+- **Optimizer**: Adam (lr=1e-3, weight_decay=1e-4)
+- **Scheduler**: ReduceLROnPlateau
+- **Batch Size**: 32
+- **Max Epochs**: 100
+- **Early Stopping**: Patience=15 on validation F1
+- **Framework**: PyTorch Lightning
+
+## Model Architecture
+
+The heterogeneous GNN uses:
+1. **Node Embeddings**: Learnable embeddings for shooters, goal, and goalkeeper
+2. **Edge-Conditioned Attention**: GAT layers with edge attributes
+3. **Bidirectional Message Passing**: 3 layers with forward and reverse edges
+4. **Shot-Indexed Masking**: Efficient prediction via edge masking
+5. **Global Context**: Shot-level features encoded and combined
+6. **Readout**: Concatenate shooter + goal + goalkeeper representations → MLP classifier
+
+## Key Innovation
+
+Unlike traditional approaches that create separate graphs for each shot, this model uses:
+- **One persistent graph** with all nodes
+- **Shot-indexed edges** for efficient masking
+- **Bidirectional message passing** for richer representations
+- This architecture is more memory-efficient and allows for better batch processing
+
+## License
+
+MIT