How imedslab/adatriplet works
Project type and purpose
• AdaTriplet is a Python-based metric-learning library focused on learning embeddings from medical images using Triplet/AdaTriplet losses.
• It provides command-line scripts (train.py, test.py, eval_ablation.py) to run experiments on X-ray data (OAI, ChestX-ray14).
File structure
• Top-level scripts:
• train.py, test.py, eval_ablation.py – CLI entry points (Controller layer)
• networks.py – model definitions (Feature extraction networks)
• config.yml, environment.yml – configuration & dependency management
• Library code under common/:
• data handling (data_loader.py, prepare_dataframe.py, split_train_test_data.py, parse_metadata.py)
• image transforms (image_transformation.py)
• metric-learning core (methods.py, main_loop.py)
• losses (losses/losses.py)
• miners (hard/auto-margin sampling in common/miners/)
• distance metrics (dist_metric.py)
• evaluation (evaluation_metrics/, evaluators.py)
• utilities (utilities/meters.py, utils.py)
• Packaging: setup.py declares this as an installable package.
Extract Insights from the README
• Workflow: create conda env, pip install -e ., prepare datasets, then python train.py … or python test.py ….
• Eight methods are supported (AdaTriplet, Triplet, ArcFace, etc.).
• Outputs include performance tables and figures under images/.
Core Components & Their Interactions
a. Controller / CLI Layer
• Scripts parse command-line args and load config.yml
• Invoke the MainLoop from common/main_loop.py
b. Data Layer
• Raw Images + Metadata + DataFrame → DataLoader
• ImageTransformations apply cropping, resizing, augmentation
• split_train_test_data.py handles dataset partitioning
c. Model & Sampling Layer
• networks.py defines backbone CNNs or embedding networks
• Samplers (“miners”) select triplets (hard, auto-margin)
d. Loss & Metric Learning Layer
• Loss functions computed in common/losses/losses.py
• Methods (e.g., AdaTriplet) encapsulate loss + mining strategy
e. Training/Evaluation Loop
• main_loop.py orchestrates epochs: forward pass → compute loss → backward → update
• evaluators.py and evaluation_metrics/ compute classification/ranking metrics
f. Visualization & Reporting
• Final tables and figures saved in images/
Architectural Patterns & Design Principles
• Modular pipeline: each concern (data, model, loss, evaluation) lives in its own namespace.
• Dependency Injection via the CLI + YAML config
• Plugin-style methods: new metric-learning methods can be registered via common/methods.py.
• Separation of concerns: miners, losses, metrics, and network architectures are decoupled.
Detailed Steps for the Engineer
1. Sketch a high-level pipeline: start from “User runs train.py” and end at “Results stored in images/”.
– From raw data store to DataLoader
– From DataLoader to Model + Miner + Loss
– From Loss back to Training Loop (optimizer)
– From Model outputs to Evaluator
– From Evaluator to Reporting/Visualization
– Rectangles for modules/packages
– Clouds for external systems
8. Every component from the file tree is represented or grouped logically.