In lhmet/inmetwrangler: Functions to Wrangle Data Files from INMET Weather Stations

Os arquivos de dados horários das Estações Meteorológicas Automáticas (EMA) do INMET são disponibilizados em formato texto (ASCII). É comum em dados armazenados em formato texto, mesmo temporariamente, que algum procedimento de formatação manual seja realizada.

A estrutura de armazenamento de dados mais comum em arquivos texto com dados meteorológicos é a retangular, onde as observações ao longo das linhas e as variáveis ao longo das colunas. Eventualmente, os arquivos são editados manualmente e esse padrão pode ser quebrado, mesmo despropositadamente. Então uma da observação (linha) pode não conter os campos de todas as variáveis meteorológicas (colunas).

Analogamente, podem ocorrer descontinuidades temporais nas observações. Por exemplo, a observação na linha seguinte ao horário 2000-01-01 16:00:00 pode ser referente ao horário 2000-01-01 19:00:00, ou seja há 2 horários faltantes entre essas 2 observações. Logo os dados não estão regularmente espaçados no tempo.

Para garantir um conjunto de dados temporalmente consistente os horários faltantes devem explicitamente inseridos na variável temporal adequada (e.g. date) e as variáveis meteorológicas (colunas) preenchidas com um valor definido para identificar dados faltantes (e.g: NA, -9999). Dessa forma, cada ano de dados ter-se-á 365 (ou 366) dias/ano $\times$ 24 horas/dia $=$ r 365*24 (r 366*24) observações.

A seguir mostra-se como usar o pacote inmetwrangler para importar os dados das EMA do INMET e diagnosticar onde (arquivos, linhas e colunas) ocorrem estes problemas. Esta informação pode servir para verificação dos dados com a agência que forneceu os dados, para descartar a hipótese de algum problema na extração dos dados ou na operação manual dos arquivos texto.

Pré-requisitos

Instalação do pacote inmetwrangler:

library(devtools)
install_github("lhmet/inmetwrangler")

library(inmetwrangler)

knitr::opts_chunk$set(comment = "#>")

Outros pacotes necessários para reproduzir os exemplos mostrados a seguir:

library(knitr)
library(tidyverse)
library(stringr)

Dados

Os dados dos exemplos abaixo são disponibilizados com o próprio pacote inmetwrangler, no diretório de instalação do pacote. Os arquivos disponibilizados são:

#.libPaths()
# arquivos disponíveis
list.files(system.file("extdata", package = "inmetwrangler"
                       #, full.names = TRUE)
))

O caminho para um arquivo de dados pode ser obtido da seguinte forma:

system.file("extdata", "A838.txt", package = "inmetwrangler")

library(dplyr)
system.file("extdata", "A838.txt", package = "inmetwrangler") %>%
  stringr::str_replace_all(.libPaths()[1], "~/.R")
detach(package:dplyr)

Arquivos com cabeçalho variável

Os arquivos de dados horários das EMA tem um cabeçalho que pode ocupar de 2 a 4 linhas. Essa variação no formato dos arquivos pode ser devido a forma como os dados foram extraídos do banco de dados ou dependente do técnico responsável pelo banco de dados.

Os arquivos disponibilizados com o pacote são exemplos de arquivos com diferentes cabeçalhos^[O cabeçalho inclui o comando SQL usado para extração dos dados a partir do banco de dados.].

Arquivo com 4 linhas de cabeçalho sendo a 1ª observação apendada na última linha do cabeçalho

ex_file_h4 <- system.file("extdata", "A819.txt", package = "inmetwrangler")
head(read_lines(ex_file_h4))

Arquivo com 3 linhas de cabeçalho seguida de uma linha (4ª) em branco

ex_file_h3 <- system.file("extdata", "A804.txt", package = "inmetwrangler")
head(read_lines(ex_file_h3))

Arquivo com 1 linha de cabeçalho seguida de uma linha (2ª) em branco

ex_file_h2 <- system.file("extdata", "A852.txt", package = "inmetwrangler")
head(read_lines(ex_file_h2))

Detectando problemas

A função import_txt_files_inmet() além de importar os arquivos de dados horários considerando os diferentes cabeçalhos dos arquivos, também é usada para diagnosticar problemas na estrutura dos dados.

Caso 1: menos variáveis do que o esperado

Conforme nota técnica do INMET os arquivos devem conter 23 variáveis meteorológicas (especificadas na seção IMPORTANDO DADOS), uma com identificador da EMA e 4 com informação do ano, mês, dia e hora (UTC); totalizando 28 colunas. Mas nos arquivos ASCII fornecidos há uma coluna adicional com o símbolo "=". Então o total esperado de colunas nos arquivos texto é de 29 colunas^[A coluna excedente é desconsiderada na saída da função import_txt_files_inmet(), mas para diagnóstico de problemas ela é considerada.].

myfile <- system.file("extdata", "A838.txt", package = "inmetwrangler")
A838_problems <- import_txt_files_inmet(files = myfile, 
                                        verbose = FALSE,
                                        only.problems = TRUE, 
                                        full.names = TRUE)
kable(A838_problems)

A tabela de dados mostrada é auto-explicativa, mas é importante notar a diferença entre row (linha nos dados importados no R) e row_file (linha no arquivo ASCII). Foram encontradas r nrow(A838_problems) observações com menor n° de variáveis que o esperado. Esperavam-se 29 variáveis para a observação da linha 9712 (9741), entretanto, o arquivo contém apenas 14 (24) variáveis naquela linha.

Para verificar no arquivo original é possível abri-lo em um editor de texto, ou executar os comandos abaixo em que importamos o arquivo da EMA de interesse (myfile) e filtrarmos os dados entre uma linha acima (ir - 1) e uma abaixo (ir + 1) da linha com problema (ir).

for (i in 1:nrow(A838_problems)) {
  cat(" ------------", "Problem ", i, " ------------", "\n")
  ir <- A838_problems$row_file[i]
  print(read_lines(file = myfile)[(ir - 1):(ir + 1)])
}

Caso 2: mais variáveis do que o esperado

myfile <- system.file("extdata", "A852.txt", package = "inmetwrangler")
myfile
A852_problems <- import_txt_files_inmet(files = myfile, 
                                        verbose = FALSE,
                                        only.problems = TRUE)
kable(A852_problems)

Foram encontradas r nrow(A852_problems) observações com mais variáveis do que o esperado (29). Essas linhas são consecutivas, desde a linha r min(A852_problems$row_file) no arquivo original até a linha r max(A852_problems$row_file).

Caso 3: arquivos sem problemas

Quando os arquivos importados não apresentarem problemas a tabela com os problemas estará vazia. Então a função import_txt_files_inmet quando usada para detectar problemas (import_txt_files_inmet(..., only.problems = TRUE)) retornará informação somente sobre os arquivos com problemas (caso eles os tenham).

txt_files <- list.files(system.file("extdata", 
                                package = "inmetwrangler"),
                    full.names = TRUE) 
txt_files_no_prob <- discard(txt_files, ~str_detect(.x, "A852|A838"))
# somente arquivos sem problemas estruturais
basename(txt_files_no_prob)
probs <- import_txt_files_inmet(txt_files_no_prob, 
                       verbose = FALSE, 
                       only.problems = TRUE, 
                       full.names = FALSE)
probs
str(probs)

Importando os arquivos de dados

A função import_txt_files_inmet() importa arquivos de dados horários dando conta das diferenças de cabeçalhos dos arquivos e preenche (ou remove) as variáveis de uma observação com campos incompletos (excedentes).

# merge data files
hdata <- import_txt_files_inmet(files = txt_files, verbose = FALSE)
kable(head(hdata[, 1:10]))
kable(tail(hdata[, 1:10]))

## Gráficos
#The figure sizes have been customised so that you can easily put two images side-by-side. 
nsites <- length(unique(hdata$site))
timePlot(hdata, 
         "prec", 
         type = "site", 
         plot.type = "h", 
         layout = c(1, nsites),
         date.format = "%b\n%Y")