Skip to main content

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 every bf epochs).

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)

Source distribution for art-resampling 0.1.2
File Size Uploaded
art_resampling-0.1.2.tar.gz 17.8 kB Details

Built distribution (wheel)

Table of built distributions (wheels) for art-resampling 0.1.2
File Interpreter ABI Platform
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

Release history Release notifications | RSS feed

This release

0.1.2 This release

2 release files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page