🌊 Wavewatch III & Machine Learning - Projeto IARA

Este repositório contém a pipeline completa de Machine Learning e processamento de dados para a previsão e ajuste de altura de ondas, utilizando dados do modelo Wavewatch III (WW3), reanálise do ERA5 e dados observacionais de boias (ex: SIMCOSTA, PNBOIA) para as regiões do Paraná (PR), Rio de Janeiro (RJ) e Rio Grande do Sul (RS). O projeto é desenvolvido sob o escopo do Projeto IARA.

---

🎯 Objetivo

Aplicar modelos de Machine Learning (como XGBoost, LightGBM, Random Forest, LSTM e estratégias de Blending) sobre dados do modelo numérico Wavewatch III e ERA5 para corrigir e aprimorar as previsões de altura significativa de ondas ($SWH$), especialmente durante eventos extremos (ressacas), reduzindo erros sistemáticos (resíduos) do modelo numérico.

---

📁 Estrutura do Repositório

WavewatchIII_Machine_Learning/
│
├── 📂 Arquivos_Forecast/           # [LOCAL] Dados brutos NetCDF (.nc) de Forecast WW3
├── 📂 Arquivos_Reforecast/         # [LOCAL] Dados brutos NetCDF (.nc) de Reforecast WW3
├── 📂 ERA5_Series_SWH/             # [LOCAL] Dados brutos NetCDF (.nc) do ERA5
│
├── 📂 data/                        # Dados do projeto
│   ├── 📂 raw/                     # Dados brutos em CSV (ex: dados qualificados de boias)
│   ├── 📂 interim/                 # Dados intermediários de processamento
│   └── 📂 processed/               # DataFrames finais prontos para ML (por região)
│       ├── 📂 pr/                  # DataFrames processados do Paraná
│       ├── 📂 rj/                  # DataFrames processados do Rio de Janeiro
│       └── 📂 rs/                  # DataFrames processados do Rio Grande do Sul
│
├── 📂 notebooks/                   # Pipeline em Jupyter Notebooks
│   ├── 📂 01_download/             # Scripts para obtenção de dados (WW3, ERA5, Boias)
│   ├── 📂 02_preprocessing/        # Padronização temporal e ajuste de datas/fusos
│   ├── 📂 03_features/             # Geração de atributos, cálculo de resíduos e merge
│   │   ├── 📂 pr/
│   │   ├── 📂 rj/
│   │   └── 📂 rs/
│   ├── 📂 04_modeling/             # Treinamento e avaliação dos modelos de ML
│   │   ├── 📂 pr/
│   │   ├── 📂 rj/
│   │   └── 📂 rs/
│   ├── 📂 05_evaluation/           # Comparação de erros e gráficos de eventos severos
│   └── 📂 utils/                  # Scripts utilitários auxiliares (compactação, etc.)
│
├── 📂 models/                      # Hiperparâmetros e salvamento de modelos treinados
│   ├── 📂 pr/
│   ├── 📂 rj/
│   └── 📂 rs/
│
├── 📂 results/                     # Tabelas e gráficos de saídas dos modelos
│   ├── 📂 pr/
│   ├── 📂 rj/
│   ├── 📂 rs/
│   └── 📄 resultados_modelos.md    # Consolidação final das métricas
│
├── 📂 config/                      # Configurações do ambiente
├── 📂 src/                         # Módulos Python reutilizáveis
├── 📄 requirements.txt             # Dependências do projeto
└── 📄 README.md                    # Documentação principal

⚠️ Nota sobre arquivos NetCDF (.nc):
As pastas Arquivos_Forecast/, Arquivos_Reforecast/ e ERA5_Series_SWH/ permanecem na raiz para execução dos notebooks localmente, mas são ignoradas pelo controle de versão do Git (*.nc no .gitignore) devido ao grande volume de dados.

---

🔄 Fluxo do Pipeline (Pipeline de Dados)

O processamento segue uma ordem lógica e organizada por subpastas:

flowchart TD
    A[notebooks/01_download<br/>Download de NetCDFs / Boias] --> B[Arquivos_Reforecast / ERA5_Series_SWH<br/>Dados Brutos NetCDF Locais]
    B --> C[notebooks/02_preprocessing<br/>Padronização temporal e fusos]
    C --> D[notebooks/03_features<br/>Criação de resíduos WW3 x ERA5 / Boia]
    D --> E[data/processed/{pr,rj,rs}/<br/>DataFrames CSV organizados]
    E --> F[notebooks/04_modeling<br/>Treinamento dos modelos ML & Blending]
    F --> G[models/{pr,rj,rs}/<br/>Hiperparâmetros e modelos salvos]
    F --> H[notebooks/05_evaluation<br/>Plotagens de eventos & Análise de erros]
    H --> I[results/{pr,rj,rs}/<br/>Gráficos & Tabela final de métricas]

Loading

Ordem de Execução Recomendada:

1. Obtenção dos Dados (notebooks/01_download/): Baixa arquivos de forecast/reforecast do WW3, reanálises do ERA5 e séries temporais das boias.
2. Pré-processamento (notebooks/02_preprocessing/): Padroniza os passos temporais (step) e converte fusos para o horário padrão.
3. Engenharia de Atributos (notebooks/03_features/): Processa as variáveis atmosféricas e oceanográficas por região, calculando os resíduos temporais e salvando em data/processed/{pr,rj,rs}/.
4. Modelagem Preditiva (notebooks/04_modeling/): Carrega os CSVs processados, realiza o ajuste de hiperparâmetros, treina os modelos de regressão/redes neurais (XGBoost, LSTM, Blending) e salva o progresso em models/{pr,rj,rs}/.
5. Avaliação e Resultados (notebooks/05_evaluation/): Plota o desempenho dos modelos em eventos severos de onda e compila relatórios em results/{pr,rj,rs}/.

---

🛠️ Tecnologias e Dependências

• Linguagem: Python 3.11+
• Manipulação de Dados: Pandas, NumPy, Xarray, NetCDF4
• Machine Learning: Scikit-Learn, XGBoost, LightGBM, Keras / TensorFlow
• Visualização: Matplotlib, Seaborn

Para instalar todas as dependências necessárias, execute:

pip install -r requirements.txt