# Dataset IED — Meteorologia e Transporte Aéreo Brasileiro

Plataforma de coleta, processamento e visualização de dados meteorológicos e de transporte aéreo brasileiro, com foco em aeroportos operados pelo sistema DECEA/ICEA.

---

## Sumário

- [Pré-requisitos](#pré-requisitos)
- [Instalação](#instalação)
- [Estrutura do Projeto](#estrutura-do-projeto)
- [Módulos e Uso](#módulos-e-uso)
  - [Scraper de Meteorologia](#1-scraper-de-meteorologia)
  - [Pipeline Completo](#2-pipeline-completo)
  - [Concatenação de CSVs](#3-concatenação-de-csvs)
  - [Dashboard Interativo](#4-dashboard-interativo)
  - [Diagnóstico de Outliers](#5-diagnóstico-de-outliers)
- [Banco de Dados](#banco-de-dados)
- [Categorias ICAO](#categorias-icao)
- [Solução de Problemas](#solução-de-problemas)

---

## Pré-requisitos

| Requisito | Versão mínima | Observação |
|-----------|--------------|------------|
| Python | 3.10+ | [python.org](https://www.python.org/downloads/) |
| Google Chrome | Qualquer versão recente | Necessário para o Selenium (scraper) |
| Git | Qualquer | Para clonar o repositório |

> O `webdriver-manager` baixa automaticamente o ChromeDriver compatível com a versão do Chrome instalada. Não é necessário instalar o ChromeDriver manualmente.

---

## Instalação

### 1. Clonar o repositório

```bash
git clone ssh://git@git.ppgao.ita.br:2222/reboucassr/dataset.git
cd dataset
```

> Caso não tenha acesso SSH configurado, solicite ao administrador a chave de acesso ou use HTTPS se disponível.

### 2. Criar e ativar o ambiente virtual

Navegue até o diretório do módulo de meteorologia:

```bash
cd softwares/test
```

**Windows (PowerShell):**
```powershell
python -m venv .venv            # Instala o ambiente virtual no Windows
.\.venv\Scripts\Activate.ps1    # Ativa o ambiente virtual
```

**Linux / macOS:**
```bash
python3 -m venv .venv
source .venv/bin/activate # Para Linux e macOS
```

> No Windows, se receber erro de política de execução, execute antes:
> `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`

### 3. Instalar dependências

Com o ambiente virtual ativado:

```PowerShell
pip install -r requirements.txt
```

Principais pacotes instalados:

| Pacote | Finalidade |
|--------|-----------|
| `selenium` | Automação do navegador para scraping |
| `webdriver-manager` | Gerencia o ChromeDriver automaticamente |
| `beautifulsoup4` + `lxml` | Parsing de HTML |
| `pandas` | Processamento e análise de dados |
| `streamlit` | Dashboard interativo |
| `plotly` | Gráficos interativos |

---
### 4. Executar o projeto

Com o ambiente virtual ativado:

```PowerShell
cd meteorologia_aeroportos
streamlit run dashboard.py
```

> O dashboard será executado na porta 8501.


## Estrutura do Projeto

```
dataset/
├── softwares/
│   └── test/
│       └── meteorologia_aeroportos/
│           ├── dados/                  # Banco SQLite + CSVs por aeródromo
│           │   ├── met.db              # Banco de dados principal
│           │   ├── SBGR/              # CSVs do aeroporto de Guarulhos
│           │   └── SBAN/              # CSVs de outros aeródromos
│           ├── scraper_meteorologia.py # Coleta dados do ICEA/DECEA
│           ├── pipeline.py            # Orquestrador completo
│           ├── concat_meteorologia.py # Mescla arquivos CSV
│           ├── db.py                  # Lógica do banco SQLite
│           ├── dashboard.py           # Dashboard Streamlit
│           ├── _diag_outliers.py      # Diagnóstico de qualidade
│           └── requirements.txt
├── tabelas/
│   ├── raw/                           # Dados brutos ANAC
│   ├── preproc/                       # Dados intermediários
│   └── proc/                          # Dados processados finais
└── textos/
    ├── artigos/                        # Artigos acadêmicos
    ├── livros/
    └── relatorios/                     # Relatórios ANAC e setor
```

---

## Módulos e Uso

> Todos os comandos abaixo devem ser executados a partir do diretório `softwares/test/meteorologia_aeroportos/`, com o ambiente virtual ativado.

### 1. Scraper de Meteorologia

Coleta dados de superfície horários do portal ICEA/DECEA para um dado aeródromo.

**Coletar todos os anos disponíveis:**
```bash
python scraper_meteorologia.py --aerodrome SBGR --all-years
```

**Coletar um intervalo de anos específico:**
```bash
python scraper_meteorologia.py --aerodrome SBGR --start-year 2020 --end-year 2025
```

**Executar com navegador visível (sem modo headless — útil para depuração):**
```bash
python scraper_meteorologia.py --aerodrome SBGR --start-year 2023 --end-year 2023 --no-headless
```

**Parâmetros disponíveis:**

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `--aerodrome` | string | Código ICAO do aeródromo (ex: `SBGR`, `SBSP`, `SBAN`) |
| `--all-years` | flag | Coleta desde o início do histórico disponível |
| `--start-year` | int | Ano inicial do intervalo |
| `--end-year` | int | Ano final do intervalo |
| `--no-headless` | flag | Abre o Chrome de forma visível |

Os arquivos CSV são salvos em `dados/{CÓDIGO_ICAO}/`.

---

### 2. Pipeline Completo

Orquestra todo o fluxo: verifica cobertura existente, executa scraping incremental, valida dados com limites físicos, calcula variáveis analíticas e persiste no banco SQLite.

**Processar todos os anos para um aeródromo:**
```bash
python pipeline.py --aerodrome SBGR --all-years
```

**Processar intervalo específico:**
```bash
python pipeline.py --aerodrome SBGR --start-year 2020 --end-year 2025
```

**Manter arquivos temporários após o processamento:**
```bash
python pipeline.py --aerodrome SBGR --all-years --no-cleanup
```

**Parâmetros disponíveis:**

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `--aerodrome` | string | Código ICAO do aeródromo |
| `--all-years` | flag | Processa todo o histórico disponível |
| `--start-year` | int | Ano inicial |
| `--end-year` | int | Ano final |
| `--no-cleanup` | flag | Mantém CSVs intermediários após upsert |

> **Recomendado para uso normal.** O pipeline é idempotente: pode ser executado múltiplas vezes sem duplicar dados.

---

### 3. Concatenação de CSVs

Mescla os arquivos CSV trimestrais baixados pelo scraper em uma tabela única por aeródromo.

```bash
python concat_meteorologia.py --dados-dir dados --validate --cleanup
```

**Parâmetros:**

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `--dados-dir` | string | Diretório raiz dos CSVs (padrão: `dados`) |
| `--validate` | flag | Aplica validação por limites físicos |
| `--cleanup` | flag | Remove arquivos temporários após concatenação |

> Este passo é executado automaticamente pelo `pipeline.py`. Use-o de forma isolada apenas se precisar reprocessar os CSVs sem coletar novos dados.

---

### 4. Dashboard Interativo

Interface web para análise e visualização das séries temporais meteorológicas.

```bash
streamlit run dashboard.py
```

Acesse no navegador: **http://localhost:8501**

**Funcionalidades do dashboard:**

- Seleção de aeródromo e variável meteorológica
- Reamostagem temporal: Horária, Diária, Semanal, Mensal
- Gráficos de série temporal interativos (Plotly)
- Rosa dos ventos
- Análise de teto e visibilidade com classificação ICAO
- Distribuição estatística por variável

---

### 5. Diagnóstico de Outliers

Analisa a qualidade dos dados no banco, exibindo estatísticas sobre valores tratados por limites físicos.

```bash
python _diag_outliers.py
```

Exibe contagens e proporções de outliers registrados na tabela `outlier_log` por variável meteorológica.

---

## Banco de Dados

O banco SQLite (`dados/met.db`) possui três tabelas:

| Tabela | Descrição |
|--------|-----------|
| `observations` | Série temporal horária com 10 variáveis meteorológicas |
| `outlier_log` | Registro de valores anômalos tratados (auditoria) |
| `aerodromes` | Catálogo de aeródromos disponíveis |

**Variáveis na tabela `observations`:**

| Coluna | Descrição | Unidade |
|--------|-----------|---------|
| `T` | Temperatura | °C |
| `Td` | Ponto de orvalho | °C |
| `UR` | Umidade relativa | % |
| `QNH` | Pressão atmosférica | hPa |
| `WS` | Velocidade do vento | kt |
| `WG` | Rajada de vento | kt |
| `WD` | Direção do vento | graus |
| `VIS` | Visibilidade | dam |
| `TETO` | Teto de nuvens | dam |
| `PREC` | Precipitação acumulada | mm |

---

## Categorias ICAO

O dashboard classifica as condições meteorológicas segundo os critérios ICAO:

| Categoria | Teto (dam) | Visibilidade (dam) | Condição |
|-----------|------------|-------------------|----------|
| **LIFR** | < 31 | < 16 | IFR Severo |
| **IFR** | 31–91 | 16–48 | Voo por instrumentos |
| **MVFR** | 91–300 | 48–800 | VFR Marginal |
| **VMC** | > 300 | > 800 | Condições visuais |

---

## Solução de Problemas

**Erro de ChromeDriver / Selenium:**
- Verifique se o Google Chrome está instalado na máquina.
- O `webdriver-manager` tentará baixar o ChromeDriver automaticamente; verifique se há acesso à internet.
- Em ambientes corporativos com proxy, pode ser necessário configurar `HTTP_PROXY` / `HTTPS_PROXY`.

**Erro ao ativar o ambiente virtual no Windows:**
```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

**Dashboard não abre / porta ocupada:**
```bash
streamlit run dashboard.py --server.port 8502
```

**Banco de dados não encontrado:**
- Execute o `pipeline.py` ao menos uma vez para criar e popular o banco `dados/met.db`.

**Dados ausentes para um aeródromo:**
- Verifique se o código ICAO está correto e disponível no portal ICEA: https://pesquisa.icea.decea.mil.br/superficie_list/
- Nem todos os aeródromos possuem histórico completo desde 1947.

---

## Fonte dos Dados

- **Meteorologia:** Portal ICEA/DECEA — https://pesquisa.icea.decea.mil.br/superficie_list/
- **Transporte Aéreo:** ANAC — Relatório Anual 2024 e séries históricas de demanda e oferta

---

*Projeto de pesquisa acadêmica — IED / ITA*