Skip to content

PyTorch Image Classifier - Documentation

Complete documentation for the PyTorch Image Classification framework.

Documentation Structure

🚀 Getting Started

New to the framework? Start here:

  1. Installation - Setup and dependencies
  2. Data Preparation - Organize your dataset ⚠️ CRITICAL
  3. Quick Start - Train your first model

⚙️ Configuration

Complete configuration reference:

📖 User Guides

Practical workflows and how-tos:

🏗️ Architecture

Deep dive into the codebase:

🛠️ Development

Extend and customize:

📚 Reference

Quick lookups and troubleshooting:

Common Tasks

Train a Model

ml-train --config configs/my_dataset_config.yaml --batch_size 32 --lr 0.01 --num_epochs 50
See: Training Guide

Resume Training

ml-train --config configs/my_dataset_config.yaml --resume runs/hymenoptera_base_fold_0/last.pt
See: Resuming Training

Run Inference

# Standard inference
ml-inference --checkpoint_path runs/hymenoptera_base_fold_0/weights/best.pt

# TTA for improved accuracy
ml-inference --checkpoint_path runs/hymenoptera_base_fold_0/weights/best.pt --tta

# Ensemble multiple models
ml-inference --ensemble \
  runs/fold_0/weights/best.pt \
  runs/fold_1/weights/best.pt \
  runs/fold_2/weights/best.pt
See: Inference Guide, TTA Guide, Ensemble Guide

Monitor Training

tensorboard --logdir runs/
# Or use ml-visualise
ml-visualise --mode launch --run_dir runs/hymenoptera_base_fold_0
See: Monitoring Guide

Visualize Dataset

ml-visualise --mode samples --run_dir runs/hymenoptera_base_fold_0 --split train
See: Monitoring Guide

Visualize Predictions

ml-visualise --mode predictions --run_dir runs/hymenoptera_base_fold_0 --split val
See: Visualization Reference

Change Model

# In ml_src/config_template.yaml
model:
  architecture: 'efficientnet_b0'
See: Model Configuration

Documentation Navigation Tips

  1. New users: Start with Getting Started
  2. Quick reference: Check Configuration
  3. Workflows: See User Guides
  4. Understanding code: Read Architecture
  5. Customization: Explore Development
  6. Problems: Visit Troubleshooting

Key Concepts

Configuration System

YAML-based with CLI overrides: 

ml-train --config custom.yaml --lr 0.01
Learn more →

Data Organization

Mandatory structure: 

data/your_dataset/
├── raw/                    # All images organized by class
│   ├── class1/
│   ├── class2/
│   └── classN/
└── splits/                 # Generated by ml-split
    ├── test.txt
    ├── fold_0_train.txt
    ├── fold_0_val.txt
    └── ...
Index-based cross-validation: No data duplication - all images stored once in raw/, referenced by .txt index files.

Learn more →

Checkpointing

Two checkpoints per run: - best.pt - Highest validation accuracy (for deployment) - last.pt - Latest epoch (for resuming)

Learn more →

Run Organization

Automatic directory naming based on dataset, fold, and hyperparameters: 

runs/
├── hymenoptera_base_fold_0/
├── hymenoptera_batch_32_lr_0.01_fold_0/
└── my_dataset_epochs_50_lr_0.001_fold_1/
Learn more →

Support

Contributing to Documentation

Found an issue or want to improve the docs?

  1. Documentation source: /docs/ directory
  2. Each section has its own folder
  3. Written in Markdown
  4. Feel free to submit improvements!

Happy training! 🚀

Start with the Quick Start Guide →