Metadata-Version: 2.4
Name: datakhanon
Version: 0.2.0
Summary: Biblioteca para mineração de dados e aprendizado de máquina com fluxo end-to-end.
Author-email: Vinicius de Souza Santos <vinicius.santos@ifsp.edu.br>
Maintainer-email: ViniciusKanh <vinicius.santos@ifsp.edu.br>
License-Expression: MIT
Project-URL: Homepage, https://github.com/ViniciusKanh/datakhanon
Project-URL: Bug Tracker, https://github.com/ViniciusKanh/datakhanon/issues
Project-URL: Documentation, https://github.com/ViniciusKanh/datakhanon
Project-URL: Source, https://github.com/ViniciusKanh/datakhanon
Keywords: data-mining,machine-learning,feature-engineering,preprocessing,eda,model-selection,datakhanon
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: scikit-learn>=1.3
Requires-Dist: scipy>=1.10
Requires-Dist: matplotlib>=3.8
Requires-Dist: seaborn>=0.13
Requires-Dist: joblib>=1.3
Requires-Dist: PyYAML>=6.0
Requires-Dist: imbalanced-learn>=0.12
Provides-Extra: viz
Requires-Dist: plotly>=5.0; extra == "viz"
Requires-Dist: bokeh>=3.0; extra == "viz"
Provides-Extra: dashboard
Requires-Dist: streamlit>=1.30; extra == "dashboard"
Provides-Extra: explainer
Requires-Dist: shap>=0.44; extra == "explainer"
Provides-Extra: embed
Requires-Dist: umap-learn>=0.5; extra == "embed"
Provides-Extra: ensemble
Provides-Extra: dev
Requires-Dist: black>=24.0; extra == "dev"
Requires-Dist: isort>=5.13; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: ipython>=8.0; extra == "dev"
Requires-Dist: twine>=6.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Dynamic: license-file

# DataKhanon

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Python](https://img.shields.io/badge/Python-3.9%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
[![scikit-learn](https://img.shields.io/badge/scikit--learn-1.3%2B-F7931E?logo=scikit-learn&logoColor=white)](https://scikit-learn.org/)

**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

```bash
pip install datakhanon
```

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

```bash
pip install "datakhanon[viz,explainer]"
```

---

## Quickstart — 1 comando

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

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

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

---

## Inferência com um modelo salvo

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

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

```bash
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**.
