How virajprabhu/clue works
Project Type and Purpose
• This project is a research codebase for Active Domain Adaptation in computer vision. Its purpose is to select target data points intelligently (using uncertainty and clustering) in order to efficiently train deep neural networks when there is a domain shift.
• The README explains that it is used for active learning under domain adaptation scenarios (e.g., SVHN→MNIST and DomainNet experiments) and includes training, evaluation, demo, and preprocessing components.
Analyzing the File Structure
• Top-Level Files:
– CLUE.py, train.py, evaluate.py, sample.py, utils.py, and data.py are key executable scripts.
– demo.ipynb is the Jupyter Notebook for interactive demonstrations.
• The “adapt” Directory:
– Contains model definitions and solver implementation:
▪ “adapt/models” houses network definitions such as adapt_net.py, task_net.py, and models.py.
▪ “adapt/solvers” includes files (adapt.py, solver.py) that likely implement the active domain adaptation strategies.
• Configuration Files:
– The “config” folder is organized by dataset (digits, domainnet) with YAML configuration files that set hyperparameters and experimental settings.
• Checkpoints, Results, and Plots:
– The “checkpoints” folder holds model state files that aren’t generated on the fly.
– “results” and “plots” record evaluation outputs and visualizations respectively.
• Other Supporting Scripts:
– “preprocess_domainnet.py” provides data preprocessing for DomainNet.
– “requirements.txt” and “license.txt” deal with dependencies and legal aspects.
Key Components
a. Data & Input Layer:
– Data Ingestion: “data.py” and the automatic download/preprocessing routines (e.g., via preprocess_domainnet.py) for datasets (SVHN, MNIST, DomainNet).
– Configuration Input: YAML config files under “config/” (for digits and domainnet) which determine experimental and hyperparameter settings.
b. Model & Adaptation Module:
– Model Definitions: Components in “adapt/models” that define the network architectures (e.g., CLUE network elements, task networks).
– Adaptation / Solver Module: Code in “adapt/solvers” that implements the active domain adaptation strategy (including uncertainty-weighted clustering).
c. Training Pipeline:
– The train.py script acts as the entry-point for training. It integrates:
▪ Reading configuration files.
▪ Setting up the deep learning model and adaptation strategy.
▪ Saving model checkpoints (managed in the “checkpoints” folder).
– The training procedure may also use utilities from utils.py.
d. Evaluation & Visualization Module:
– The evaluate.py script processes checkpoints and outputs performance metrics, storing results as JSON and generating plots (saved in “results” and “plots”).
e. Demo / Interactive Module:
– A Jupyter notebook (demo.ipynb) allowing interactive exploration, dataset loading, label acquisition demonstration, training on target data with acquired labels, and visualization of performance.
Relationships and Interactions
• Data Flow: Raw data (from datasets, automatically downloaded or preprocessed by preprocess_domainnet.py) flows into the training module.
• Model Component: The train.py workflow leverages the “adapt” module to set up the model (using definitions from adapt/models) and apply the adaptation strategy (via adapt/solvers).
• Checkpoints: After training, models are saved into the “checkpoints” directory, which then get utilized during evaluation or for resuming training.
• Evaluation: The evaluate.py script uses trained models (and their checkpoints) and configuration data to generate performance metrics/plots.
• Demo Workflow: The demo.ipynb integrates the whole pipeline interactively, calling on data loading, checkpoint usage, model inference, and plotting.
Architectural Patterns and Technologies
• The codebase follows a modular structure with clear separation of concerns:
– Model definitions and solver logic are separated into dedicated submodules.
– Configuration-driven experiments via YAML files allow flexible testing of different settings.
– Scripts (train.py, evaluate.py) serve as orchestration layers.
• Underlying Technology: Built on PyTorch (as mentioned in the README), with models defined for active domain adaptation.