Metadata-Version: 2.4
Name: datakhanon
Version: 0.4.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: boost
Requires-Dist: xgboost>=2.0; extra == "boost"
Requires-Dist: lightgbm>=4.0; extra == "boost"
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.**

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](#instalação)
- [Conceito em 30 segundos](#conceito-em-30-segundos)
- [Descobrir a biblioteca: `dk.info()`](#descobrir-a-biblioteca-dkinfo)
- [Análise exploratória (EDA) e limpeza](#análise-exploratória-eda-e-limpeza)
- [Classificação](#classificação)
- [Regressão](#regressão)
- [Escolhendo o modelo](#escolhendo-o-modelo)
- [Métricas](#métricas)
- [Salvar, exportar e inferência](#salvar-exportar-e-inferência)
- [Linha de comando (CLI)](#linha-de-comando-cli)
- [Referência dos módulos](#referência-dos-módulos)
- [Níveis de API](#níveis-de-api)
- [Reprodutibilidade e artefatos](#reprodutibilidade-e-artefatos)
- [Desenvolvimento](#desenvolvimento)

---

## Instalação

```bash
pip install datakhanon
```

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

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

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

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

---

## Conceito em 30 segundos

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

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

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

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

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

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

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

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

```python
res.cv_report()      # ou res.cv_metrics
```

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

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

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

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

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

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

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

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

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

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

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

## Salvar, exportar e inferência

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

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

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