art-resampling
art-resampling is a PyTorch utility for Adaptive Resampling-Based Training for Imbalanced Datasets (ART).
This repository contains the reference implementation used in the paper: Adaptive Resampling for Imbalanced Datasets (ART)
Install
pip install art-resampling
Quick start
Run the example script:
python examples/tabular_multiclass.py
Library API
ARTDataset
A PyTorch Dataset that can act as:
- a normal dataset (
enable_art=False), or - an ART-resampled dataset (
enable_art=True).
from art_resampling import ARTDataset
train_dataset = ARTDataset(
X_train,
y_train,
enable_art=True,
c=0.3,
cls_weights=initial_class_weights,
seed=5529,
)
val_dataset = ARTDataset(X_val, y_val, enable_art=False)
Refresh helpers
Refresh using validation predictions
from art_resampling import art_refresh_dataset_from_predictions
train_loader, class_weights, per_class_f1 = art_refresh_dataset_from_predictions(
art_dataset=train_dataset,
y_true=val_true,
y_pred=val_pred,
n_classes=num_classes,
train_loader_kwargs={"batch_size": 256, "shuffle": True, "drop_last": True},
)
Refresh using precomputed per-class F1
from art_resampling import art_refresh_dataset_from_f1_scores
train_loader, class_weights, per_class_f1 = art_refresh_dataset_from_f1_scores(
art_dataset=train_dataset,
f1=per_class_f1,
train_loader_kwargs={"batch_size": 256, "shuffle": True, "drop_last": True},
)
Weight and metric utilities
import numpy as np
from art_resampling import per_class_f1, art_weights_from_f1
val_true = np.array([0, 0, 0, 1, 1, 2, 2, 2])
val_pred = np.array([0, 0, 1, 1, 2, 0, 2, 2])
f1 = per_class_f1(val_true, val_pred, n_classes=3)
weights = art_weights_from_f1(f1)
print("per_class_f1:", np.round(f1, 4))
print("class_weights:", np.round(weights, 4))
print("sum:", float(weights.sum()))
Smoke test
pytest -q
Notes
- This library focuses on the ART resampling logic only.
- The example uses a synthetic tabular dataset for a complete end-to-end demonstration.
Minimal PyTorch training loop with ART
You choose two key ART parameters:
c: fraction of each refreshed training set drawn uniformly from all samples (the "balanced" portion).bf: refresh frequency in epochs (refresh everybfepochs).
A typical training loop looks like:
from torch.utils.data import DataLoader
from art_resampling import ARTDataset, art_refresh_dataset_from_predictions
c = 0.3
bf = 4
initial_class_weights = [1 / num_classes] * num_classes
train_dataset = ARTDataset(X_train, y_train, enable_art=True, c=c, cls_weights=initial_class_weights, seed=seed)
val_dataset = ARTDataset(X_val, y_val, enable_art=False)
train_loader_kwargs = {"batch_size": 256, "shuffle": True, "drop_last": True}
val_loader_kwargs = {"batch_size": 512, "shuffle": False, "drop_last": False}
train_loader = DataLoader(train_dataset, **train_loader_kwargs)
val_loader = DataLoader(val_dataset, **val_loader_kwargs)
for epoch in range(1, epochs + 1):
train_one_epoch(model, train_loader, optimizer, loss_fn)
if epoch % bf == 0:
val_true, val_pred = predict_labels(model, val_loader)
train_loader, class_weights, per_class_f1 = art_refresh_dataset_from_predictions(
art_dataset=train_dataset,
y_true=val_true,
y_pred=val_pred,
n_classes=num_classes,
train_loader_kwargs=train_loader_kwargs,
)
Support
If you find a bug, please open a GitHub Issue with:
- a minimal code snippet to reproduce
- your Python / PyTorch / numpy versions
- the exact error message or unexpected behavior
For questions about how to integrate ART into a specific training loop, include a small sketch of your dataloader and evaluation step.
Release files for art-resampling 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| art_resampling-0.1.2.tar.gz | 17.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| art_resampling-0.1.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 36.9 kB
Release files / art_resampling-0.1.2.tar.gz
| Download URL | art_resampling-0.1.2.tar.gz |
|---|---|
| Size | 17.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c977c09b4ed670629656742ebb4714b8004fa1d28173dc302cd85e0d44177606
|
|
BLAKE2b-256 checksum How to use checksums |
63e1a0b46c8cde69f3fdfeb59c8982080c5582cbd84949dc0a22b73512d0af7a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.4
|
Release files / art_resampling-0.1.2-py3-none-any.whl
| Download URL | art_resampling-0.1.2-py3-none-any.whl |
|---|---|
| Size | 19.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ff76d9722b1b60f82d91bd1e37f7cab2a60d5310ef0c51fe5f507d7cadd3cf35
|
|
BLAKE2b-256 checksum How to use checksums |
0741f6e06d077ec26e80df1443d9e11979a93478237f2699185e5f88e303427d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.4
|