FTIR-OPTUNA

Framework de AutoML para espectros FTIR: um único estudo Optuna otimiza, a cada trial, tanto o pipeline de pré-processamento (via ftir_prep) quanto a escolha do classificador e seus hiperparâmetros — simultaneamente, não em etapas separadas.

Para o histórico de decisões de design, bugs encontrados/corrigidos e a investigação de integração com o amlb_ainet, ver CLAUDE.md.

Requisitos

• Python 3.9
• O pacote ftir_prep (no PyPI, instalado automaticamente como dependência — ver abaixo)

Instalação

ftir-optuna-automl está no PyPI e depende do ftir-prep (também no PyPI) diretamente — a partir do ftir-prep>=0.3.5, o pip resolve as duas instalações sozinho, sem passo manual:

# 1. Crie e ative um venv
python3.9 -m venv venv
source venv/bin/activate

# 2. Instale o ftir-optuna-automl (traz o ftir-prep junto)
pip install ftir-optuna-automl

Para desenvolver este repositório em vez de só usar a biblioteca, clone o repositório e instale em modo editável (pip install -e .) no lugar do passo 2 acima, depois instale as dependências de dev:

git clone https://github.com/lucas-mendonca-andrade/ftir-optuna-automl.git
cd ftir-optuna-automl
pip install -e .
pip install -r requirements.txt   # suite de testes, notebook, empacotamento

Configuração

Os caminhos de dataset não ficam hardcoded no código — vêm de variáveis de ambiente, carregadas de um arquivo .env na raiz do projeto (não versionado; cada máquina tem o seu).

cp .env.example .env
# edite .env com os caminhos reais da sua maquina

Se TEA_DATA_PATH/TEA_WAVENUMBERS_PATH estiverem faltando, a importação de config falha imediatamente com uma mensagem clara (não um FileNotFoundError genérico no meio de uma busca).

Uso rápido

from config import settings
from ftir_prep import FTIRDataLoader
from ftir_optuna_automl import AutoMLOptunaOptimizer

# 1. Carregar os dados
loader = FTIRDataLoader(
    data_path=str(settings.tea_data_path),
    wavenumbers_path=str(settings.tea_wavenumbers_path),
)
X, y, wavenumbers = loader.load_data()

# 2. Rodar a busca conjunta (pre-processamento + classificador)
optimizer = AutoMLOptunaOptimizer(X, y, wavenumbers)
optimizer.optimize(
    time_budget_s=600,       # orcamento de tempo (segundos)
    memory_limit_mb=4096,    # teto de memoria (RSS), em MB
)

# 3. Ver o resultado
summary = optimizer.get_optimization_summary()
print(summary["best_classifier"], summary["best_value"])

# 4. Treinar o melhor pipeline no dado completo e salvar (p/ SHAP pos-hoc, ex.)
optimizer.fit_best()
optimizer.save_fitted_pipeline("models/tea")

Notebook interativo

optuna_automl.ipynb cobre o mesmo fluxo com todos os parâmetros expostos (célula por célula, com explicação de cada um). Abra com o kernel "Python (ftir-optuna)":

python -m ipykernel install --user --name=ftir-optuna --display-name="Python (ftir-optuna)"

Parâmetros principais

AutoMLOptunaOptimizer(X, y, wavenumbers, ...):

optimizer.optimize(...):

Preset structure_then_refine

Analogamente aos presets de frameworks como AutoGluon/MLJAR, optimize(..., preset="structure_then_refine") divide time_budget_s em duas fases sequenciais, cada uma com metade do orçamento:

1. Estrutura (50%): busca só quais técnicas de pré-processamento e qual classificador usar, avaliando cada combinação com os hiperparâmetros default de cada técnica/modelo — sem tunar.
2. Refino (50%): fixa a estrutura vencedora da fase 1 e tuna só os hiperparâmetros dela, no mesmo espaço de busca condicional completo usado no modo sem preset.

optimizer.optimize(
    time_budget_s=600,
    memory_limit_mb=4096,
    preset="structure_then_refine",
)

Depois de rodar, optimizer.structure_study_/optimizer.refine_study_ dão acesso aos dois estudos Optuna internos separadamente; optimizer.best_pipeline_/optimizer.best_classifier_ (e get_optimization_summary()) sempre refletem o resultado final da fase de refino.

Rodando os testes

pytest

37 testes, cobrindo desde o comportamento default até cenários de concorrência real (n_jobs>1), persistência/retomada, validação de orçamento de recursos e o preset structure_then_refine.

Estrutura do projeto

FTIR-OPTUNA/
├── src/ftir_optuna_automl/   # o pacote em si (instalavel via pip)
├── tests/                    # suite pytest
├── config.py                 # carrega .env (caminhos de dataset deste repositorio)
├── optuna_automl.ipynb       # notebook interativo
├── simulate_amlb_ftir_tea_10min_acc.py  # simula o benchmark real do amlb_ainet
├── dist/                     # wheel buildado
└── pyproject.toml

Licença

MIT