Download Automático, Preenchimento de Falhas de Dados Meteorológicos do INMET com Machine Learning

Introdução e Motivação

O que você aprenderá: Da obtenção dos dados à validação visual da imputação — um pipeline completo para dados climáticos do INMET com aplicações em epidemiologia e saúde pública.

A saúde humana é profundamente sensível às variações do clima. Ondas de calor aumentam o risco de desidratação, infarto e mortalidade cardiovascular. Períodos de frio intenso potencializam doenças respiratórias. Chuvas acima da média facilitam a proliferação de vetores transmissores de dengue, malária e leptospirose. Para compreender, monitorar e prever esses efeitos, pesquisadores, epidemiologistas e gestores de saúde pública precisam de séries temporais climáticas confiáveis, contínuas e bem documentadas.

O Instituto Nacional de Meteorologia (INMET) mantém uma rede de estações automáticas distribuídas por todo o território nacional, produzindo observações horárias de temperatura, umidade, pressão atmosférica, precipitação, vento e radiação solar. Esses dados são públicos, mas o acesso programático, a padronização das variáveis, o tratamento de falhas e a documentação do processo de imputação exigem esforço considerável quando feitos manualmente.

O pacote climasus4r resolve exatamente esse problema. Ele oferece um pipeline integrado que vai desde o download automático dos dados brutos do INMET até a visualização diagnóstica da qualidade da imputação. Três funções formam o núcleo desse pipeline:

sus_climate_inmet() — baixa, padroniza e aplica controle de qualidade físico nos dados horários do INMET
sus_climate_fill_inmet() — imputa valores faltantes usando modelos XGBoost treinados por estação e por variável
sus_climate_plot_fill() — gera visualizações profissionais para inspecionar e comunicar a qualidade do preenchimento

Este tutorial apresenta as três funções de forma progressiva, partindo do problema prático até a interpretação dos resultados. Cada seção combina explicação conceitual, descrição dos parâmetros e exemplos com código R que refletem cenários reais de uso em epidemiologia climática e vigilância ambiental.

📌 Nota: Este tutorial foi escrito para usuários que conhecem R, mas ainda não dominam o fluxo de dados climáticos do pacote. Não é necessário conhecimento prévio de modelagem por aprendizado de máquina: o pipeline foi desenhado para abstrair essa complexidade e entregar resultados prontos para análise.

Visão Geral do Pipeline

As três funções foram projetadas para operar em sequência. A saída de uma é a entrada esperada da seguinte, e cada etapa adiciona informação ou qualidade ao objeto de dados. O fluxo abaixo resume essa jornada:

Etapa	Função	Entrada	Saída	Papel no pipeline
1 — Obtenção	`sus_climate_inmet`	Anos e UFs	`climasus_df` com dados brutos padronizados	Fonte única de verdade dos dados observados
2 — Imputação	`sus_climate_fill_inmet`	`climasus_df`	`climasus_df` com valores preenchidos e flags `is_imputed_*`	Garante continuidade temporal para análise
3 — Diagnóstico	`sus_climate_plot_fill`	`climasus_df` preenchido ou lista de avaliação	Gráficos ggplot2 ou plotly + tabelas DT	Valida a plausibilidade do preenchimento

Na prática, o fluxo mais comum é:

Instalar e carregar o pacote — uma única vez por projeto
Baixar os dados com sus_climate_inmet(), filtrando por anos e estados de interesse
Inspecionar a cobertura verificando datas, estações e proporção de dados faltantes
Imputar falhas com sus_climate_fill_inmet() nas variáveis de interesse
Avaliar a qualidade da imputação antes de usar os dados em modelos epidemiológicos
Visualizar o preenchimento com sus_climate_plot_fill() para comunicar o processo
Integrar com dados de saúde para análises de associação clima–desfecho

💡 Dica: O objeto retornado por sus_climate_inmet() tem classe climasus_df, uma subclasse de tibble. Ele carrega metadados do processo de importação acessíveis via sus_meta(df). Esses metadados registram versão do pacote, timestamp, estados importados, estatísticas de controle de qualidade e o histórico das etapas de processamento.

`sus_climate_inmet()` — Obtendo Dados do INMET

O que a função faz

A função sus_climate_inmet() encapsula um pipeline completo de seis etapas que transforma arquivos CSV brutos do INMET em um objeto analítico padronizado, pronto para uso imediato:

Download automático — busca os arquivos anuais diretamente dos servidores do INMET com retry automático e backoff exponencial em caso de falha de conexão
Parsing — lê e interpreta o formato CSV específico do INMET, que inclui um cabeçalho de metadados antes dos dados tabulares
Padronização — renomeia as colunas para nomes canônicos independentes do ano (os nomes brutos do INMET variam entre versões)
Controle de qualidade físico — valores fora de intervalos fisicamente possíveis são convertidos para NA e registrados nas estatísticas de QC
Sistema de cache em dois níveis — memória de sessão e disco (formato Parquet comprimido) para evitar downloads repetidos
Processamento paralelo — entre anos e dentro de cada ano, entre arquivos CSV

O resultado é um climasus_df com timestamps em UTC, decimais normalizados (vírgula → ponto) e todas as strings em UTF-8. A temporalidade é sempre horária; para agregar em escalas diária, semanal ou mensal, use sus_climate_aggregate().

Parâmetros Principais

Parâmetro	Tipo	Padrão	Quando ajustar
`years`	Numérico ou vetor	Últimos 2 anos	Sempre que precisar de um período específico. Use `2020:2024` para séries históricas.
`uf`	Character ou vetor	`NULL` (todos os 27 estados)	Filtre por estado para reduzir volume. Ex: `c("AM", "PA")` para a Amazônia Legal.
`use_cache`	Lógico	`TRUE`	Mantenha `TRUE` em produção. Use `FALSE` apenas se suspeitar que o cache está desatualizado.
`cache_dir`	Character	`~/.climasus4r_cache/climate`	Altere se precisar de um diretório compartilhado em servidor ou cluster.
`parallel`	Lógico	`TRUE`	Mantenha `TRUE` para importações grandes. Use `FALSE` para depuração de erros.
`workers`	Inteiro	`4`	Aumente em servidores com muitos núcleos. Automaticamente limitado a cores disponíveis − 1.
`lang`	Character	`"pt"`	Mude para `"en"` ou `"es"` conforme o idioma do projeto.
`verbose`	Lógico	`TRUE`	Use `TRUE` durante o desenvolvimento para acompanhar progresso. `FALSE` em produção automatizada.

Variáveis Retornadas

Além das colunas de identificação da estação (station_code, station_name, region, UF, latitude, longitude, altitude) e da coluna de data/hora (date em POSIXct UTC), o objeto contém as 17 variáveis meteorológicas padronizadas:

Nome canônico	Descrição	Unidade	Relevância para saúde
`tair_dry_bulb_c`	Temperatura média do ar (bulbo seco)	°C	Estresse térmico, mortalidade cardiovascular, ondas de calor
`tair_max_c`	Temperatura máxima do ar	°C	Pico de calor diário, risco de insolação
`tair_min_c`	Temperatura mínima do ar	°C	Doenças respiratórias em períodos frios
`rh_mean_porc`	Umidade relativa média	%	Conforto térmico, transmissão de doenças respiratórias
`rh_max_porc`	Umidade relativa máxima	%	Condições favoráveis a vetores e fungos
`rh_min_porc`	Umidade relativa mínima	%	Ressecamento de mucosas, doenças respiratórias
`rainfall_mm`	Precipitação acumulada	mm	Doenças transmitidas por vetores (dengue, malária), leptospirose
`patm_mb`	Pressão atmosférica média	mb	Conforto respiratório em altitude, doenças cardiovasculares
`sr_kj_m2`	Radiação solar global	kJ/m²	Índice UV, fotodegradação de poluentes, saúde ocular
`ws_2_m_s`	Velocidade do vento a 2m	m/s	Dispersão de poluentes, conforto térmico
`ws_gust_m_s`	Rajada máxima de vento	m/s	Riscos estruturais, dispersão de aerossóis
`wd_degrees`	Direção do vento	graus	Transporte de poluentes e alérgenos
`dew_tmean_c`	Ponto de orvalho médio	°C	Indicador integrado de calor e umidade

Controle de Qualidade Automático

Antes de retornar os dados, a função aplica três camadas de verificação física:

Validação de intervalos físicos — valores impossíveis são convertidos para NA. Por exemplo, temperatura < −90 °C ou > 60 °C, umidade < 0 % ou > 100 %, pressão fora de 700–1100 mb
Consistência ponto de orvalho — o ponto de orvalho observado é comparado ao calculado pela fórmula de Magnus a partir de temperatura e umidade relativa. Divergências > 3 °C são marcadas como NA
Radiação solar noturna — valores positivos entre 18h e 6h (horário local) são zerados por inconsistência física

As estatísticas de QC ficam armazenadas no atributo de metadados do objeto e podem ser inspecionadas com sus_meta(df, "qc_stats").

⚠️ Atenção: Os dados do INMET são brutos e podem conter erros de sensor, falhas de transmissão e valores suspeitos que passam nos limites físicos. O controle de qualidade da função captura os casos mais evidentes, mas não substitui uma inspeção visual e estatística do pesquisador.

Sistema de Cache

A primeira execução de sus_climate_inmet() para um dado conjunto de anos e UFs pode demorar alguns minutos, dependendo da conexão e do volume de dados. Nas execuções seguintes, o cache de disco em formato Apache Parquet (com compressão Zstandard) reduz drasticamente o tempo de carregamento. O cache de memória elimina a leitura de disco quando a mesma consulta é repetida dentro da mesma sessão R.

Para limpar o cache de disco: unlink("~/.climasus4r_cache/climate", recursive = TRUE)
Para inspecionar o diretório de cache: list.files("~/.climasus4r_cache/climate", recursive = TRUE)

Exemplo Aplicado — Pesquisa no Amazonas

Cenário: uma pesquisadora de epidemiologia da Universidade Federal de Rondônia precisa de dados horários de temperatura, umidade e precipitação para estudar a relação entre extremos climáticos e internações por causas respiratórias em municípios do estado. Ela precisa dos dados de 2024 a 2025.

# ── Instalação (apenas uma vez) ─────────────────────────────────────────────
# install.packages("remotes")
# remotes::install_github("ByMaxAnjos/climasus4r")

library(climasus4r)
library(dplyr)

# ── Download: estações do Amazonas, 2022–2024 ────────────────────────────────

df_ro <- sus_climate_inmet(
  years = 2024,
  uf = "AM",
  parallel = FALSE,
  workers = 2,
  lang =  "pt",
  verbose = TRUE
)

# ── Inspecionar a estrutura ──────────────────────────────────────────────────
glimpse(df_ro)

# ── Estações disponíveis ────────────────────────────────────────────────────
df_ro |>
  distinct(station_code, station_name, latitude, longitude, altitude)

# ── Cobertura temporal ──────────────────────────────────────────────────────
range(df_ro$date, na.rm = TRUE)

# ── Proporção de dados faltantes por variável ───────────────────────────────
df_ro |>
  summarise(across(tair_dry_bulb_c:sr_kj_m2,
                   ~ mean(is.na(.x)) * 100,
                   .names = "pct_na_{.col}"))

# ── Metadados do processo ───────────────────────────────────────────────────
sus_meta(df_ro)

A saída de glimpse(df_ro) mostrará as colunas padronizadas, o tipo POSIXct para date e os valores numéricos já com ponto decimal. Os metadados revelarão quantas linhas foram corrigidas pelo QC e o tempo de processamento.

`sus_climate_fill_inmet()` — Preenchendo Falhas com XGBoost

Por que preencher falhas?

Séries temporais meteorológicas horárias raramente são completas. Falhas de sensor, problemas de transmissão de dados, manutenção de equipamentos e eventos extremos resultam em períodos de NA que podem comprometer análises epidemiológicas. Um modelo de regressão que associa temperatura a internações, por exemplo, simplesmente descarta as observações com datas faltantes — o que pode introduzir viés sazonal se as falhas forem mais frequentes em certos períodos do ano.

Preencher falhas não significa inventar dados: significa estimar os valores mais prováveis com base no comportamento temporal e nas regularidades da série. Quanto mais bem comportada e regular for a variável (como temperatura), mais confiável tende a ser a imputação. Variáveis muito ruidosas (como precipitação horária) são mais difíceis de imputar com precisão.

Como o modelo funciona

A função sus_climate_fill_inmet() treina um modelo XGBoost independente para cada combinação de estação e variável. Isso significa que o modelo para a estação A101 predizendo temperatura não é o mesmo que o modelo para a estação A119 — cada estação tem seu próprio padrão microclimático e seu próprio histórico de falhas.

Para cada estação e variável, o modelo recebe como preditores um conjunto rico de features criadas automaticamente a partir da série temporal:

Features temporais — hora do dia, dia do mês, mês do ano, ano, e transformações cíclicas via seno e cosseno (para capturar periodicidade diária e sazonal)
Features de lag — valores defasados em 1, 2, 3, 6, 12, 24, 48, 72 e 168 horas (este último captura o padrão semanal)
Estatísticas de janela deslizante — média e desvio padrão em janelas de 3, 6, 12, 24, 48 e 72 horas

Essa engenharia de features automática é o que permite ao XGBoost capturar o ciclo diário de temperatura, o padrão de chuvas após frentes frias e a autocorrelação de curto prazo na velocidade do vento, sem que o usuário precise especificar nada.

📌 Nota: A função é projetada exclusivamente para dados importados por sus_climate_inmet(). Ela conhece os nomes das 17 variáveis meteorológicas do INMET e usa esse conhecimento para treinamento e validação. Não use com dados de outras fontes sem adaptação prévia.

Modo de Produção e Modo de Avaliação

A função opera em dois modos distintos, controlados pelo argumento run_evaluation:

Modo	run_evaluation	O que faz	Saída
Produção	`FALSE` (padrão)	Imputa os NAs reais da série.	`climasus_df` com falhas imputadas. Adiciona uma coluna `is_imputed_<var>` indicando quais valores foram preenchidos.
Avaliação	`TRUE`	Cria artificialmente gaps em dados conhecidos (MCAR), imputa, compara com os valores verdadeiros e calcula métricas por estação.	Lista nomeada com `$data` e `$metrics` por variável.

O modo de avaliação é uma forma honesta de responder à pergunta: “quão bem o modelo teria se saído se eu não soubesse os valores reais?”. Ele simula o pior caso — falhas completamente aleatórias (MCAR) — e usa as métricas resultantes como garantia de qualidade antes de usar os valores imputados em análises.

Parâmetros Principais

Parâmetro	Padrão	Descrição
`df`	—	O objeto `climasus_df` retornado por `sus_climate_inmet()`. Obrigatório.
`target_var`	—	Variável(is) a imputar. Ex: `"tair_dry_bulb_c"`, `c("tair_dry_bulb_c", "ws_2_m_s")` ou `"all"` para todas.
`quality_threshold`	`0.4` (40%)	Proporção máxima de NAs por estação. Estações mais esparsas são excluídas do modelo.
`run_evaluation`	`FALSE`	`TRUE` ativa o modo de avaliação com métricas de desempenho.
`gap_percentage`	`0.2` (20%)	Proporção de dados removidos artificialmente no modo de avaliação.
`keep_features`	`FALSE`	`TRUE` retém as features de engenharia no tibble final (útil para depuração).
`parallel`	`TRUE`	Processa estações em paralelo com furrr.
`workers`	`NULL` (auto)	Número de workers paralelos. `NULL` usa cores disponíveis − 1.
`lang`	`"pt"`	Idioma das mensagens de progresso.

Interpretando as Métricas de Desempenho

No modo de avaliação, a função retorna um tibble de métricas por estação. Entender o que cada métrica significa é fundamental para julgar se o preenchimento é adequado para o uso pretendido:

Métrica	Interpretação	O que esperar
RMSE	Erro quadrático médio na mesma unidade da variável. Penaliza erros grandes mais do que o MAE.	Temperatura: < 1,5 °C costuma ser aceitável. Precipitação: valores maiores são esperados.
MAE	Erro absoluto médio. Mais interpretável que RMSE: é literalmente ‘em média, erre X unidades’.	Temperatura: < 0,8 °C é bom. Vento: depende da variabilidade local.
R²	Proporção da variância da variável explicada pelo modelo. Varia de 0 a 1.	Temperatura: > 0,85 é excelente. Precipitação e vento: 0,5 já pode ser aceitável.
sMAPE	Erro percentual simétrico. Útil para comparar variáveis em escalas diferentes.	< 20% é bom para a maioria das variáveis meteorológicas.
slope_bias	Coeficiente angular da regressão predito ~ observado. Valor ideal: 1,0.	< 0,9 indica subestimação sistemática. > 1,1 indica superestimação.

⚠️ Atenção: Métricas ruins (R² < 0,5, sMAPE > 60%) para uma estação específica não necessariamente invalidam todo o conjunto de dados. Avalie estação por estação e considere excluir da análise aquelas com desempenho inaceitável, especialmente se a proporção de dados imputados for alta.

Exemplo Aplicado — Temperatura e Velocidade do Vento

Continuando o cenário do Amazonas: após inspecionar os dados, a pesquisadora identifica que tair_dry_bulb_c e ws_2_m_s têm lacunas em algumas estações. Ela decide primeiro avaliar a qualidade da imputação antes de aplicá-la em produção.

# ── Passo 1: avaliar a qualidade da imputação antes de aplicar ───────────────
avaliacao <- sus_climate_fill_inmet(
  df = df_ro,
  target_var = c("tair_dry_bulb_c", "ws_2_m_s"),
  run_evaluation = TRUE,
  gap_percentage = 0.20,  # simula 20% de falhas aleatórias
  parallel = TRUE,
  workers = 4,
  lang = "pt"
)

# Métricas por estação para temperatura
print(avaliacao$tair_dry_bulb_c$metrics)

# Métricas por estação para vento
print(avaliacao$ws_2_m_s$metrics)

# ── Passo 2: aplicar a imputação em produção (após validar as métricas) ──────
df_ro_filled <- sus_climate_fill_inmet(
  df = df_ro,
  quality_threshold = 0.7,
  target_var = c("tair_dry_bulb_c", "ws_2_m_s"),
  parallel = TRUE,
  workers = 4,
  lang = "pt"
)

`sus_climate_plot_fill()` — Diagnóstico Visual

A imputação de dados nunca deve ser aceita cegamente. Mesmo com boas métricas estatísticas, padrões visuais podem revelar problemas que os números não capturam: um modelo que imputa valores plausíveis em magnitude mas sem o ciclo diário correto, ou que produz valores constantes em blocos longos de falha.

A função sus_climate_plot_fill() oferece ferramentas visuais para inspecionar e comunicar a qualidade do preenchimento. Ela detecta automaticamente se recebeu dados de produção ou resultados de avaliação e adapta o gráfico adequadamente.

Dois Modos de Visualização

Modo	Entrada	O que exibe	Quando usar
Série temporal (produção)	`climasus_df` preenchido + `df_original`	Linha da série observada (com lacunas naturais) + segmentos imputados destacados em pontos e linha pontilhada. Com múltiplas estações, exibe um painel por estação.	Para comunicar onde e quanto foi imputado em um conjunto de dados real.
Dashboard de avaliação	Lista retornada por `sus_climate_fill_inmet` com `run_evaluation = TRUE`	Painel 2×2: dispersão observado vs. predito com linha 1:1 e R²; histograma de resíduos; resíduos ao longo do tempo; resíduos vs. observado.	Para julgar se a qualidade do modelo justifica o uso dos valores imputados.

Paletas de Cores Científicas

A função integra o pacote ggsci e oferece 28 paletas profissionais. A escolha da paleta é uma questão de estilo e contexto:

Categoria	Paletas disponíveis	Recomendação de uso
Revistas científicas	`npg`, `aaas`, `nejm`, `lancet`, `jama`, `bmj`, `jco`, `frontiers`, `gsea`	Para artigos científicos. `npg` (Nature) e `aaas` (Science) são os padrões mais reconhecidos.
Profissional/acadêmica	`uchicago`, `primer`, `atlassian`, `observable`	Para relatórios institucionais e apresentações.
Especializada	`d3`, `igv`, `cosmic`, `locuszoom`, `ucscgb`	Para contextos técnicos específicos.
Design moderno	`bs5`, `material`, `tw3`	Para dashboards interativos e comunicação ao público geral.
Criativa	`startrek`, `tron`, `futurama`, `simpsons`, `rickandmorty`, `flatui`	Para visualizações informais ou apresentações descontraídas.

Interpretando os Gráficos

No modo de série temporal

Linha azul (observado) — a série original com lacunas naturais. Os gaps aparecem como interrupções na linha
Pontos e linha pontilhada vermelha (imputado) — cada bloco de imputação consecutivo é conectado por uma linha pontilhada separada. Um ponto isolado indica um único horário imputado sem vizinhos imputados
O que observar: os valores imputados continuam o padrão da série? Eles seguem o ciclo diário? Não há saltos abruptos nas bordas dos gaps?

No dashboard de avaliação

Painel Obs vs. Pred — os pontos devem se alinhar próximos à linha 1:1 (tracejada). Afastamento sistemático indica viés. O R² e o RMSE no título resumem o ajuste
Histograma de resíduos — deve ser aproximadamente centrado em zero. Assimetria indica viés direcional
Resíduos ao longo do tempo — pontos aleatoriamente distribuídos em torno de zero indicam bom ajuste. Padrões sistemáticos sugerem que o modelo não captura alguma tendência temporal
Resíduos vs. observado — pontos aleatoriamente distribuídos indicam erros uniformes. Uma forma de funil (maior dispersão em valores extremos) indica heterocedasticidade

💡 Dica: A linha pontilhada que conecta pontos imputados só conecta pontos consecutivos na mesma estação. Gaps isolados aparecem como pontos únicos sem linha. Isso garante que a visualização não cria a ilusão de uma interpolação entre gaps distantes.

Exemplo Aplicado — Inspecionando a Imputação

# ── Modo de série temporal: produção ────────────────────────────────────────
# ggplot2 estático — todas as estações em painéis separados
p_static <- sus_climate_plot_fill(
  df_filled = df_ro_filled,
  df_original = df_ro,
  target_var = "tair_dry_bulb_c",
  interactive = FALSE,  # ggplot2
  color_palette = "npg",
  lang = "pt",
  output_type = "plot"
)

p_static

# plotly interativo — zoom e hover habilitados, subplots por estação
p_interactive <- sus_climate_plot_fill(
  df_filled = df_ro_filled,
  df_original = df_ro,
  target_var = "tair_dry_bulb_c",
  interactive = TRUE,  # plotly
  color_palette = "lancet",
  lang = "pt",
  output_type = "plot"
)

p_interactive

# Salvar o gráfico estático em arquivo
sus_climate_plot_fill(
  df_filled = df_ro_filled,
  df_original = df_ro,
  target_var = "tair_dry_bulb_c",
  interactive = FALSE,
  save_plot = "temperatura_imputacao_AM.png",
  lang = "pt"
)

# ── Modo de avaliação: dashboard diagnóstico ─────────────────────────────────
sus_climate_plot_fill(
  df_filled = avaliacao,  # lista retornada por sus_climate_fill_inmet(..., run_evaluation = TRUE)
  target_var = "tair_dry_bulb_c",
  interactive = FALSE,
  color_palette = "aaas",
  lang = "pt"
)

# ── Múltiplas variáveis simultaneamente ──────────────────────────────────────
sus_climate_plot_fill(
  df_filled = df_ro_filled,
  df_original = df_ro,
  target_var = c("tair_dry_bulb_c", "ws_2_m_s"),
  interactive = TRUE,
  color_palette = "jco",
  lang = "pt"
)

# ── Modo de série temporal: produção ────────────────────────────────────────
# ggplot2 estático — todas as estações em painéis separados
p_static <- sus_climate_plot_fill(
  df_filled = df_ro_filled,
  df_original = df_ro,
  target_var = "tair_dry_bulb_c",
  interactive = FALSE,  # ggplot2
  color_palette = "npg",
  lang = "pt",
  output_type = "plot"
)

p_static

# plotly interativo — zoom e hover habilitados, subplots por estação
p_interactive <- sus_climate_plot_fill(
  df_filled = df_ro_filled,
  df_original = df_ro,
  target_var = "tair_dry_bulb_c",
  interactive = TRUE,  # plotly
  color_palette = "lancet",
  lang = "pt",
  output_type = "plot"
)

p_interactive

# Salvar o gráfico estático em arquivo
sus_climate_plot_fill(
  df_filled = df_ro_filled,
  df_original = df_ro,
  target_var = "tair_dry_bulb_c",
  interactive = FALSE,
  save_plot = "temperatura_imputacao_AM.png",
  lang = "pt"
)

# ── Modo de avaliação: dashboard diagnóstico ─────────────────────────────────
sus_climate_plot_fill(
  df_filled = avaliacao,  # lista retornada por sus_climate_fill_inmet(..., run_evaluation = TRUE)
  target_var = "tair_dry_bulb_c",
  interactive = FALSE,
  color_palette = "aaas",
  lang = "pt"
)

# ── Múltiplas variáveis simultaneamente ──────────────────────────────────────
sus_climate_plot_fill(
  df_filled = df_ro_filled,
  df_original = df_ro,
  target_var = c("tair_dry_bulb_c", "ws_2_m_s"),
  interactive = TRUE,
  color_palette = "jco",
  lang = "pt"
)

# ── Modo de série temporal: produção ────────────────────────────────────────
# ggplot2 estático — todas as estações em painéis separados
p_static <- sus_climate_plot_fill(
  df_filled = df_ro_filled,
  df_original = df_ro,
  target_var = "tair_dry_bulb_c",
  interactive = FALSE,  # ggplot2
  color_palette = "npg",
  lang = "pt",
  output_type = "plot"
)

p_static

# plotly interativo — zoom e hover habilitados, subplots por estação
p_interactive <- sus_climate_plot_fill(
  df_filled = df_ro_filled,
  df_original = df_ro,
  target_var = "tair_dry_bulb_c",
  interactive = TRUE,  # plotly
  color_palette = "lancet",
  lang = "pt",
  output_type = "plot"
)

p_interactive

# Salvar o gráfico estático em arquivo
sus_climate_plot_fill(
  df_filled = df_ro_filled,
  df_original = df_ro,
  target_var = "tair_dry_bulb_c",
  interactive = FALSE,
  save_plot = "temperatura_imputacao_AM.png",
  lang = "pt"
)

# ── Modo de avaliação: dashboard diagnóstico ─────────────────────────────────
sus_climate_plot_fill(
  df_filled = avaliacao,  # lista retornada por sus_climate_fill_inmet(..., run_evaluation = TRUE)
  target_var = "tair_dry_bulb_c",
  interactive = FALSE,
  color_palette = "aaas",
  lang = "pt"
)

# ── Múltiplas variáveis simultaneamente ──────────────────────────────────────
sus_climate_plot_fill(
  df_filled = df_ro_filled,
  df_original = df_ro,
  target_var = c("tair_dry_bulb_c", "ws_2_m_s"),
  interactive = TRUE,
  color_palette = "jco",
  lang = "pt"
)

Pipeline Completo — Do Download à Validação

O código abaixo demonstra o fluxo de trabalho completo em um único script reprodutível, usando o cenário de pesquisa sobre clima e saúde respiratória no estado do Pará.

# =============================================================================
# Pipeline climasus4r — Pará 2023
# Objetivo: preparar dados climáticos para estudo clima-saúde respiratória
# =============================================================================

library(climasus4r)
library(dplyr)

# ── ETAPA 1: Obter dados do INMET ────────────────────────────────────────────
df_pa <- sus_climate_inmet(
  years = 2023,
  uf = "PA",
  parallel = TRUE,
  workers = 6,
  lang = "pt",
  verbose = TRUE
)

# Inspeção rápida
cat("Estações:", n_distinct(df_pa$station_code), "\n")
cat("Observações:", nrow(df_pa), "\n")
cat("Período:", format(range(df_pa$date)), "\n")

# Proporção de faltantes nas variáveis de interesse
df_pa |>
  summarise(across(c(tair_dry_bulb_c, rh_mean_porc, rainfall_mm),
                   ~ round(mean(is.na(.x)) * 100, 1),
                   .names = "pct_na_{.col}"))

# ── ETAPA 2: Avaliar a qualidade da imputação antes de produção ──────────────
eval_pa <- sus_climate_fill_inmet(
  df = df_pa,
  target_var = c("tair_dry_bulb_c", "rh_mean_porc", "rainfall_mm"),
  run_evaluation = TRUE,
  gap_percentage = 0.20,
  parallel = TRUE,
  lang = "pt"
)

# Checar R² e RMSE para temperatura
eval_pa$tair_dry_bulb_c$metrics |>
  select(station_id, rmse, mae, r_squared, smape) |>
  arrange(r_squared)

# ── ETAPA 3: Aplicar imputação em produção ───────────────────────────────────
# (somente após validar que as métricas são aceitáveis)
df_pa_filled <- sus_climate_fill_inmet(
  df = df_pa,
  target_var = c("tair_dry_bulb_c", "rh_mean_porc", "rainfall_mm"),
  parallel = TRUE,
  lang = "pt"
)

# ── ETAPA 4: Diagnóstico visual — série temporal ─────────────────────────────
sus_climate_plot_fill(
  df_filled = df_pa_filled,
  df_original = df_pa,
  target_var = "tair_dry_bulb_c",
  interactive = TRUE,
  color_palette = "lancet",
  lang = "pt"
)

# ── ETAPA 5: Diagnóstico visual — dashboard de avaliação ─────────────────────
sus_climate_plot_fill(
  df_filled = eval_pa,
  target_var = "tair_dry_bulb_c",
  interactive = FALSE,
  color_palette = "nejm",
  lang = "pt"
)

# ── ETAPA 6: Registrar metadados do processo ─────────────────────────────────
sus_meta(df_pa_filled)

Tabela Comparativa das Três Funções

Aspecto	sus_climate_inmet	sus_climate_fill_inmet	sus_climate_plot_fill
Papel no pipeline	Fonte de dados	Imputação de falhas	Diagnóstico visual
Entrada principal	Anos e UFs (argumentos)	`climasus_df` observado	`climasus_df` preenchido ou lista de avaliação
Saída principal	`climasus_df` padronizado	`climasus_df` com `is_imputed_*` ou lista de métricas	Gráfico ggplot2/plotly + tabela DT
Modelo interno	Pipeline de download, parsing, QC e cache	XGBoost com engenharia de features automática	Sem modelo; apenas visualização
Paralelismo	Entre anos e entre CSVs	Entre estações (furrr)	Não se aplica
Modos de operação	Único	Produção e avaliação	Série temporal e dashboard
Dependência de outra função	Nenhuma	Requer saída de `sus_climate_inmet`	Requer saída de `sus_climate_fill_inmet`
Formato da saída	`climasus_df` (subclasse de tibble)	`climasus_df` ou lista nomeada	Objeto ggplot2, plotly ou lista com plot + table + metrics

Boas Práticas e Erros Comuns

Boas Práticas

Sempre avalie antes de imputar — execute sus_climate_fill_inmet() com run_evaluation = TRUE antes de usar os dados em produção. Não assuma que um bom R² médio se aplica a todas as estações
Inspecione visualmente cada variável crítica — use sus_climate_plot_fill() para pelo menos uma estação representativa de cada região ou cluster geográfico
Documente a proporção imputada — sempre registre quantos dados foram imputados (pct_imputed na tabela de métricas) e inclua essa informação nos métodos do estudo
Use cache consistentemente — o parâmetro use_cache = TRUE é padrão por uma razão: downloads repetidos sobrecarregam os servidores do INMET e são desnecessários
Mantenha o df_original — guarde sempre o objeto bruto retornado por sus_climate_inmet(). Ele é necessário para sus_climate_plot_fill() e serve como referência de auditoria
Considere o quality_threshold — o padrão de 40% de NAs é uma regra equilibrada. Para análises onde a qualidade dos dados é crítica, considere quality_threshold = 0.3

Erros Comuns

Usar dados de outras fontes sem adaptação — sus_climate_fill_inmet() foi construída para os nomes de colunas do INMET. Usar com dados de outras redes meteorológicas sem renomear as colunas causará erros ou resultados incorretos
Ignorar o fuso horário — os dados retornados por sus_climate_inmet() estão em UTC. Se combinar com dados de saúde em horário local brasileiro (BRT = UTC−3), é necessário converter com lubridate::with_tz(df$date, "America/Manaus") ou equivalente para cada fuso
Confiar em métricas agregadas — um R² de 0,90 no conjunto de todas as estações pode esconder estações individuais com R² de 0,50. Sempre avalie por estação
Imputar precipitação sem cautela — precipitação horária é uma variável muito irregular (muitos zeros, eventos extremos raros). Valores imputados para chuva devem ser usados com mais cautela do que temperatura ou umidade
Não verificar os flags is_imputed_* — após a imputação, sempre filtre por is_imputed_tair_dry_bulb_c == TRUE para inspecionar os valores imputados. Nunca assuma que todos os valores na série são observados

Como Interpretar os Resultados na Prática

A execução correta do pipeline gera vários objetos com informações que precisam de interpretação ativa por parte do pesquisador. Esta seção guia as perguntas mais comuns:

O dashboard de avaliação parece bom, mas posso confiar na imputação?

Métricas favoráveis no modo de avaliação são uma condição necessária, mas não suficiente. Elas indicam que o modelo poderia ter acertado bem em falhas aleatórias. Na realidade, as falhas reais podem ter um padrão diferente (por exemplo, falhas em dias de tempestade, exatamente quando os valores seriam mais extremos). Por isso, combine as métricas com a inspeção visual: os segmentos imputados seguem o ciclo diário? Não há saltos abruptos nas transições?

Qual proporção de dados imputados é aceitável?

Não há uma resposta universal, mas uma referência prática: abaixo de 10% de dados imputados, o impacto na maioria das análises é negligenciável. Entre 10% e 30%, o impacto merece atenção e deve ser mencionado nos métodos. Acima de 30%, a série imputada pode dominar certas análises estatísticas e deve ser tratada com cautela ou até excluída de análises de sensibilidade.

O modelo de uma estação ficou ruim. O que fazer?

Primeiro, verifique a proporção de dados faltantes nessa estação. Se estiver próxima ou acima do quality_threshold, o modelo treinou com poucos dados e a baixa qualidade é esperada. Você tem três opções: (1) excluir essa estação da análise; (2) aumentar o quality_threshold para incluí-la, aceitando a incerteza; (3) usar uma interpolação espacial a partir de estações vizinhas.

Por que dois gaps próximos aparecem como pontos separados no gráfico?

A função sus_climate_plot_fill() conecta apenas pontos imputados consecutivos dentro da mesma estação. Se entre dois gaps existe ao menos uma observação real, eles são tratados como blocos distintos — o que é analiticamente correto. A linha não é meramente estética; ela representa a estrutura real dos blocos de imputação.

Perguntas Frequentes

Quando devo preencher falhas?

Sempre que sua análise depender de séries temporais completas ou de variáveis que precisam ser calculadas a cada hora. Se o objetivo for calcular médias mensais e a proporção de faltantes for baixa (< 5% por mês), a imputação pode não ser necessária. Se o objetivo for correlacionar dados horários com desfechos hospitalares na mesma janela temporal, a continuidade importa.

Como saber se o valor imputado é plausível?

Combine três verificações: (1) a métrica de RMSE no modo de avaliação está dentro do esperado para a variável e região? (2) o gráfico de série temporal mostra os valores imputados seguindo o ciclo diário e sazonal típico? (3) os valores imputados estão dentro de faixas históricas plausíveis para aquela estação?

Posso usar esses dados em análises de saúde sem mencionar a imputação?

Não. Boas práticas de pesquisa exigem que a proporção de dados imputados e o método de imputação sejam reportados na seção de métodos. Isso permite que leitores e revisores avaliem a influência da imputação nas conclusões.

A função funciona com dados de outras fontes (CEMADEN, INPA, WMO)?

A função sus_climate_fill_inmet() foi projetada para os 17 nomes de variáveis canônicos do INMET. Dados de outras fontes precisam ter as colunas renomeadas para os mesmos nomes antes do uso.

Conclusão e Recomendações

O pipeline formado por sus_climate_inmet(), sus_climate_fill_inmet() e sus_climate_plot_fill() oferece ao pesquisador de epidemiologia climática uma cadeia de trabalho completa, reprodutível e auditável — desde os dados brutos do INMET até a comunicação visual da qualidade da imputação.

As principais forças do pipeline são a padronização automática das variáveis, o controle de qualidade físico embutido, a modelagem independente por estação que respeita microclimas locais, e a visualização que distingue claramente dados observados de dados imputados.

As principais limitações a ter em mente são: a função foi projetada para o INMET e não é imediatamente portável para outras redes; a imputação de precipitação é intrinsecamente mais incerta do que temperatura; e falhas concentradas em períodos específicos (como eventos extremos) são mais difíceis de imputar do que falhas aleatórias.

A recomendação final é: sempre avalie antes de imputar, sempre inspecione visualmente os resultados, e sempre documente o que foi imputado. Dados climáticos de alta qualidade são um pré-requisito para análises de saúde ambiental confiáveis. O pipeline do climasus4r foi construído para ajudar nesse caminho.

Referências e Recursos Adicionais

Abrir issue no GitHub

sus_climate_inmet • sus_climate_fill_inmet • sus_climate_plot_fill

Max Anjos

09 de May de 2026

Introdução e Motivação

Visão Geral do Pipeline

sus_climate_inmet() — Obtendo Dados do INMET

O que a função faz

Parâmetros Principais

Variáveis Retornadas

Controle de Qualidade Automático

Sistema de Cache

Exemplo Aplicado — Pesquisa no Amazonas

sus_climate_fill_inmet() — Preenchendo Falhas com XGBoost

Por que preencher falhas?

Como o modelo funciona

Modo de Produção e Modo de Avaliação

Parâmetros Principais

Interpretando as Métricas de Desempenho

Exemplo Aplicado — Temperatura e Velocidade do Vento

sus_climate_plot_fill() — Diagnóstico Visual

Dois Modos de Visualização

Paletas de Cores Científicas

Interpretando os Gráficos

No modo de série temporal

No dashboard de avaliação

Exemplo Aplicado — Inspecionando a Imputação

Pipeline Completo — Do Download à Validação

Tabela Comparativa das Três Funções

Boas Práticas e Erros Comuns

Boas Práticas

Erros Comuns

Como Interpretar os Resultados na Prática

O dashboard de avaliação parece bom, mas posso confiar na imputação?

Qual proporção de dados imputados é aceitável?

O modelo de uma estação ficou ruim. O que fazer?

Por que dois gaps próximos aparecem como pontos separados no gráfico?

Perguntas Frequentes

Quando devo preencher falhas?

Como saber se o valor imputado é plausível?

Posso usar esses dados em análises de saúde sem mencionar a imputação?

A função funciona com dados de outras fontes (CEMADEN, INPA, WMO)?

Conclusão e Recomendações

Referências e Recursos Adicionais

`sus_climate_inmet()` — Obtendo Dados do INMET

`sus_climate_fill_inmet()` — Preenchendo Falhas com XGBoost

`sus_climate_plot_fill()` — Diagnóstico Visual