DataKhanon

Biblioteca de Ciência de Dados com API simples por fora e engenharia científica rigorosa por dentro.

Faça análise exploratória, corrija os dados, treine, avalie e exporte um modelo em poucos comandos — sem cair nas armadilhas científicas mais comuns (vazamento de dados, métricas enganosas para dados desbalanceados, etc.). Funciona bem em scripts, Jupyter e Google Colab.

Instalação

pip install datakhanon

Extras opcionais (não são necessários para o uso básico):

pip install "datakhanon[viz,explainer]"

Quickstart — 1 comando

import datakhanon as dk

res = dk.run("dados.csv", target="classe")   # inspeciona → processa → treina → avalia → salva
print(res.metrics)                            # métricas no holdout (SEM vazamento)
res.save("outputs/exp1")                      # run completo em disco
res.export("modelo.joblib")                   # modelo pronto p/ deploy

dk.run faz, na ordem cientificamente correta:

1. inspeciona o dataset (nulos, duplicatas, outliers, balanceamento do alvo);
2. separa treino/holdout ANTES de qualquer transformação;
3. pré-processa (limpeza, imputação, encoding, scaling, seleção de features) reajustando tudo dentro dos folds da validação cruzada;
4. treina e seleciona o melhor modelo (ou um ensemble);
5. avalia no holdout com métricas apropriadas;
6. salva modelo, schema, métricas e relatório.

A coluna alvo nunca entra nas features e o preprocessing nunca "vê" o conjunto de teste — as duas causas clássicas de métricas infladas.

Fluxo interativo (Jupyter / Colab)

Para analisar, corrigir e olhar os dados antes de treinar, use Dataset:

import datakhanon as dk

ds = dk.Dataset("dados.csv", target="classe")

# 1) Avaliar o dataset ANTES de mexer
ds.inspect()            # resumo + alertas (missing, duplicatas, outliers, desbalanceamento)
ds.head()               # olhar algumas linhas
ds.plot_missing()       # gráficos matplotlib (renderizam inline no notebook)
ds.plot_correlation()
ds.plot_target()

# 2) Ver e corrigir outliers
ds.outliers()               # onde estão (por coluna, IQR ou z-score)
ds.fix_outliers("clip")     # winsoriza; ou "remove" / "nan"
ds.clean(drop_dupes=True)   # remove duplicatas

# 3) Treinar (escolhendo o modo)
res = ds.run(models="best")        # melhor modelo por CV
# res = ds.run(models="ensemble")  # combina os melhores num Voting
# res = ds.run(models="rf")        # um modelo específico

# 4) Resultado estruturado
res.metrics            # dict de métricas
res.best_model_name
res.features           # features efetivamente usadas
res.plot()             # matriz de confusão (classif.) ou previsto-vs-real (regressão)

# 5) Salvar e exportar
res.save("outputs/exp1")
res.export("outputs/modelo.joblib")

Escolhendo o modelo

models= aceita:

• "auto" / "best" — testa candidatos por validação cruzada e escolhe o melhor;
• "ensemble" — combina os melhores candidatos num VotingClassifier/VotingRegressor;
• o nome de um candidato — "logistic", "rf", "gb", "dt" (classificação); "linear", "rf_reg", "gb_reg", "dt_reg", "svr" (regressão);
• um estimador do scikit-learn já configurado (ex.: RandomForestClassifier(...)).

A tarefa (classificação binária/multiclasse ou regressão) é detectada automaticamente a partir do alvo.

Métricas

Nunca dependa só de accuracy. Para classificação, res.metrics traz accuracy, balanced_accuracy, precision, recall, f1, mcc, e — quando há probabilidades — roc_auc, average_precision (PR-AUC) e log_loss. Para regressão: mse, rmse, mae, median_ae, r2 e mape (protegido contra divisão por zero).

A métrica de seleção do melhor modelo é escolhida com um default seguro por tarefa (roc_auc para binária, f1_macro para multiclasse, r2 para regressão) e pode ser trocada:

res = dk.run("dados.csv", target="classe", metric="average_precision")

Inferência com um modelo salvo

import datakhanon as dk
import pandas as pd

model = dk.load("outputs/exp1")            # carrega o pipeline (preprocessor + modelo)
novos = pd.read_csv("novos_dados.csv")
preds = model.predict(novos)               # o preprocessing salvo é reaplicado

CLI

datakhanon inspect dados.csv --target classe --save relatorio/
datakhanon run dados.csv --target classe --models auto --cv 5 --out outputs/exp1
datakhanon predict --run outputs/exp1 --data novos.csv --out predicoes.csv

Níveis de API

1. Rápida — dk.run(...), dk.Dataset(...), dk.inspect(...), dk.load(...).
2. Configurável — dk.Experiment(dk.ExperimentConfig(target=..., cv=..., metric=..., models=..., preprocess={...})).
3. Baixo nível — componentes de sempre em datakhanon.preprocess (Preprocessor, encoders, imputers, FeatureEngineer, detect_outliers, handle_outliers), datakhanon.model (AutoTrainer, metrics, selector, persistence, exporter) e datakhanon.visualize.

A API antiga (Preprocessor, AutoTrainer, quick_experiment_*) continua funcionando — e o quick_experiment_* agora roda o fluxo sem vazamento.

Estrutura de um run salvo

outputs/exp1/
├─ config.json
├─ schema.json
├─ summary.json
├─ model/best_model.joblib
├─ eda/data_health_report.html
└─ predictions/predictions.csv

Desenvolvimento

pip install -e ".[dev]"
pytest                          # roda a suíte de testes (inclui testes de leakage)
pytest --cov=datakhanon --cov-report=term-missing

Licença e créditos

Licença: MIT. Autor: Vinicius de Souza Santos.