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 (não está no PyPI — instalado a partir de um wheel local, ver abaixo)

Instalação

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

# 2. Instale o ftir_prep a partir do wheel local do repositorio irmao
pip install --no-deps ../FTIR-Prep/dist/ftir_prep-0.3.1-py3-none-any.whl
pip install rampy==0.5.3 PyWavelets==1.6.0 statsmodels openpyxl shap matplotlib

# 3. Instale o ftir_optuna_automl
pip install -e .              # modo editavel, para desenvolver este repositorio
# ou, para so usar a biblioteca:
#   pip install dist/ftir_optuna_automl-0.1.0-py3-none-any.whl

# 4. Para rodar a suite de testes/notebook tambem, instale as deps de dev
pip install -r requirements.txt

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(...):

Rodando os testes

pytest

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

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