Metadata-Version: 2.4
Name: mixup
Version: 0.1.0
Summary: A unified PyTorch library for SOTA MixUp augmentations.
Home-page: https://github.com/your_username/mixupentations
Author: Andrey Katasonov
Author-email: andre.katasonov@gmail.com
Project-URL: Source, https://github.com/your_username/mixupentations
Keywords: mixup cutmix resizemix fmix augmentations computer vision pytorch deep learning
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: torch>=1.10.0
Requires-Dist: numpy>=1.21.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# mixupentations

[![PyPI version](https://badge.fury.io/py/mixupentations.svg)](https://badge.fury.io/py/mixupentations)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)

A unified PyTorch library for SOTA MixUp augmentations. It keeps popular image and label mixing methods in one place, making it extremely convenient for rapid experiments and training robust classification models.

## Features

- **VanillaMixUp** — Classic linear mixing of two images and their labels.
- **CutMix** — Replaces a rectangular region of an image with a patch from another image.
- **ResizeMix** — Overlays a rescaled patch from another image.
- **FMix** — Blends images using a low-frequency noise mask generated via FFT.
- **MixupPipeline** — Randomly selects one method from a provided list for multi-mode training strategies.
- Easily extensible architecture via the `BaseMixup` abstract class.

## Installation

Install directly from PyPI:

```bash
pip install mixup

```

Or install in development mode from the source:

```bash
git clone [https://github.com/your_username/mixup.git](https://github.com/your_username/mixupentations.git)
cd mixup
pip install -e .

```

## Quick Start

```python
import torch
import torch.nn.functional as F
from mixup import VanillaMixUp, CutMix, MixupPipeline

# Dummy batch of images [B, C, H, W] and labels [B]
images = torch.randn(8, 3, 224, 224)
labels = torch.randint(0, 10, (8,))

# Convert labels to one-hot encoding for mixing
labels_one_hot = F.one_hot(labels, num_classes=10).float()

# Use a single method
mixup = VanillaMixUp(alpha=1.0, probability=0.5)
mixed_images, mixed_labels = mixup(images, labels_one_hot)

# Or use a multi-mode pipeline
pipeline = MixupPipeline([
    VanillaMixUp(alpha=1.0),
    CutMix(alpha=1.0),
])
mixed_images, mixed_labels = pipeline(images, labels_one_hot)

```

## Available Augmentations

### VanillaMixUp

Standard MixUp: blends two images and their corresponding labels using a mixing coefficient λ sampled from a Beta(α, α) distribution.

```python
from mixup import VanillaMixUp

mixup = VanillaMixUp(alpha=1.0, probability=1.0)

```

### CutMix

Cuts a rectangular region from one image and pastes a patch from another. The λ coefficient is recalculated based on the actual patch area.

```python
from mixup import CutMix

cutmix = CutMix(alpha=1.0, probability=0.5)

```

### ResizeMix

Rescales a partner image and pastes the resulting patch into a random position on the original image.

```python
from mixup.methods import ResizeMix

resizemix = ResizeMix(alpha=1.0)

```

### FMix

Generates a binary mask via the inverse FFT of low-frequency noise and blends images according to this mask.

```python
from mixup.methods import FMix

fmix = FMix(alpha=1.0, decay_power=3.0)

```

## Parameters

All methods inherit from `BaseMixup` and accept the following common arguments:

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `alpha` | float | `1.0` | Hyperparameter for the Beta distribution. If `alpha=0`, λ is set to 1. |
| `probability` | float | `1.0` | The probability (0.0 to 1.0) of applying the augmentation. |

`FMix` accepts an additional parameter:

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `decay_power` | float | `3.0` | The decay power applied in the frequency domain. |

## Integration into Training Loop

PyTorch's native `CrossEntropyLoss` supports soft-labels out of the box (since version 1.10).

```python
import torch.nn as nn
import torch.nn.functional as F
import torch.optim as optim
from mixup import CutMix

model = ...  # Your PyTorch model
criterion = nn.CrossEntropyLoss()
optimizer = optim.Adam(model.parameters())

# Initialize augmentation
cutmix = CutMix(alpha=1.0, probability=0.5)
NUM_CLASSES = 100

model.train()
for images, labels in dataloader:
    images, labels = images.cuda(), labels.cuda()

    # 1. Convert targets to one-hot floats
    labels_one_hot = F.one_hot(labels, num_classes=NUM_CLASSES).float()

    # 2. Apply augmentation
    mixed_images, mixed_labels = cutmix(images, labels_one_hot)

    # 3. Standard forward & backward pass
    optimizer.zero_grad()
    outputs = model(mixed_images)

    loss = criterion(outputs, mixed_labels)
    loss.backward()
    optimizer.step()

```

## References

* [MixUp: Beyond Empirical Risk Minimization](https://arxiv.org/abs/1710.09412)
* [CutMix: Regularization Strategy to Train Strong Classifiers](https://arxiv.org/abs/1905.04899)
* [ResizeMix: Mixing Data with Preserved Object Information](https://arxiv.org/abs/2012.11101)
* [FMix: Enhancing Mixed Sample Data Augmentation](https://arxiv.org/abs/2002.12047)

## License

This project is licensed under the MIT License.

