datatunner 3.1.0

DataTunner: Scientific Platform for Optimal Artificial Data Proportion in Deep Learning

DataTunner

Scientific Platform for Optimal Artificial Data Proportion in Deep Learning

DataTunner is a rigorous, reproducible experimentation platform designed to determine the optimal proportion (α*) of artificial data — including augmentation, SMOTE, and CTGAN — in hybrid datasets for neural network training.

Philosophy

Unlike conventional AutoML tools that treat data proportion as a hyperparameter to be guessed, DataTunner elevates it to a scientific variable with full provenance, statistical fidelity assessment, and isolated experimental environments.

Architecture

datatunner/
├── domain/          # Immutable domain objects
├── generators/      # Abstract generator hierarchy (Augmentation, SMOTE, CTGAN)
├── mixing/          # Isolated mixing engine with leakage detection
├── training/        # Isolated training environments (GPU/seed control)
├── evaluation/      # Quality (fidelity) + Performance (model metrics)
├── optimization/    # Search strategies (Grid, Random, Bayesian)
├── reporting/       # Publication-ready tables and plots
└── infrastructure/  # Seeds, hardware, logging, persistence

Quick Start

import pandas as pd
from sklearn.datasets import make_classification
from sklearn.model_selection import train_test_split
import torch
import torch.nn as nn
from sklearn.metrics import f1_score

from datatunner import DataTunner, ExperimentConfig
from datatunner.domain.generator import GeneratorSpec
from datatunner.generators.smote import SMOTEGenerator
from datatunner.optimization.grid import GridSearch
from datatunner.reporting.exporters import HTMLExporter, LaTeXExporter


# 1. Prepare real data
X, y = make_classification(n_samples=2000, n_features=10, n_classes=2,
                           weights=[0.75, 0.25], random_state=42)
df = pd.DataFrame(X, columns=[f'f{i}' for i in range(10)])
df['target'] = y
train_df, test_df = train_test_split(df, test_size=0.2, random_state=42, stratify=df['target'])


# 2. Define model, train, and evaluate functions
def build_mlp():
    return nn.Sequential(nn.Linear(10, 64), nn.ReLU(),
                         nn.Linear(64, 32), nn.ReLU(), nn.Linear(32, 2))


def train_fn(model, train_data, hyperparams):
    from torch.utils.data import DataLoader, TensorDataset
    X = train_data.drop('target', axis=1).values
    y = train_data['target'].values
    ds = TensorDataset(torch.FloatTensor(X), torch.LongTensor(y))
    loader = DataLoader(ds, batch_size=64, shuffle=True)
    opt = torch.optim.Adam(model.parameters(), lr=1e-3)
    crit = nn.CrossEntropyLoss()
    model.train()
    for _ in range(hyperparams.get('epochs', 20)):
        for bx, by in loader:
            opt.zero_grad()
            loss = crit(model(bx), by)
            loss.backward()
            opt.step()
    return model


def evaluate_fn(model, test_data):
    from datatunner.domain.metrics import ClassificationMetrics
    X = test_data.drop('target', axis=1).values
    y_true = test_data['target'].values
    model.eval()
    with torch.no_grad():
        y_pred = torch.argmax(model(torch.FloatTensor(X)), dim=1).numpy()
    return ClassificationMetrics(f1_macro=f1_score(y_true, y_pred, average='macro'))


# 3. Configure and run experiment
config = ExperimentConfig(
    data_type='tabular',
    search_strategy=GridSearch(),
    alpha_bounds=(0.0, 1.0),
    n_repetitions=3,
    search_budget=6,
    target_metric='f1_macro',
    hyperparams={'epochs': 20, 'batch_size': 64},
)

spec = GeneratorSpec(name="SMOTE_k5", mechanism="smote",
                     hyperparameters={'target_column': 'target', 'k_neighbors': 5},
                     random_state=42)

tunner = DataTunner(config)
report = tunner.run(
    real_data=train_df,
    test_data=test_df,
    model_fn=build_mlp,
    generator=SMOTEGenerator(spec),
    train_fn=train_fn,
    evaluate_fn=evaluate_fn,
)

# 4. Export results
HTMLExporter().export(report, "report.html")
LaTeXExporter().export_tables(report, "./latex_output")

Citation

@software{datatunner2026,
  author = {Rocha, Leandro Costa},
  title = {DataTunner: Optimal Artificial Data Proportion for Deep Learning},
  year = {2026},
  url = {https://github.com/leandrocrx/datatunner}
}