V.1.0
This commit is contained in:
kolmeasi
169
softwares/test/meteorologia_aeroportos/docs/about.md
Normal file
169
softwares/test/meteorologia_aeroportos/docs/about.md
Normal file
@@ -0,0 +1,169 @@
|
||||
# Documentação Técnica — Meteorologia de Superfície
|
||||
|
||||
## O que é
|
||||
|
||||
Sistema de coleta, processamento e visualização de dados meteorológicos horários de aeródromos brasileiros. Os dados são extraídos do portal de dados de superfície do ICEA/DECEA, armazenados em um banco SQLite local e disponibilizados em um dashboard interativo para análise de séries temporais, climatologia e condições operacionais de voo.
|
||||
|
||||
O sistema foi desenvolvido como parte de projeto de pesquisa no IED/ITA.
|
||||
|
||||
---
|
||||
|
||||
## Fonte dos dados
|
||||
|
||||
**Portal:** https://pesquisa.icea.decea.mil.br/superficie_list/
|
||||
**Órgão:** ICEA — Instituto de Controle do Espaço Aéreo / DECEA — Departamento de Controle do Espaço Aéreo
|
||||
**Tipo:** Observações meteorológicas de superfície de aeródromos brasileiros
|
||||
|
||||
Os dados são organizados no portal em **9 abas temáticas** por período trimestral:
|
||||
|
||||
| Aba | Conteúdo |
|
||||
|-----|----------|
|
||||
| CGT | Dados corrigidos de superfície (conjunto) |
|
||||
| Nuvem | Cobertura e tipo de nuvem |
|
||||
| Precipitação | Intensidade e duração da chuva |
|
||||
| Pressão | QNH e pressão de superfície |
|
||||
| RVR | Alcance visual de pista por cabeceira |
|
||||
| Temperatura | Bulbo seco, orvalho, umidade por pista |
|
||||
| Teto | Teto de nuvens por pista |
|
||||
| Vento | Velocidade, rajada e direção por cabeceira |
|
||||
| Visibilidade | Visibilidade predominante |
|
||||
|
||||
A cobertura histórica varia por aeródromo. Os três aeródromos com dados carregados
|
||||
no banco na versão inicial são:
|
||||
|
||||
| ICAO | Aeródromo | Início do histórico |
|
||||
|------|-----------|---------------------|
|
||||
| SBGR | Guarulhos / Cumbica (SP) | 1951 |
|
||||
| SBAN | Santos (SP) | 1973 |
|
||||
| SBCC | Campinas / Viracopos (SP) | 1992 |
|
||||
|
||||
---
|
||||
|
||||
## Como funciona
|
||||
|
||||
O fluxo completo é orquestrado pelo módulo `pipeline.py`:
|
||||
|
||||
```
|
||||
1. Verifica cobertura existente no banco (db.get_coverage)
|
||||
2. Passe forward — baixa dados novos após a data máxima existente
|
||||
3. Passe backward — baixa histórico anterior à data mínima existente
|
||||
4. Concatena os CSVs trimestrais por aba (concat_meteorologia)
|
||||
5. Deriva as 10 variáveis analíticas (build_analytics)
|
||||
6. Persiste no SQLite com validação de limites físicos (db.upsert_analytics)
|
||||
7. Salva CSV de backup em tabelas/preproc/meteorologia_aeroportos/<ICAO>/
|
||||
8. Valida por amostragem contra os arquivos fonte
|
||||
9. Remove os CSVs temporários (se validação aprovada e --cleanup ativo)
|
||||
```
|
||||
|
||||
### Derivação das variáveis analíticas
|
||||
|
||||
As 84+ colunas brutas (uma por medição específica, por pista ou cabeceira) são reduzidas
|
||||
a 10 variáveis float por timestamp:
|
||||
|
||||
| Variável | Derivação |
|
||||
|----------|-----------|
|
||||
| `T` | Média das colunas de temperatura de bulbo seco |
|
||||
| `Td` | Média das colunas de ponto de orvalho |
|
||||
| `UR` | Média das colunas de umidade relativa |
|
||||
| `QNH` | Coluna genérica de QNH ou agregação das específicas |
|
||||
| `WS` | Média das velocidades de vento por cabeceira |
|
||||
| `WG` | Máximo das rajadas por cabeceira |
|
||||
| `WD` | Média da direção do vento |
|
||||
| `VIS` | Mínimo da visibilidade predominante |
|
||||
| `TETO` | Mínimo do teto por pista (conservador) |
|
||||
| `PREC` | Soma da precipitação acumulada |
|
||||
|
||||
### Limites físicos aplicados
|
||||
|
||||
Valores fora dos intervalos abaixo são substituídos por `NULL` e registrados em `outlier_log`:
|
||||
|
||||
| Variável | Mínimo | Máximo |
|
||||
|----------|--------|--------|
|
||||
| T | −25 °C | 55 °C |
|
||||
| Td | −30 °C | 40 °C |
|
||||
| UR | 0 % | 100 % |
|
||||
| QNH | 940 hPa | 1060 hPa |
|
||||
| WS | 0 kt | 200 kt |
|
||||
| WG | 0 kt | 250 kt |
|
||||
| WD | 0° | 360° |
|
||||
| VIS | 0 dam | 9999 dam |
|
||||
| TETO | 0 dam | 9999 dam |
|
||||
| PREC | 0 mm | 500 mm |
|
||||
|
||||
---
|
||||
|
||||
## Limitações conhecidas
|
||||
|
||||
1. **Extração via web scraping, não via API oficial.**
|
||||
O sistema automatiza interações de navegador (Selenium + Chrome). Qualquer alteração
|
||||
no layout, estrutura HTML ou comportamento JavaScript do portal ICEA pode interromper
|
||||
a coleta sem aviso prévio.
|
||||
|
||||
2. **Fonte única e exclusiva.**
|
||||
Os dados provêm exclusivamente da tabela de dados de superfície do portal
|
||||
https://pesquisa.icea.decea.mil.br/superficie_list/. Não há integração com METAR,
|
||||
SYNOP, REDEMET, SPECI, SIGMET, ou qualquer outra fonte meteorológica ou aeronáutica.
|
||||
|
||||
3. **Sem tratamento de erros de lançamento.**
|
||||
Os dados são replicados como estão no portal. Erros de digitação, transcrição incorreta
|
||||
ou valores biologicamente implausíveis mas dentro dos limites físicos definidos não são
|
||||
detectados nem corrigidos. A qualidade dos dados depende integralmente da fonte.
|
||||
|
||||
4. **Limites físicos são condição necessária, não suficiente.**
|
||||
Os filtros removem valores meteorologicamente impossíveis (ex: temperatura de 500 °C),
|
||||
mas não detectam erros plausíveis dentro dos limites (ex: QNH de 1010 hPa registrado
|
||||
incorretamente como 1001 hPa).
|
||||
|
||||
5. **Dependência de hardware e software local.**
|
||||
A coleta requer Google Chrome instalado. A performance e o sucesso da coleta dependem
|
||||
de conexão com a internet, versão do Chrome, e disponibilidade do portal.
|
||||
|
||||
6. **Cobertura histórica variável.**
|
||||
Nem todos os aeródromos possuem histórico completo. A disponibilidade de dados depende
|
||||
do que foi inserido no portal — aeródromos mais antigos ou de menor porte podem ter
|
||||
lacunas significativas.
|
||||
|
||||
7. **Processamento sequencial.**
|
||||
A coleta é executada para um aeródromo por vez. Não há paralelização da coleta
|
||||
de múltiplos aeródromos.
|
||||
|
||||
8. **Sem atualização automática.**
|
||||
A coleta de dados novos deve ser iniciada manualmente pelo usuário, seja via dashboard
|
||||
ou via linha de comando.
|
||||
|
||||
---
|
||||
|
||||
## Oportunidades de melhoria
|
||||
|
||||
| Prioridade | Melhoria |
|
||||
|------------|----------|
|
||||
| Alta | Agendamento automático da coleta (cron / Task Scheduler) |
|
||||
| Alta | Notificação de falha na coleta (e-mail, webhook) |
|
||||
| Alta | Coleta paralela de múltiplos aeródromos |
|
||||
| Média | Integração com REDEMET / METAR para validação cruzada |
|
||||
| Média | Detecção de anomalias por métodos estatísticos (z-score, IQR) |
|
||||
| Média | API REST sobre o banco SQLite para consumo programático |
|
||||
| Média | Suporte a dados SYNOP e SPECI do portal |
|
||||
| Baixa | Exportação em formatos científicos (NetCDF, HDF5, Parquet) |
|
||||
| Baixa | Interface de configuração de alertas por variável e limiar |
|
||||
| Baixa | Mapa de cobertura dos aeródromos disponíveis |
|
||||
|
||||
---
|
||||
|
||||
## Solução de problemas
|
||||
|
||||
**Chrome não encontrado / erro de WebDriver:**
|
||||
Verifique se o Google Chrome está instalado. O `webdriver-manager` baixa o ChromeDriver
|
||||
compatível automaticamente — é necessária conexão com a internet.
|
||||
|
||||
**Portal ICEA indisponível ou com layout alterado:**
|
||||
A coleta depende da estrutura HTML do portal. Se o portal alterar sua interface, o scraper
|
||||
pode parar de funcionar. Verifique o portal manualmente e abra uma issue no repositório.
|
||||
|
||||
**Dashboard não abre / porta ocupada:**
|
||||
```bash
|
||||
streamlit run _apps/dashboard.py --server.port 8502
|
||||
```
|
||||
|
||||
**Banco de dados não encontrado:**
|
||||
Execute o pipeline ao menos uma vez para criar e popular `db/met.db`.
|
||||
Reference in New Issue
Block a user