# maxzaragoza2a/deeplearning-benchmark-project architecture

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

- Interactive diagram: https://gitdiagram.com/maxzaragoza2a/deeplearning-benchmark-project
- Repository: https://github.com/maxzaragoza2a/deeplearning-benchmark-project

## Overview

This repository is a few-shot learning benchmark for fine-grained insect-wing classification. Its principal workflow indexes and preprocesses images, creates class-disjoint and labelled/unlabelled episodes, trains and evaluates PRWN using either frozen DINOv2 embeddings or a trainable Conv-4, then compares results. It also includes a separate NCA implementation and post-run analysis. The README documents ProtoNet as a benchmark control, including PRWN configurations with the random-walk term disabled. Some connections are supported only by the README or source-index references; unsampled implementation details are not inferred.

Main entry points: [`scripts/train_prwn.py`](https://github.com/maxzaragoza2a/deeplearning-benchmark-project/blob/main/scripts/train_prwn.py) (DINOv2 PRWN run), [`scripts/train_prwn_conv4.py`](https://github.com/maxzaragoza2a/deeplearning-benchmark-project/blob/main/scripts/train_prwn_conv4.py) (Conv-4 PRWN run), [`src/data/dataset.py`](https://github.com/maxzaragoza2a/deeplearning-benchmark-project/blob/main/src/data/dataset.py) (Dataset index), [`scripts/evaluate_prwn.py`](https://github.com/maxzaragoza2a/deeplearning-benchmark-project/blob/main/scripts/evaluate_prwn.py) (PRWN evaluation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Dataset and episodes"]
  node_dataset["Dataset index<br/>[dataset.py]"]
  node_episodes["Episode sampler<br/>[episodes.py]"]
end

subgraph group_models["Embedding and methods"]
  node_dinov2["DINOv2 embeddings<br/>[backbone.py]"]
  node_conv4["Conv-4 backbone<br/>[conv4.py]"]
  node_prwn["PRWN method<br/>[prwn.py]"]
  node_nca_model["NCA model<br/>[model.py]"]
  node_nca_loss["NCA loss<br/>[loss.py]"]
end

subgraph group_runs["Training and evaluation"]
  node_config["Run configuration<br/>[config.py]"]
  node_prwn_train["DINOv2 PRWN run<br/>[train_prwn.py]"]
  node_conv4_train["Conv-4 PRWN run"]
  node_prwn_eval["PRWN evaluation<br/>[evaluate_prwn.py]"]
  node_nca_train["NCA training<br/>[train.py]"]
  node_nca_eval["NCA evaluation<br/>[evaluate.py]"]
end

subgraph group_analysis["Benchmark analysis"]
  node_results_analysis["Result analysis<br/>[analyze_results.py]"]
end

node_user(("Researcher"))
node_image_data[("Wing images")]
node_pretrained{{"Hugging Face model hub"}}

node_user -->|"starts run"| node_prwn_train
node_image_data -->|"indexes images"| node_dataset
node_prwn_train -->|"loads settings"| node_config
node_prwn_train -->|"builds index"| node_dataset
node_prwn_train -->|"splits classes"| node_episodes
node_prwn_train -->|"extracts features"| node_dinov2
node_prwn_train -->|"trains with"| node_prwn
node_dinov2 -->|"loads checkpoint"| node_pretrained
node_conv4_train -->|"loads settings"| node_config
node_conv4_train -->|"builds index"| node_dataset
node_conv4_train -->|"splits classes"| node_episodes
node_conv4_train -->|"trains backbone"| node_conv4
node_conv4_train -->|"trains with"| node_prwn
node_prwn_eval -->|"loads settings"| node_config
node_prwn_eval -->|"rebuilds index"| node_dataset
node_prwn_eval -->|"loads embeddings"| node_dinov2
node_prwn_eval -->|"uses evaluation"| node_prwn_train
node_nca_train -->|"trains model"| node_nca_model
node_nca_train -->|"uses loss"| node_nca_loss
node_nca_eval -->|"evaluates model"| node_nca_model
node_results_analysis -->|"rebuilds index"| node_dataset
node_results_analysis -->|"replays episodes"| node_episodes
node_results_analysis -->|"replays predictions"| node_prwn
node_results_analysis -->|"compares backbone"| node_conv4

click node_dataset "https://github.com/maxzaragoza2a/deeplearning-benchmark-project/blob/main/src/data/dataset.py"
click node_episodes "https://github.com/maxzaragoza2a/deeplearning-benchmark-project/blob/main/src/data/episodes.py"
click node_config "https://github.com/maxzaragoza2a/deeplearning-benchmark-project/blob/main/src/utils/config.py"
click node_dinov2 "https://github.com/maxzaragoza2a/deeplearning-benchmark-project/blob/main/src/models/backbone.py"
click node_conv4 "https://github.com/maxzaragoza2a/deeplearning-benchmark-project/blob/main/src/models/conv4.py"
click node_prwn "https://github.com/maxzaragoza2a/deeplearning-benchmark-project/blob/main/src/models/prwn.py"
click node_prwn_train "https://github.com/maxzaragoza2a/deeplearning-benchmark-project/blob/main/scripts/train_prwn.py"
click node_conv4_train "https://github.com/maxzaragoza2a/deeplearning-benchmark-project/blob/main/scripts/train_prwn_conv4.py"
click node_prwn_eval "https://github.com/maxzaragoza2a/deeplearning-benchmark-project/blob/main/scripts/evaluate_prwn.py"
click node_nca_model "https://github.com/maxzaragoza2a/deeplearning-benchmark-project/blob/main/scripts/nca_paper/model.py"
click node_nca_loss "https://github.com/maxzaragoza2a/deeplearning-benchmark-project/blob/main/scripts/nca_paper/loss.py"
click node_nca_train "https://github.com/maxzaragoza2a/deeplearning-benchmark-project/blob/main/scripts/nca_paper/train.py"
click node_nca_eval "https://github.com/maxzaragoza2a/deeplearning-benchmark-project/blob/main/scripts/nca_paper/evaluate.py"
click node_results_analysis "https://github.com/maxzaragoza2a/deeplearning-benchmark-project/blob/main/scripts/analyze_results.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_dataset,node_episodes toneBlue
class node_dinov2,node_conv4,node_prwn,node_nca_model,node_nca_loss,node_image_data toneAmber
class node_config,node_prwn_train,node_conv4_train,node_prwn_eval,node_nca_train,node_nca_eval toneMint
class node_results_analysis toneRose
class node_user,node_pretrained toneIndigo
```

## Components

### Dataset and episodes

- [Dataset index](https://github.com/maxzaragoza2a/deeplearning-benchmark-project/blob/main/src/data/dataset.py): `src/data/dataset.py`
- [Episode sampler](https://github.com/maxzaragoza2a/deeplearning-benchmark-project/blob/main/src/data/episodes.py): `src/data/episodes.py`

### Embedding and methods

- [DINOv2 embeddings](https://github.com/maxzaragoza2a/deeplearning-benchmark-project/blob/main/src/models/backbone.py): `src/models/backbone.py`
- [Conv-4 backbone](https://github.com/maxzaragoza2a/deeplearning-benchmark-project/blob/main/src/models/conv4.py): `src/models/conv4.py`
- [PRWN method](https://github.com/maxzaragoza2a/deeplearning-benchmark-project/blob/main/src/models/prwn.py): `src/models/prwn.py`
- [NCA model](https://github.com/maxzaragoza2a/deeplearning-benchmark-project/blob/main/scripts/nca_paper/model.py): `scripts/nca_paper/model.py`
- [NCA loss](https://github.com/maxzaragoza2a/deeplearning-benchmark-project/blob/main/scripts/nca_paper/loss.py): `scripts/nca_paper/loss.py`

### Training and evaluation

- [Run configuration](https://github.com/maxzaragoza2a/deeplearning-benchmark-project/blob/main/src/utils/config.py): `src/utils/config.py`
- [DINOv2 PRWN run](https://github.com/maxzaragoza2a/deeplearning-benchmark-project/blob/main/scripts/train_prwn.py): `scripts/train_prwn.py`
- [Conv-4 PRWN run](https://github.com/maxzaragoza2a/deeplearning-benchmark-project/blob/main/scripts/train_prwn_conv4.py): `scripts/train_prwn_conv4.py`
- [PRWN evaluation](https://github.com/maxzaragoza2a/deeplearning-benchmark-project/blob/main/scripts/evaluate_prwn.py): `scripts/evaluate_prwn.py`
- [NCA training](https://github.com/maxzaragoza2a/deeplearning-benchmark-project/blob/main/scripts/nca_paper/train.py): `scripts/nca_paper/train.py`
- [NCA evaluation](https://github.com/maxzaragoza2a/deeplearning-benchmark-project/blob/main/scripts/nca_paper/evaluate.py): `scripts/nca_paper/evaluate.py`

### Benchmark analysis

- [Result analysis](https://github.com/maxzaragoza2a/deeplearning-benchmark-project/blob/main/scripts/analyze_results.py): `scripts/analyze_results.py`

### Other components

- **Researcher**
- **Wing images**
- **Hugging Face model hub**

## Connections

- Researcher → DINOv2 PRWN run: starts run (evidence: `scripts/train_prwn.py`)
- Wing images → Dataset index: indexes images (evidence: `src/data/dataset.py`)
- DINOv2 PRWN run → Run configuration: loads settings (evidence: `scripts/train_prwn.py`)
- DINOv2 PRWN run → Dataset index: builds index (evidence: `scripts/train_prwn.py`)
- DINOv2 PRWN run → Episode sampler: splits classes (evidence: `scripts/train_prwn.py`)
- DINOv2 PRWN run → DINOv2 embeddings: extracts features (evidence: `scripts/train_prwn.py`)
- DINOv2 PRWN run → PRWN method: trains with (evidence: `scripts/train_prwn.py`)
- DINOv2 embeddings → Hugging Face model hub: loads checkpoint (evidence: `src/models/backbone.py`)
- Conv-4 PRWN run → Run configuration: loads settings (evidence: `scripts/train_prwn_conv4.py`)
- Conv-4 PRWN run → Dataset index: builds index (evidence: `scripts/train_prwn_conv4.py`)
- Conv-4 PRWN run → Episode sampler: splits classes (evidence: `scripts/train_prwn_conv4.py`)
- Conv-4 PRWN run → Conv-4 backbone: trains backbone (evidence: `scripts/train_prwn_conv4.py`)
- Conv-4 PRWN run → PRWN method: trains with (evidence: `scripts/train_prwn_conv4.py`)
- PRWN evaluation → Run configuration: loads settings (evidence: `scripts/evaluate_prwn.py`)
- PRWN evaluation → Dataset index: rebuilds index (evidence: `scripts/evaluate_prwn.py`)
- PRWN evaluation → DINOv2 embeddings: loads embeddings (evidence: `scripts/evaluate_prwn.py`)
- PRWN evaluation → DINOv2 PRWN run: uses evaluation (evidence: `scripts/evaluate_prwn.py`)
- NCA training → NCA model: trains model (evidence: `scripts/nca_paper/train.py`)
- NCA training → NCA loss: uses loss (evidence: `scripts/nca_paper/train.py`)
- NCA evaluation → NCA model: evaluates model (evidence: `scripts/nca_paper/evaluate.py`)
- Result analysis → Dataset index: rebuilds index (evidence: `scripts/analyze_results.py`)
- Result analysis → Episode sampler: replays episodes (evidence: `scripts/analyze_results.py`)
- Result analysis → PRWN method: replays predictions (evidence: `scripts/analyze_results.py`)
- Result analysis → Conv-4 backbone: compares backbone (evidence: `scripts/analyze_results.py`)