# ml-kuleuven/un-xpass architecture

> Architecture diagram of the GitHub repository ml-kuleuven/un-xpass, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ml-kuleuven/un-xpass
- Repository: https://github.com/ml-kuleuven/un-xpass

## Overview

un-xPass evaluates soccer-player creativity from StatsBomb 360 passing data. Its user workflow is to load and convert match events, build feature/label datasets, train and evaluate pass-selection, pass-success, and pass-value models, then combine trained components into creativity ratings. The graph preserves these domain stages and the SoccerMap model layer, plus the database backends. Some command and rating details are documented in the README rather than visible in the excerpts; those links cite the README, and unsampled implementation specifics are omitted.

Main entry points: [`unxpass/__main__.py`](https://github.com/ml-kuleuven/un-xpass/blob/main/unxpass/__main__.py) (CLI commands), [`unxpass/components/base.py`](https://github.com/ml-kuleuven/un-xpass/blob/main/unxpass/components/base.py) (Component training), [`unxpass/databases/base.py`](https://github.com/ml-kuleuven/un-xpass/blob/main/unxpass/databases/base.py) (Database interface), [`unxpass/ratings.py`](https://github.com/ml-kuleuven/un-xpass/blob/main/unxpass/ratings.py) (Creativity ratings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["CLI workflow"]
  node_cli["CLI commands<br/>[__main__.py]"]
end

subgraph group_data["Match data"]
  node_import["Event import<br/>[base.py]"]
  node_dbapi["Database interface<br/>[base.py]"]
  node_sqlite[("SQLite store<br/>[sqlite.py]")]
  node_hdf[("HDF store<br/>[hdf.py]")]
  node_features["Feature generation<br/>[features.py]"]
  node_labels["Label generation<br/>[labels.py]"]
  node_datasets["Pass datasets<br/>[datasets.py]"]
end

subgraph group_models["Modeling"]
  node_base["Component training<br/>[base.py]"]
  node_selection["Pass selection<br/>[pass_selection.py]"]
  node_success["Pass success<br/>[pass_success.py]"]
  node_value["Pass value<br/>[pass_value.py]"]
  node_soccermap["SoccerMap network<br/>[soccermap.py]"]
end

subgraph group_ratings["Creativity ratings"]
  node_ratings["Creativity ratings<br/>[ratings.py]"]
end

subgraph group_infra["Configuration and tracking"]
  node_config["Experiment configuration<br/>[config.py]"]
end

node_user(("Researcher"))
node_mlflow["MLflow tracking"]

node_user -->|"runs commands"| node_cli
node_cli -->|"loads events"| node_import
node_import -->|"stores actions"| node_dbapi
node_dbapi -->|"selects backend"| node_sqlite
node_dbapi -->|"selects backend"| node_hdf
node_cli -->|"creates dataset"| node_datasets
node_datasets -->|"computes features"| node_features
node_datasets -->|"computes labels"| node_labels
node_features -->|"reads match data"| node_dbapi
node_labels -->|"reads match data"| node_dbapi
node_cli -->|"composes settings"| node_config
node_cli -->|"trains component"| node_base
node_base -->|"initializes dataset"| node_datasets
node_selection -->|"extends training"| node_base
node_success -->|"extends training"| node_base
node_value -->|"extends training"| node_base
node_selection -->|"uses network"| node_soccermap
node_value -->|"uses network"| node_soccermap
node_success -->|"uses network"| node_soccermap
node_cli -->|"computes ratings"| node_ratings
node_ratings -->|"loads model"| node_selection
node_ratings -->|"loads model"| node_success
node_ratings -->|"loads model"| node_value
node_cli -->|"logs runs"| node_mlflow
node_base -->|"tracks training"| node_mlflow

click node_cli "https://github.com/ml-kuleuven/un-xpass/blob/main/unxpass/__main__.py"
click node_import "https://github.com/ml-kuleuven/un-xpass/blob/main/unxpass/databases/base.py"
click node_dbapi "https://github.com/ml-kuleuven/un-xpass/blob/main/unxpass/databases/base.py"
click node_sqlite "https://github.com/ml-kuleuven/un-xpass/blob/main/unxpass/databases/sqlite.py"
click node_hdf "https://github.com/ml-kuleuven/un-xpass/blob/main/unxpass/databases/hdf.py"
click node_features "https://github.com/ml-kuleuven/un-xpass/blob/main/unxpass/features.py"
click node_labels "https://github.com/ml-kuleuven/un-xpass/blob/main/unxpass/labels.py"
click node_datasets "https://github.com/ml-kuleuven/un-xpass/blob/main/unxpass/datasets.py"
click node_base "https://github.com/ml-kuleuven/un-xpass/blob/main/unxpass/components/base.py"
click node_selection "https://github.com/ml-kuleuven/un-xpass/blob/main/unxpass/components/pass_selection.py"
click node_success "https://github.com/ml-kuleuven/un-xpass/blob/main/unxpass/components/pass_success.py"
click node_value "https://github.com/ml-kuleuven/un-xpass/blob/main/unxpass/components/pass_value.py"
click node_soccermap "https://github.com/ml-kuleuven/un-xpass/blob/main/unxpass/components/soccermap.py"
click node_ratings "https://github.com/ml-kuleuven/un-xpass/blob/main/unxpass/ratings.py"
click node_config "https://github.com/ml-kuleuven/un-xpass/blob/main/unxpass/config.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli toneBlue
class node_import,node_dbapi,node_sqlite,node_hdf,node_features,node_labels,node_datasets toneAmber
class node_base,node_selection,node_success,node_value,node_soccermap toneMint
class node_ratings toneRose
class node_config,node_user,node_mlflow toneIndigo
```

## Components

### CLI workflow

- [CLI commands](https://github.com/ml-kuleuven/un-xpass/blob/main/unxpass/__main__.py): `unxpass/__main__.py`

### Match data

- [Event import](https://github.com/ml-kuleuven/un-xpass/blob/main/unxpass/databases/base.py): `unxpass/databases/base.py`
- [Database interface](https://github.com/ml-kuleuven/un-xpass/blob/main/unxpass/databases/base.py): `unxpass/databases/base.py`
- [SQLite store](https://github.com/ml-kuleuven/un-xpass/blob/main/unxpass/databases/sqlite.py): `unxpass/databases/sqlite.py`
- [HDF store](https://github.com/ml-kuleuven/un-xpass/blob/main/unxpass/databases/hdf.py): `unxpass/databases/hdf.py`
- [Feature generation](https://github.com/ml-kuleuven/un-xpass/blob/main/unxpass/features.py): `unxpass/features.py`
- [Label generation](https://github.com/ml-kuleuven/un-xpass/blob/main/unxpass/labels.py): `unxpass/labels.py`
- [Pass datasets](https://github.com/ml-kuleuven/un-xpass/blob/main/unxpass/datasets.py): `unxpass/datasets.py`

### Modeling

- [Component training](https://github.com/ml-kuleuven/un-xpass/blob/main/unxpass/components/base.py): `unxpass/components/base.py`
- [Pass selection](https://github.com/ml-kuleuven/un-xpass/blob/main/unxpass/components/pass_selection.py): `unxpass/components/pass_selection.py`
- [Pass success](https://github.com/ml-kuleuven/un-xpass/blob/main/unxpass/components/pass_success.py): `unxpass/components/pass_success.py`
- [Pass value](https://github.com/ml-kuleuven/un-xpass/blob/main/unxpass/components/pass_value.py): `unxpass/components/pass_value.py`
- [SoccerMap network](https://github.com/ml-kuleuven/un-xpass/blob/main/unxpass/components/soccermap.py): `unxpass/components/soccermap.py`

### Creativity ratings

- [Creativity ratings](https://github.com/ml-kuleuven/un-xpass/blob/main/unxpass/ratings.py): `unxpass/ratings.py`

### Configuration and tracking

- [Experiment configuration](https://github.com/ml-kuleuven/un-xpass/blob/main/unxpass/config.py): `unxpass/config.py`

### Other components

- **Researcher**
- **MLflow tracking**

## Connections

- Researcher → CLI commands: runs commands (evidence: `README.md`)
- CLI commands → Event import: loads events (evidence: `unxpass/__main__.py`)
- Event import → Database interface: stores actions (evidence: `unxpass/databases/base.py`)
- Database interface → SQLite store: selects backend (evidence: `unxpass/databases/__init__.py`)
- Database interface → HDF store: selects backend (evidence: `unxpass/databases/__init__.py`)
- CLI commands → Pass datasets: creates dataset (evidence: `README.md`)
- Pass datasets → Feature generation: computes features (evidence: `unxpass/datasets.py`)
- Pass datasets → Label generation: computes labels (evidence: `unxpass/datasets.py`)
- Feature generation → Database interface: reads match data (evidence: `unxpass/features.py`)
- Label generation → Database interface: reads match data (evidence: `unxpass/labels.py`)
- CLI commands → Experiment configuration: composes settings (evidence: `unxpass/__main__.py`)
- CLI commands → Component training: trains component (evidence: `unxpass/__main__.py`)
- Component training → Pass datasets: initializes dataset (evidence: `unxpass/components/base.py`)
- Pass selection → Component training: extends training (evidence: `unxpass/components/pass_selection.py`)
- Pass success → Component training: extends training (evidence: `unxpass/components/pass_success.py`)
- Pass value → Component training: extends training (evidence: `unxpass/components/pass_value.py`)
- Pass selection → SoccerMap network: uses network (evidence: `unxpass/components/pass_selection.py`)
- Pass value → SoccerMap network: uses network (evidence: `unxpass/components/pass_value.py`)
- Pass success → SoccerMap network: uses network (evidence: `unxpass/components/pass_success.py`)
- CLI commands → Creativity ratings: computes ratings (evidence: `README.md`)
- Creativity ratings → Pass selection: loads model (evidence: `unxpass/ratings.py`)
- Creativity ratings → Pass success: loads model (evidence: `unxpass/ratings.py`)
- Creativity ratings → Pass value: loads model (evidence: `unxpass/ratings.py`)
- CLI commands → MLflow tracking: logs runs (evidence: `unxpass/__main__.py`)
- Component training → MLflow tracking: tracks training (evidence: `unxpass/components/base.py`)
