Deep Learning › Convolutional Networks and Vision › Day 214

Hands-on lab — 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

  1. Confirm that apply_mixup produces soft probability rows summing to 1.0.
  2. Confirm that apply_cutmix computes actual area ratios accurately.
  3. 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_bbox clips coordinates within [0, W] and [0, H].

Security notes

All augmentations execute locally in CPU/GPU memory without external network calls.

Extension exercises

  1. Implement Test-Time Augmentation (TTA) averaging across multiple augmented test copies.
  2. Implement Mosaic 4-image grid augmentation.
  • 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-augmentation when 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

  1. 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.