# donny31415/group-sprint-1 architecture

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

- Interactive diagram: https://gitdiagram.com/donny31415/group-sprint-1
- Repository: https://github.com/donny31415/group-sprint-1

## Overview

This repository is a research workflow for estimating football-shot expected goals and analysing model performance. The principal path runs from shot data through preparation and model-specific prediction to common evaluation and spatial/team analysis. The README documents the main report sequence and capabilities; the sampled random-forest scripts show its feature split, model fitting, tuning and test prediction. Other model internals are represented at their documented report paths, not as inspected implementations.

Main entry points: [`report/07_comparison_and_analysis.ipynb`](https://github.com/donny31415/group-sprint-1/blob/main/report/07_comparison_and_analysis.ipynb) (Model comparison), [`data/shots_cleaned.csv`](https://github.com/donny31415/group-sprint-1/blob/main/data/shots_cleaned.csv) (Cleaned shots), [`luke/rf_01_features_and_split.py`](https://github.com/donny31415/group-sprint-1/blob/main/luke/rf_01_features_and_split.py) (Season feature split), [`report/02_data_processing.ipynb`](https://github.com/donny31415/group-sprint-1/blob/main/report/02_data_processing.ipynb) (Data processing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Shot data"]
  node_understat["Understat shots"]
  node_statsbomb["StatsBomb shots"]
  node_cleaned["Cleaned shots<br/>[shots_cleaned.csv]"]
  node_processing["Data processing"]
end

subgraph group_models["Model development"]
  node_lr["Logistic regression"]
  node_gb["Gradient boosting"]
  node_rfmodel["Random forest"]
  node_nn["Neural network<br/>[neural_network.Rmd]"]
  node_baseline["Base-rate model"]
  node_lrpred["LR predictions"]
  node_gbpred["GB predictions"]
  node_rfpred["RF predictions"]
  node_nnpred["NN predictions"]
end

subgraph group_evaluation["Evaluation and analysis"]
  node_benchmark["Understat benchmark"]
  node_comparison["Model comparison"]
  node_metrics["Performance table"]
  node_heatmaps["Shot heatmaps<br/>[08_heatmaps.ipynb]"]
  node_teamxg["Team xG analysis<br/>[08_heatmaps.ipynb]"]
end

subgraph group_rf["Random forest detail"]
  node_rf_split["Season feature split"]
  node_rf_tree["Single tree"]
  node_rf_oob["Forest OOB scoring"]
  node_rf_tuning["Forest tuning"]
  node_rf_final["Final forest"]
end

node_understat -->|"prepares"| node_processing
node_statsbomb -->|"considers"| node_processing
node_processing -->|"produces"| node_cleaned
node_cleaned -->|"models"| node_lr
node_cleaned -->|"models"| node_gb
node_cleaned -->|"models"| node_rfmodel
node_cleaned -->|"models"| node_nn
node_cleaned -->|"splits seasons"| node_rf_split
node_rf_split -->|"supplies features"| node_rf_tree
node_rf_split -->|"supplies data"| node_rf_oob
node_rf_split -->|"supplies groups"| node_rf_tuning
node_rf_tuning -->|"selects settings"| node_rf_final
node_rf_split -->|"supplies test data"| node_rf_final
node_lr -->|"predicts"| node_lrpred
node_gb -->|"predicts"| node_gbpred
node_rfmodel -->|"predicts"| node_rfpred
node_nn -->|"predicts"| node_nnpred
node_lrpred -->|"compares"| node_comparison
node_gbpred -->|"compares"| node_comparison
node_rfpred -->|"compares"| node_comparison
node_nnpred -->|"compares"| node_comparison
node_baseline -->|"benchmarks"| node_comparison
node_benchmark -->|"benchmarks"| node_comparison
node_comparison -->|"reports scores"| node_metrics
node_rf_final -.->|"writes predictions"| node_rfpred
node_comparison -->|"supports analysis"| node_heatmaps
node_heatmaps -->|"aggregates xG"| node_teamxg

click node_understat "https://github.com/donny31415/group-sprint-1/blob/main/data/understat_shots.csv"
click node_statsbomb "https://github.com/donny31415/group-sprint-1/blob/main/data/statsbomb_shots_all.csv"
click node_cleaned "https://github.com/donny31415/group-sprint-1/blob/main/data/shots_cleaned.csv"
click node_processing "https://github.com/donny31415/group-sprint-1/blob/main/report/02_data_processing.ipynb"
click node_lr "https://github.com/donny31415/group-sprint-1/blob/main/report/03_logistic_regression.ipynb"
click node_gb "https://github.com/donny31415/group-sprint-1/blob/main/report/04_gradient_boosting.ipynb"
click node_rfmodel "https://github.com/donny31415/group-sprint-1/blob/main/report/05_random_forest.ipynb"
click node_nn "https://github.com/donny31415/group-sprint-1/blob/main/dylan/neural_network.Rmd"
click node_baseline "https://github.com/donny31415/group-sprint-1/blob/main/report/07_comparison_and_analysis.ipynb"
click node_lrpred "https://github.com/donny31415/group-sprint-1/blob/main/results/lr_xg_predictions_2025_26.csv"
click node_gbpred "https://github.com/donny31415/group-sprint-1/blob/main/results/gb_xg_predictions_2025_26.csv"
click node_rfpred "https://github.com/donny31415/group-sprint-1/blob/main/results/rf_xg_predictions_2025_26.csv"
click node_nnpred "https://github.com/donny31415/group-sprint-1/blob/main/results/nn_xg_predictions_2025_26.csv"
click node_benchmark "https://github.com/donny31415/group-sprint-1/blob/main/report/07_comparison_and_analysis.ipynb"
click node_comparison "https://github.com/donny31415/group-sprint-1/blob/main/report/07_comparison_and_analysis.ipynb"
click node_metrics "https://github.com/donny31415/group-sprint-1/blob/main/results/statistical_performance_analysis_table.csv"
click node_heatmaps "https://github.com/donny31415/group-sprint-1/blob/main/report/08_heatmaps.ipynb"
click node_teamxg "https://github.com/donny31415/group-sprint-1/blob/main/report/08_heatmaps.ipynb"
click node_rf_split "https://github.com/donny31415/group-sprint-1/blob/main/luke/rf_01_features_and_split.py"
click node_rf_tree "https://github.com/donny31415/group-sprint-1/blob/main/luke/rf_02_single_tree.py"
click node_rf_oob "https://github.com/donny31415/group-sprint-1/blob/main/luke/rf_03_basic_forest_oob.py"
click node_rf_tuning "https://github.com/donny31415/group-sprint-1/blob/main/luke/rf_04_grid_search.py"
click node_rf_final "https://github.com/donny31415/group-sprint-1/blob/main/luke/rf_05_final_model_and_baselines.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_understat,node_statsbomb,node_cleaned,node_processing toneBlue
class node_lr,node_gb,node_rfmodel,node_nn,node_baseline,node_lrpred,node_gbpred,node_rfpred,node_nnpred toneAmber
class node_benchmark,node_comparison,node_metrics,node_heatmaps,node_teamxg toneMint
class node_rf_split,node_rf_tree,node_rf_oob,node_rf_tuning,node_rf_final toneRose
```

## Components

### Shot data

- [Understat shots](https://github.com/donny31415/group-sprint-1/blob/main/data/understat_shots.csv): `data/understat_shots.csv`
- [StatsBomb shots](https://github.com/donny31415/group-sprint-1/blob/main/data/statsbomb_shots_all.csv): `data/statsbomb_shots_all.csv`
- [Cleaned shots](https://github.com/donny31415/group-sprint-1/blob/main/data/shots_cleaned.csv): `data/shots_cleaned.csv`
- [Data processing](https://github.com/donny31415/group-sprint-1/blob/main/report/02_data_processing.ipynb): `report/02_data_processing.ipynb`

### Model development

- [Logistic regression](https://github.com/donny31415/group-sprint-1/blob/main/report/03_logistic_regression.ipynb): `report/03_logistic_regression.ipynb`
- [Gradient boosting](https://github.com/donny31415/group-sprint-1/blob/main/report/04_gradient_boosting.ipynb): `report/04_gradient_boosting.ipynb`
- [Random forest](https://github.com/donny31415/group-sprint-1/blob/main/report/05_random_forest.ipynb): `report/05_random_forest.ipynb`
- [Neural network](https://github.com/donny31415/group-sprint-1/blob/main/dylan/neural_network.Rmd): `dylan/neural_network.Rmd`
- [Base-rate model](https://github.com/donny31415/group-sprint-1/blob/main/report/07_comparison_and_analysis.ipynb): `report/07_comparison_and_analysis.ipynb`
- [LR predictions](https://github.com/donny31415/group-sprint-1/blob/main/results/lr_xg_predictions_2025_26.csv): `results/lr_xg_predictions_2025_26.csv`
- [GB predictions](https://github.com/donny31415/group-sprint-1/blob/main/results/gb_xg_predictions_2025_26.csv): `results/gb_xg_predictions_2025_26.csv`
- [RF predictions](https://github.com/donny31415/group-sprint-1/blob/main/results/rf_xg_predictions_2025_26.csv): `results/rf_xg_predictions_2025_26.csv`
- [NN predictions](https://github.com/donny31415/group-sprint-1/blob/main/results/nn_xg_predictions_2025_26.csv): `results/nn_xg_predictions_2025_26.csv`

### Evaluation and analysis

- [Understat benchmark](https://github.com/donny31415/group-sprint-1/blob/main/report/07_comparison_and_analysis.ipynb): `report/07_comparison_and_analysis.ipynb`
- [Model comparison](https://github.com/donny31415/group-sprint-1/blob/main/report/07_comparison_and_analysis.ipynb): `report/07_comparison_and_analysis.ipynb`
- [Performance table](https://github.com/donny31415/group-sprint-1/blob/main/results/statistical_performance_analysis_table.csv): `results/statistical_performance_analysis_table.csv`
- [Shot heatmaps](https://github.com/donny31415/group-sprint-1/blob/main/report/08_heatmaps.ipynb): `report/08_heatmaps.ipynb`
- [Team xG analysis](https://github.com/donny31415/group-sprint-1/blob/main/report/08_heatmaps.ipynb): `report/08_heatmaps.ipynb`

### Random forest detail

- [Season feature split](https://github.com/donny31415/group-sprint-1/blob/main/luke/rf_01_features_and_split.py): `luke/rf_01_features_and_split.py`
- [Single tree](https://github.com/donny31415/group-sprint-1/blob/main/luke/rf_02_single_tree.py): `luke/rf_02_single_tree.py`
- [Forest OOB scoring](https://github.com/donny31415/group-sprint-1/blob/main/luke/rf_03_basic_forest_oob.py): `luke/rf_03_basic_forest_oob.py`
- [Forest tuning](https://github.com/donny31415/group-sprint-1/blob/main/luke/rf_04_grid_search.py): `luke/rf_04_grid_search.py`
- [Final forest](https://github.com/donny31415/group-sprint-1/blob/main/luke/rf_05_final_model_and_baselines.py): `luke/rf_05_final_model_and_baselines.py`

## Connections

- Understat shots → Data processing: prepares (evidence: `README.md`)
- StatsBomb shots → Data processing: considers (evidence: `README.md`)
- Data processing → Cleaned shots: produces (evidence: `README.md`)
- Cleaned shots → Logistic regression: models (evidence: `README.md`)
- Cleaned shots → Gradient boosting: models (evidence: `README.md`)
- Cleaned shots → Random forest: models (evidence: `README.md`)
- Cleaned shots → Neural network: models (evidence: `README.md`)
- Cleaned shots → Season feature split: splits seasons (evidence: `luke/rf_01_features_and_split.py`)
- Season feature split → Single tree: supplies features (evidence: `luke/rf_02_single_tree.py`)
- Season feature split → Forest OOB scoring: supplies data (evidence: `luke/rf_03_basic_forest_oob.py`)
- Season feature split → Forest tuning: supplies groups (evidence: `luke/rf_04_grid_search.py`)
- Forest tuning → Final forest: selects settings (evidence: `luke/rf_05_final_model_and_baselines.py`)
- Season feature split → Final forest: supplies test data (evidence: `luke/rf_05_final_model_and_baselines.py`)
- Logistic regression → LR predictions: predicts (evidence: `README.md`)
- Gradient boosting → GB predictions: predicts (evidence: `README.md`)
- Random forest → RF predictions: predicts (evidence: `README.md`)
- Neural network → NN predictions: predicts (evidence: `README.md`)
- LR predictions → Model comparison: compares (evidence: `README.md`)
- GB predictions → Model comparison: compares (evidence: `README.md`)
- RF predictions → Model comparison: compares (evidence: `README.md`)
- NN predictions → Model comparison: compares (evidence: `README.md`)
- Base-rate model → Model comparison: benchmarks (evidence: `README.md`)
- Understat benchmark → Model comparison: benchmarks (evidence: `README.md`)
- Model comparison → Performance table: reports scores (evidence: `README.md`)
- Final forest → RF predictions: writes predictions
- Model comparison → Shot heatmaps: supports analysis (evidence: `README.md`)
- Shot heatmaps → Team xG analysis: aggregates xG (evidence: `README.md`)
