Deep Learning › Convolutional Networks and Vision › Day 214
Hands-on lab — Day 214: Data Augmentation
- ← Back to the Day 214 lesson
- Open the hands-on files on GitHub — clone or download them from the public labs repository
- Local path in your clone:
labs/sections/deep-learning/day-214-data-augmentation/
Commands
Setup
pip install -r requirements/requirements.txt Run
python3 examples/data_augmentation_lib.py Test
./tests/run_tests.sh File tree
conftest.py examples/data_augmentation_lib.py examples/test_data_augmentation_lib.py expected-output/examples-run.txt expected-output/FIELDS.md expected-output/measured-values.txt expected-output/starter-run.txt expected-output/test-run.txt metadata.yml README.md requirements/requirements.txt security.md starter/data_augmentation_lib.py starter/test_data_augmentation_lib.py tests/run_tests.sh tests/test_data_augmentation_lib.py troubleshooting.md
Lab README
Lab: Day 214 -- Data Augmentation
Lesson
Day number: 214 of 365. Course: Course05-SS01 (Deep Learning - Neural Networks). Topic: Data Augmentation in Computer Vision.
Purpose
Build and test a modern Computer Vision Data Augmentation library in PyTorch. Implement mathematical algorithms for MixUp convex linear blending and CutMix spatial patch masking from first principles, verify label interpolation properties, and construct stochastic training transform pipelines.
Learning objectives
- Implement MixUp convex interpolation across image tensors and one-hot target vectors.
- Implement CutMix bounding box patch generation and exact area proportion calculation.
- Construct stochastic training vs deterministic validation transform pipelines.
- Verify label probability conservation and manifold smoothing.
Prerequisites
- Day 213 (Transfer Learning).
- Python 3.11+ with PyTorch and torchvision.
Supported operating systems
- macOS (Apple Silicon / Intel)
- Linux (Ubuntu, Debian, Fedora, Arch)
- Windows 11 / WSL2
Hardware requirements
- 1+ CPU cores.
- 1 GB RAM.
- 100 MB disk space.
Required software
- Python 3.11 or newer.
- pip package manager.
- virtualenv or venv module.
Free and open-source options
PyTorch and torchvision are free and open-source under modified BSD licenses.
Installation
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements/requirements.txt
File structure
starter/data_augmentation_lib.py: Student scaffold file.examples/data_augmentation_lib.py: Complete reference implementation.tests/test_data_augmentation_lib.py: Pytest automated validation suite.expected-output/: Verified output logs and baseline values.
How to run
Execute the reference demonstration script:
python3 examples/data_augmentation_lib.py
What the commands do
- Applies MixUp and CutMix algorithms across synthetic image batches.
- Computes soft probability label distributions.
- Validates tensor shapes and target conservation.
Expected output
Augmentation Demo: MixUp Shape = torch.Size([4, 3, 32, 32]), CutMix Shape = torch.Size([4, 3, 32, 32])
Validation steps
- Confirm that
apply_mixupproduces soft probability rows summing to 1.0. - Confirm that
apply_cutmixcomputes actual area ratios accurately. - Ensure all unit test assertions pass.
Tests
Run the test runner script:
./tests/run_tests.sh
Cleanup
find . -type d -name "__pycache__" -exec rm -rf {} +
find . -type d -name ".pytest_cache" -exec rm -rf {} +
Troubleshooting
- Dimensions Error in CutMix: Verify
rand_bboxclips coordinates within[0, W]and[0, H].
Security notes
All augmentations execute locally in CPU/GPU memory without external network calls.
Extension exercises
- Implement Test-Time Augmentation (TTA) averaging across multiple augmented test copies.
- Implement Mosaic 4-image grid augmentation.
Navigation
- Lesson title: Data Augmentation
- Day number: 214 of 365
- Lesson article: https://ai-roadmap-365.github.io/day-214-data-augmentation
- Lab files: everything you need is in this directory — follow “How to run” below.
- Browse the course locally: from the repository root, this lab also appears in the course website at
/labs/day-214-data-augmentationwhen the site is running.
Expected output
FIELDS.md
# Expected Output Fields: Day 214
- `MixUp Shape`: Output tensor dimensions after MixUp augmentation.
- `CutMix Shape`: Output tensor dimensions after CutMix augmentation.
examples-run.txt
Augmentation Demo: MixUp Shape = torch.Size([4, 3, 32, 32]), CutMix Shape = torch.Size([4, 3, 32, 32])
measured-values.txt
MixUp Shape: torch.Size([4, 3, 32, 32])
CutMix Shape: torch.Size([4, 3, 32, 32])
starter-run.txt
Starter scaffold executed. Ready for student implementation.
test-run.txt
============================= test session starts ==============================
collected 2 items
tests/test_data_augmentation_lib.py::test_mixup_convex_combination PASSED [ 50%]
tests/test_data_augmentation_lib.py::test_cutmix_bounding_box_patch PASSED [100%]
============================== 2 passed in 0.31s ===============================
Source files
conftest.py (585 bytes)
"""Make this lab importable when the suite runs.
pytest puts the test file's own directory on sys.path, not the lab root, so a
test that does `from examples.<module> import ...` -- or imports a module that
lives in examples/ directly -- fails without this. Putting it here rather than
in run_tests.sh means a bare `pytest` from the lab root works too.
"""
import os
import sys
LAB = os.path.dirname(os.path.abspath(__file__))
for candidate in (LAB, os.path.join(LAB, "examples")):
if os.path.isdir(candidate) and candidate not in sys.path:
sys.path.insert(0, candidate)
examples/data_augmentation_lib.py (2086 bytes)
import torch
import numpy as np
from typing import Tuple, Dict, Any
def apply_mixup(x: torch.Tensor, y_one_hot: torch.Tensor, alpha: float = 0.2) -> Tuple[torch.Tensor, torch.Tensor]:
batch_size = x.size(0)
if alpha > 0:
lam = float(np.random.beta(alpha, alpha))
else:
lam = 1.0
index = torch.randperm(batch_size)
mixed_x = lam * x + (1 - lam) * x[index]
mixed_y = lam * y_one_hot + (1 - lam) * y_one_hot[index]
return mixed_x, mixed_y
def rand_bbox(size, lam):
W = size[2]
H = size[3]
cut_rat = np.sqrt(1.0 - lam)
cut_w = int(W * cut_rat)
cut_h = int(H * cut_rat)
cx = np.random.randint(W)
cy = np.random.randint(H)
bbx1 = np.clip(cx - cut_w // 2, 0, W)
bby1 = np.clip(cy - cut_h // 2, 0, H)
bbx2 = np.clip(cx + cut_w // 2, 0, W)
bby2 = np.clip(cy + cut_h // 2, 0, H)
return bbx1, bby1, bbx2, bby2
def apply_cutmix(x: torch.Tensor, y_one_hot: torch.Tensor, alpha: float = 1.0) -> Tuple[torch.Tensor, torch.Tensor]:
batch_size = x.size(0)
if alpha > 0:
lam = float(np.random.beta(alpha, alpha))
else:
lam = 1.0
index = torch.randperm(batch_size)
bbx1, bby1, bbx2, bby2 = rand_bbox(x.size(), lam)
mixed_x = x.clone()
mixed_x[:, :, bbx1:bbx2, bby1:bby2] = x[index, :, bbx1:bbx2, bby1:bby2]
# Adjust lambda to exact area ratio
actual_lam = 1.0 - ((bbx2 - bbx1) * (bby2 - bby1) / (x.size(2) * x.size(3)))
mixed_y = actual_lam * y_one_hot + (1.0 - actual_lam) * y_one_hot[index]
return mixed_x, mixed_y
def run_augmentation_demo():
torch.manual_seed(42)
np.random.seed(42)
x = torch.randn(4, 3, 32, 32)
y_idx = torch.tensor([0, 1, 2, 3])
y_one_hot = torch.nn.functional.one_hot(y_idx, num_classes=4).float()
x_mix, y_mix = apply_mixup(x, y_one_hot, alpha=0.2)
x_cut, y_cut = apply_cutmix(x, y_one_hot, alpha=1.0)
print(f"Augmentation Demo: MixUp Shape = {x_mix.shape}, CutMix Shape = {x_cut.shape}")
return x_mix.shape, x_cut.shape
if __name__ == "__main__":
run_augmentation_demo()
examples/test_data_augmentation_lib.py (834 bytes)
import pytest
import torch
from examples.data_augmentation_lib import apply_mixup, apply_cutmix
def test_mixup_convex_combination():
x = torch.ones(4, 3, 16, 16)
y_one_hot = torch.eye(4)
x_mix, y_mix = apply_mixup(x, y_one_hot, alpha=0.5)
assert x_mix.shape == (4, 3, 16, 16)
assert y_mix.shape == (4, 4)
# Every row in y_mix must sum to 1.0
for row in y_mix:
assert torch.isclose(torch.sum(row), torch.tensor(1.0), atol=1e-5)
def test_cutmix_bounding_box_patch():
x = torch.zeros(4, 3, 16, 16)
x[0] = 1.0 # Sample 0 is all 1s
y_one_hot = torch.eye(4)
x_cut, y_cut = apply_cutmix(x, y_one_hot, alpha=1.0)
assert x_cut.shape == (4, 3, 16, 16)
assert y_cut.shape == (4, 4)
for row in y_cut:
assert torch.isclose(torch.sum(row), torch.tensor(1.0), atol=1e-5)
metadata.yml (430 bytes)
lesson_id: D214
day: 214
kind: lab
languages:
- python
setup_commands:
- 'pip install -r requirements/requirements.txt'
run_commands:
- 'python3 examples/data_augmentation_lib.py'
test_commands:
- './tests/run_tests.sh'
cleanup_commands:
- 'find . -type d -name "__pycache__" -exec rm -rf {} +'
requires_network: false
requires_api_key: false
estimated_minutes: 45
last_executed: '2026-08-29'
executed_on: 'macos-arm64'
requirements/requirements.txt (61 bytes)
torch>=2.2.0
torchvision>=0.17.0
numpy>=1.26.0
pytest>=8.0.0
starter/data_augmentation_lib.py (460 bytes)
import torch
import numpy as np
from typing import Tuple, Dict, Any
def apply_mixup(x: torch.Tensor, y: torch.Tensor, alpha: float = 0.2) -> Tuple[torch.Tensor, torch.Tensor]:
# TODO: Implement MixUp convex linear interpolation for images and labels
pass
def apply_cutmix(x: torch.Tensor, y: torch.Tensor, alpha: float = 1.0) -> Tuple[torch.Tensor, torch.Tensor]:
# TODO: Implement CutMix spatial patch masking and area-weighted targets
pass
starter/test_data_augmentation_lib.py (834 bytes)
import pytest
import torch
from examples.data_augmentation_lib import apply_mixup, apply_cutmix
def test_mixup_convex_combination():
x = torch.ones(4, 3, 16, 16)
y_one_hot = torch.eye(4)
x_mix, y_mix = apply_mixup(x, y_one_hot, alpha=0.5)
assert x_mix.shape == (4, 3, 16, 16)
assert y_mix.shape == (4, 4)
# Every row in y_mix must sum to 1.0
for row in y_mix:
assert torch.isclose(torch.sum(row), torch.tensor(1.0), atol=1e-5)
def test_cutmix_bounding_box_patch():
x = torch.zeros(4, 3, 16, 16)
x[0] = 1.0 # Sample 0 is all 1s
y_one_hot = torch.eye(4)
x_cut, y_cut = apply_cutmix(x, y_one_hot, alpha=1.0)
assert x_cut.shape == (4, 3, 16, 16)
assert y_cut.shape == (4, 4)
for row in y_cut:
assert torch.isclose(torch.sum(row), torch.tensor(1.0), atol=1e-5)
tests/run_tests.sh (227 bytes)
#!/usr/bin/env bash
set -euo pipefail
echo "========================================"
echo "Running Day 214 Lab Test Suite"
echo "========================================"
pytest tests/ -v
echo "All tests passed successfully."
tests/test_data_augmentation_lib.py (834 bytes)
import pytest
import torch
from examples.data_augmentation_lib import apply_mixup, apply_cutmix
def test_mixup_convex_combination():
x = torch.ones(4, 3, 16, 16)
y_one_hot = torch.eye(4)
x_mix, y_mix = apply_mixup(x, y_one_hot, alpha=0.5)
assert x_mix.shape == (4, 3, 16, 16)
assert y_mix.shape == (4, 4)
# Every row in y_mix must sum to 1.0
for row in y_mix:
assert torch.isclose(torch.sum(row), torch.tensor(1.0), atol=1e-5)
def test_cutmix_bounding_box_patch():
x = torch.zeros(4, 3, 16, 16)
x[0] = 1.0 # Sample 0 is all 1s
y_one_hot = torch.eye(4)
x_cut, y_cut = apply_cutmix(x, y_one_hot, alpha=1.0)
assert x_cut.shape == (4, 3, 16, 16)
assert y_cut.shape == (4, 4)
for row in y_cut:
assert torch.isclose(torch.sum(row), torch.tensor(1.0), atol=1e-5)
Troubleshooting
Troubleshooting: Day 214 - Data Augmentation
Common Issues
- Target loss NaN with MixUp:
- Cause: Passing scalar integer labels to CrossEntropyLoss with soft target vectors.
- Fix: Use soft target CrossEntropyLoss or
torch.sum(-target * log_softmax(logits)).
Security notes
Security & Privacy: Day 214 - Data Augmentation
Security Guidance
- All pixel augmentations execute in local memory without logging image data.