How sgvaze/generalized-category-discovery works
Project Type and Purpose
• This is a research‐code repository for “Generalized Category Discovery” (GCD), an ML pipeline that:
• Trains a representation (contrastive learning) on partially labeled data
• Extracts features using the trained model
• Applies (semi‐supervised) k‐means to assign categories to unlabelled examples
• Evaluates performance under two metrics (ACC v1 & v2)
Main Architectural Components
A. Data & Configuration
• Datasets (data/*): CIFAR, ImageNet, CUB, Stanford Cars, Herbarium19, SSB splits
• Augmentations module (data/augmentations)
• config.py: paths & experiment settings
• environment.yml & requirements.txt: dependency management
B. Training Module
• Contrastive training code (methods/contrastive_training/contrastive_training.py)
• Model definitions (models/resnet_twohead.py, models/vision_transformer.py)
• Schedulers & utils (project_utils/schedulers.py, general_utils.py)
• Slurm output parser (project_utils/slurm_out_parser.py)
C. Feature Extraction
• extract_features.sh (bash_scripts) orchestrates
• methods/clustering/extract_features.py reads a checkpoint, dumps feature vectors
D. Clustering Module
• methods/clustering/k_means.py & faster_mix_k_means_pytorch.py
• feature_vector_dataset.py for DataLoader abstraction
• Estimate optimal K (methods/estimate_k/estimate_k.py)
E. Evaluation & Logging
• cluster_and_log_utils.py implements ACC v1 & v2 (Hungarian assignment)
• Logs written to SAVE_DIR via bash scripts
Interactions & Data Flow
1. Data Ingestion: raw images → augmentations → DataLoaders
2. Contrastive Training: DataLoader + model → optimized weights → checkpoint saved
3. Feature Extraction: checkpoint + DataLoader → feature files (.npy/.pkl)
4. Clustering: features + optional labels → cluster assignments → metrics
5. Evaluation: assignments + ground truth → ACC old/new/all → log outputs
Architectural Patterns & Design Principles
• Pipeline/Layered Pattern: clear separation between data, model, training, feature‐extraction, clustering, evaluation
• Modular & Pluggable:
• New augmentations under data/augmentations/
• Swap in a different model under models/
• Extend clustering by dropping in a new method under methods/clustering/
• Script‐driven Orchestration: bash_scripts provide reproducible end‐to‐end runs