DataKhanon

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

Analise o dataset, corrija os dados, treine, avalie e exporte um modelo em poucos comandos — para classificação (binária/multiclasse) e regressão, detectadas automaticamente pelo alvo — sem cair nas armadilhas científicas mais comuns (vazamento de dados, métricas enganosas em dados desbalanceados). Funciona em scripts, Jupyter e Google Colab.

O DataKhanon é agnóstico de domínio: funciona com qualquer CSV/DataFrame tabular (saúde, finanças, indústria, marketing, etc.). Você só informa a coluna alvo; a biblioteca cuida do resto e não assume nada sobre o seu domínio.

dk.run vs dk.Dataset (importante!)

Há dois pontos de entrada, e confundi-los é o erro mais comum:

• dk.run(dados, target=...) → já treina e devolve um ExperimentResult. Use quando quer o resultado direto. Os métodos do resultado são res.report(), res.plot(), res.save(), res.export(), res.predict().
• dk.Dataset(dados, target=...) → um objeto para analisar e limpar (ds.eda(), ds.inspect(), ds.outliers(), ds.fix_outliers(), ds.auto_clean()) e depois treinar com ds.run(...).

Não chame métodos de análise (.eda(), .inspect()) no retorno de dk.run — aquilo já é um resultado de treino, não um Dataset.

---

Índice

• Instalação
• Conceito em 30 segundos
• Descobrir a biblioteca: dk.info()
• Análise exploratória (EDA) e limpeza
• Classificação
• Regressão
• Escolhendo o modelo
• Métricas
• Salvar, exportar e inferência
• Linha de comando (CLI)
• Referência dos módulos
• Níveis de API
• Reprodutibilidade e artefatos
• Desenvolvimento

---

Instalação

pip install datakhanon

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

pip install "datakhanon[viz,explainer]"      # gráficos interativos + SHAP
pip install "datakhanon[boost]"              # XGBoost + LightGBM (entram no 'auto')

No Google Colab / Jupyter, depois de instalar (ou trocar de versão) reinicie o runtime antes do import datakhanon — senão a versão antiga continua carregada na memória:

!pip install -q -U datakhanon
# Runtime -> Restart session, e então:
import datakhanon as dk
print(dk.__version__)

Instalar a última versão em desenvolvimento (direto do GitHub):

pip install "git+https://github.com/ViniciusKanh/datakhanon.git@main"

---

Conceito em 30 segundos

import datakhanon as dk

res = dk.run("dados.csv", target="alvo")   # detecta classificação OU regressão sozinho
res.report()                               # modelo escolhido + ranking + métricas
res.save("outputs/exp1")                   # run completo em disco
res.export("modelo.joblib")                # modelo pronto p/ deploy

dk.run executa, na ordem cientificamente correta:

1. inspeciona o dataset (nulos, duplicatas, outliers, 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 à tarefa;
6. salva modelo, schema, métricas e relatório.

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

---

Descobrir a biblioteca: dk.info()

Não precisa decorar nada. Pergunte à própria biblioteca o que cada parte faz:

import datakhanon as dk

dk.info()              # visão geral de todos os módulos
dk.info("preprocess")  # detalha o pré-processamento
dk.info("model")       # detalha a modelagem
dk.info("dataset")     # detalha a análise/limpeza

No terminal:

datakhanon info
datakhanon info preprocess
datakhanon info model

---

Análise exploratória (EDA) e limpeza

Use Dataset para analisar e corrigir antes de treinar. Tudo em poucos comandos:

import datakhanon as dk

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

# 1) Análise ANTES de mexer — em UM comando (imprime o panorama e mostra os gráficos)
ds.eda()

# ou passo a passo:
ds.inspect()          # saúde do dataset + alertas
ds.head()             # olhar algumas linhas
ds.plot_missing(); ds.plot_correlation(); ds.plot_target()

# 2) Ver e corrigir outliers (o alvo NUNCA é alterado)
ds.outliers()             # onde estão (IQR ou z-score), por coluna
ds.fix_outliers("clip")   # winsoriza; ou "remove" / "nan"

# 3) Limpeza automática sensata em UM comando (com relatório do que fez)
ds.auto_clean()

O que cada método faz:

Método	O que faz
ds.eda(plots=True)	Panorama completo (tipos, faltantes, duplicatas, outliers, alvo, correlações) + gráficos.
ds.inspect()	Resumo de saúde + alertas (retorna objeto com .alerts, .to_dict()).
ds.outliers(method="iqr")	Detecta outliers por coluna (não altera nada).
ds.fix_outliers(strategy)	Corrige outliers: "clip", "remove" ou "nan".
ds.clean(drop_dupes=, impute=)	Remove duplicatas e (opcional) imputa.
ds.auto_clean()	Padroniza nomes, remove duplicatas, descarta colunas muito vazias e trata outliers — com relatório.
ds.plot_missing / plot_correlation / plot_histograms / plot_target	Gráficos matplotlib prontos p/ inline.

A imputação de faltantes não é aplicada na limpeza exploratória de propósito: ela acontece no treino, dentro dos folds, para não vazar informação.

---

Classificação

Alvo categórico (2 ou mais classes) → o DataKhanon detecta binária ou multiclasse sozinho. Vale para qualquer domínio (basta trocar o CSV e o alvo):

import datakhanon as dk

ds = dk.Dataset("dados.csv", target="alvo")   # ex.: churn, diagnóstico, categoria...
ds.eda()                               # entender os dados (Dataset, não o run!)
ds.fix_outliers("clip")                # corrigir

res = ds.run(models="best", cv=5)      # treinar (melhor modelo por CV)
res.report()                           # modelo escolhido + ranking + métricas
res.plot()                             # matriz de confusão (rótulos legíveis)
res.save("outputs/exp"); res.export("outputs/exp/modelo.joblib")

Regressão

Se o alvo for numérico contínuo, tudo funciona igual — a tarefa vira regression automaticamente, com métricas e gráficos próprios:

import datakhanon as dk

ds = dk.Dataset("casas.csv", target="preco")     # preco é contínuo
ds.eda()                                          # mostra min/média/mediana/max do alvo
res = ds.run(models="best", cv=5)

print(res.task)          # "regression"
res.report()             # rmse, mae, r2, mape, median_ae...
res.plot()               # gráfico Previsto vs Real
res.export("modelo_preco.joblib")

Não é preciso dizer que é regressão — o detect_task_type decide pelo alvo (float contínuo → regressão; poucas classes → classificação). Para forçar, escolha um modelo de regressão explicitamente (ex.: models="rf_reg").

---

Escolhendo o modelo

Vale para classificação e regressão — o DataKhanon detecta a tarefa pelo alvo e aplica os candidatos certos automaticamente. Você escolhe apenas a estratégia com models= (o mesmo parâmetro em dk.run(...) e em ds.run(...)):

Valor	Efeito
"auto" / "best"	Testa candidatos por CV e escolhe o melhor.
"ensemble"	Combina os melhores num VotingClassifier/VotingRegressor.
nome do modelo	Classificação: "logistic", "rf", "gb", "dt", "xgb", "lgbm". Regressão: "linear", "rf_reg", "gb_reg", "dt_reg", "svr", "xgb_reg", "lgbm_reg".
estimador sklearn	Ex.: RandomForestClassifier(n_estimators=300).

"xgb"/"lgbm" exigem o extra boost instalado. Veja os códigos com dk.list_models().

Veja por que um modelo venceu:

res.cv_results     # [('rf', 0.977), ('gb', 0.977), ('logistic', 0.640), ...]

---

Métricas

Nunca dependa só de accuracy. res.metrics traz, por tarefa:

Classificação: accuracy, balanced_accuracy, precision, recall, f1, mcc, roc_auc, average_precision (PR-AUC), log_loss (e fbeta sob demanda).

Regressão: mse, rmse, mae, median_ae, r2, mape (protegido contra zero).

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

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

---

Recursos avançados (0.4.0)

Todos opcionais e acessíveis pelo mesmo run/Dataset.

Métricas por validação cruzada (média ± desvio). Mais confiáveis que um único holdout — essenciais em datasets pequenos. Já vêm no res.report(); para ver só elas:

res.cv_report()      # ou res.cv_metrics

Balanceamento automático de classes (aplicado dentro dos folds, sem leakage):

res = dk.run("dados.csv", target="alvo", balance="auto")   # ou "class_weight" / "smote"

Tuning leve de hiperparâmetros (RandomizedSearch no pipeline):

res = dk.run("dados.csv", target="alvo", tune=True)
res.best_params

Importância das features (permutation importance no holdout):

res.importance(top=15)      # DataFrame
res.plot_importance()       # gráfico

Ajuste de limiar (classificação binária):

melhor = res.tune_threshold("f1")          # {'threshold': 0.7, 'score': ...}
res.predict(novos, threshold=melhor["threshold"])

Estratégia de validação — séries temporais e grupos:

dk.run("serie.csv", target="y", cv_strategy="timeseries")
dk.run("dados.csv", target="y", cv_strategy="group", group_col="paciente")

Relatório HTML e model card (para compartilhar / governança):

res.to_html("relatorio.html")     # relatório visual autocontido
res.model_card("model_card.md")   # ficha do modelo (Markdown)

Sugestões de limpeza (não altera nada, só recomenda):

dk.Dataset("dados.csv", target="alvo").suggest()

Salvar, exportar e inferência

res.save("outputs/exp1")                 # run completo (modelo + schema + summary + predições)
res.export("outputs/exp1/modelo.joblib") # só o modelo (pipeline preprocessor+modelo)

# depois, para prever em novos dados:
import pandas as pd
model = dk.load("outputs/exp1")          # recarrega o pipeline
novos = pd.read_csv("novos.csv")
model.predict(novos)                     # o pré-processamento salvo é reaplicado

save() nunca sobrescreve em silêncio: se o diretório já existir e não estiver vazio, use res.save("...", overwrite=True).

---

Linha de comando (CLI)

datakhanon info                                   # o que cada módulo faz
datakhanon inspect dados.csv --target alvo --save relatorio/
datakhanon run dados.csv --target alvo --models auto --cv 5 --out outputs/exp1
datakhanon predict --run outputs/exp1 --data novos.csv --out predicoes.csv

---

Referência dos módulos

datakhanon (alto nível): run, inspect, load, info, Dataset, Experiment, ExperimentConfig, ExperimentResult.

datakhanon.preprocess: Preprocessor (orquestrador fit/transform/save/load, sklearn-compatível, com .summary()), ColumnImputer, OneHotEncoderWrapper, OrdinalEncoderWrapper, TargetEncoderWrapper, FeatureEngineer, detect_outliers, handle_outliers, e utilitários de limpeza (standardize_column_names, drop_duplicates, drop_missing_threshold, convert_dtypes).

datakhanon.model: AutoTrainer (seleção por CV / ensemble, aceita um preprocessor para CV sem leakage), selector.detect_task_type / default_candidates, ensemble.make_ensemble, metrics (classification_metrics, regression_metrics, auto_metrics), persistence (save_model/load_model), exporter (export), report.generate_report.

datakhanon.visualize: quick_eda e funções de plotagem (plot_*).

dk.info("<modulo>") imprime esta referência sempre atualizada.

---

Níveis de API

1. Rápida — dk.run(...), dk.Dataset(...), dk.inspect(...), dk.load(...), dk.info(...).
2. Configurável — dk.Experiment(dk.ExperimentConfig(target=..., cv=..., metric=..., models=..., preprocess={...})).
3. Baixo nível — componentes de datakhanon.preprocess, datakhanon.model, datakhanon.visualize.

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

---

Reprodutibilidade e artefatos

Todo run registra random_state, versão da biblioteca, tarefa, métricas, schema e configuração em res.metadata. 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                          # suíte de testes (inclui testes de vazamento)
pytest --cov=datakhanon --cov-report=term-missing

---

Licença

MIT. Autor: Vinicius de Souza Santos.