V1.0

2026-05-31 18:57:03 -03:00
parent b90e69c1f9
commit 77ec04cc43
6 changed files with 142575 additions and 54 deletions
--- a/softwares/test/meteorologia_aeroportos/README.md
+++ b/softwares/test/meteorologia_aeroportos/README.md
@@ -0,0 +1,328 @@
+# 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*