datatunner 0.1.0

Ferramenta para determinar a proporção ideal de dados sintéticos em modelos de ML

🎯 DataTunner

Otimização Automática de Proporções de Dados Sintéticos para Modelos de Deep Learning

📖 Sobre

DataTunner é uma ferramenta Python de código aberto que automatiza o processo de determinação da proporção ideal de dados sintéticos para maximizar a performance de modelos de redes neurais.

A crescente demanda por grandes volumes de dados para treinamento de modelos de Deep Learning tem impulsionado o uso de dados sintéticos como solução para escassez e desbalanceamento de datasets. O DataTunner sistematiza esse processo, que tradicionalmente é empírico e não estruturado.

✨ Características Principais

• 🔄 Geração Automática de Datasets Híbridos: Combina dados reais e sintéticos em diferentes proporções
• 🖼️ Suporte a Imagens: CNNs (ResNet, VGG, MobileNet) com data augmentation
• 📊 Suporte a Dados Tabulares: MLPs, Random Forest, XGBoost com SMOTE e CTGAN
• 📈 Métricas Abrangentes: Accuracy, Precision, Recall, F1-Score, ROC-AUC
• 🎨 Visualizações Ricas: Gráficos interativos e relatórios detalhados
• 🔬 Reprodutibilidade Garantida: Seeds fixas e hiperparâmetros controlados
• ⚡ Suporte a GPU: Aceleração via CUDA
• 💾 Checkpointing: Retome experimentos interrompidos

🚀 Instalação

Instalação Básica

pip install datatunner

Instalação para Desenvolvimento

git clone https://github.com/leandro-rocha/datatunner.git
cd datatunner
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -e ".[dev]"

📚 Guia Rápido

Exemplo com Imagens (CIFAR-10)

from datatunner import DataTunner
from datatunner.models.cnn import ResNetClassifier
from datatunner.generators.augmentation import ImageAugmentation

# Configurar o otimizador
tunner = DataTunner(
    data_type='image',
    real_data_path='data/cifar10/real',
    synthetic_data_path='data/cifar10/synthetic',
    output_dir='results/cifar10'
)

# Definir modelo
model = ResNetClassifier(num_classes=10, architecture='resnet18')

# Executar otimização
results = tunner.optimize(
    model=model,
    proportions=[0.0, 0.1, 0.2, 0.3, 0.5, 0.7, 1.0],
    epochs=50,
    batch_size=64,
    n_trials=3  # Repetições para robustez
)

# Visualizar resultados
tunner.plot_results()
print(f"Melhor proporção: {results['best_proportion']}")

Exemplo com Dados Tabulares

from datatunner import DataTunner
from datatunner.models.mlp import MLPClassifier
from datatunner.generators.smote import SMOTEGenerator

# Configurar o otimizador
tunner = DataTunner(
    data_type='tabular',
    real_data_path='data/adult/train.csv',
    test_data_path='data/adult/test.csv',
    output_dir='results/adult'
)

# Gerar dados sintéticos com SMOTE
generator = SMOTEGenerator(k_neighbors=5)
synthetic_data = generator.generate(data=tunner.real_data, n_samples=5000)

# Definir modelo
model = MLPClassifier(hidden_layers=[128, 64, 32], dropout=0.3)

# Executar otimização
results = tunner.optimize(
    model=model,
    synthetic_data=synthetic_data,
    proportions=[0.0, 0.1, 0.2, 0.3, 0.5, 0.7, 1.0],
    epochs=100,
    batch_size=128
)

# Relatório detalhado
tunner.generate_report(format='html')

📊 Metodologia

Para Datasets de Imagem

1. Entrada: Imagens reais + imagens sintéticas (augmentation, GANs, difusão)
2. Mistura: Combinação em proporções variadas com balanceamento de classes
3. Treinamento: CNNs (ResNet, VGG, MobileNet) com hiperparâmetros fixos
4. Avaliação: Métricas em conjunto de teste independente

Para Datasets Tabulares

1. Entrada: Dados tabulares reais + sintéticos (SMOTE, CTGAN)
2. Mistura: Preservação de distribuições e correlações
3. Treinamento: MLPs, Random Forest, XGBoost, LightGBM
4. Avaliação: Métricas específicas para desbalanceamento

🏗️ Arquitetura

datatunner/
├── core/           # Motor de otimização e avaliação
├── generators/     # Geradores de dados sintéticos
├── models/         # Modelos de ML/DL
├── utils/          # Utilitários e visualização
└── config/         # Configurações

🧪 Testes

pytest tests/ -v --cov=datatunner

📖 Documentação

Documentação completa disponível em: https://datatunner.readthedocs.io

🤝 Contribuindo

Contribuições são bem-vindas! Por favor, leia nosso guia de contribuição.

📄 Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

📚 Citação

Se você usar o DataTunner em sua pesquisa, por favor cite:

@software{datatunner2026,
  author = {Rocha, Leandro},
  title = {DataTunner: Otimização de Proporções de Dados Sintéticos},
  year = {2026},
  url = {https://github.com/leandro-rocha/datatunner}
}

👥 Autores

• Leandro Rocha - Desenvolvedor Principal - @leandrocr.adv

🙏 Agradecimentos

Baseado na pesquisa sobre otimização de dados sintéticos para modelos de Deep Learning.

---

Desenvolvido com ❤️ para a comunidade de Data Science