This repository provides a complete, educational workflow for training image classifiers with differential privacy. From raw CelebA images to balanced subset creation, preprocessing, baseline CNN training, and differentially private training with DP-SGD (via Opacus).

Design Philosophy: Instead of diving straight into opaque training loops, we prioritize clarity over complexity. Each stage is observable, testable, and modifiable — designed as a teaching tool.

The main entry point is notebooks/celeba_eyeglasses_workflow.ipynb

This notebook provides an end-to-end educational workflow where you:

• Analyze the CelebA dataset and create balanced subsets
• Preprocess images with transparent, observable steps
• Train both baseline and DP-SGD models with matched hyperparameters
• Visualize and compare privacy-accuracy trade-offs

Note: All steps are designed for learning. Each stage is observable, testable, and modifiable. Training can also be done programmatically using the modules in src/training/, but the notebook is recommended for understanding the complete workflow.

• Differential Privacy: Full DP-SGD implementation using Opacus
• Educational Focus: Transparent, well-documented code designed for learning
• Matched-Pair Methodology: Identical hyperparameters for baseline and DP-SGD enable direct privacy cost quantification
• Centralized Configuration: YAML-based config system for easy experimentation
• Comprehensive Visualization: Training curves, privacy-utility tradeoffs, and comparisons
• Tested & Reproducible: Full test suite and tracked experiments under runs/
• Automated Workflows: Hyperparameter sweeps for both baseline and DP-SGD

• Python 3.8+
• pip

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -U pip
pip install -e .[dev]

1. Download the CelebA dataset from Kaggle
2. Extract and place the archive under:

   data/celeba/archive/
   

3. The notebook will validate the expected files/structure automatically

The notebook uses a centralized YAML configuration system. Edit notebooks/config.yaml to customize:

• Dataset paths and subset sizes
• Preprocessing parameters
• Training hyperparameters
• Privacy parameters (for DP-SGD)

📖 See notebooks/README_config.md for detailed configuration documentation.

Open and run: notebooks/celeba_eyeglasses_workflow.ipynb

The notebook will:

• Build a balanced Eyeglasses subset (train/val/test)
• Preprocess images (crop/resize/normalize)
• Save dataset statistics needed by loaders

These artifacts are required before running training. We keep this step in-notebook to make the process transparent and learnable.

After preprocessing, you can train models by:

• Continuing in notebooks/celeba_eyeglasses_workflow.ipynb
• The notebook includes training cells for both baseline and DP-SGD models
• Uses matched hyperparameters for fair privacy-accuracy comparison
• Includes visualization cells for analyzing results

dp_sgd_classification/
├── data/                    # Dataset storage (CelebA archive, subsets, processed images)
│   └── celeba/
│       ├── archive/         # Raw CelebA dataset
│       ├── subsets/         # Balanced subsets
│       └── processed/       # Preprocessed images
├── notebooks/               # Main workflow notebook, configs, and utilities
│   ├── celeba_eyeglasses_workflow.ipynb  # Primary entry point
│   ├── config.yaml          # Centralized configuration
│   └── README_config.md     # Configuration guide
├── scripts/                 # Standalone CLI scripts for data processing
│   ├── celeba_analyze.py
│   ├── celeba_build_subset.py
│   ├── celeba_preprocess.py
│   └── celeba_centering.py
├── src/                     # Core Python package
│   ├── config/              # Configuration management
│   ├── core/                # Core ML components (models, data loaders, utils)
│   ├── datasets/            # Dataset-specific code (CelebA workflow, analysis)
│   ├── notebooks/           # Notebook utilities (display, setup, helpers)
│   ├── training/            # Training loops, sweeps, visualization
│   └── visualization/       # Plotting utilities
├── tests/                   # Test suite
└── runs/                    # Training run outputs (configs, checkpoints, metrics)

pytest -q

pytest tests/test_data.py
pytest tests/test_train_baseline.py
pytest tests/test_train_dp.py