Metadata-Version: 2.4
Name: datatunner
Version: 3.0.0
Summary: DataTunner: Scientific Platform for Optimal Artificial Data Proportion in Deep Learning
Author-email: Leandro Costa Rocha <leandrocrx@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/leandrocrx/datatunner
Project-URL: Repository, https://github.com/leandrocrx/datatunner
Project-URL: Issues, https://github.com/leandrocrx/datatunner/issues
Keywords: machine learning,deep learning,synthetic data,data augmentation,neural networks,smote,ctgan,optimal proportion,reproducible experiments
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: seaborn>=0.11.0
Requires-Dist: imbalanced-learn>=0.10.0
Requires-Dist: torch>=1.12.0
Requires-Dist: torchvision>=0.13.0
Requires-Dist: sdv>=1.2.0
Requires-Dist: sdmetrics>=0.12.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: tqdm>=4.62.0
Requires-Dist: jinja2>=3.0.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Requires-Dist: mypy>=0.950; extra == "dev"
Dynamic: license-file

# 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

```python
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

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