Introdução

O pacote febr (/ˈfɛ.bɾe/) para R (R Core Team 2017) foi criado para facilitar o acesso aos dados dos conjuntos de dados publicados no Repositório Brasileiro Livre para Dados Abertos do Solo (febr). Ele pode ser descarregado do CRAN da seguinte maneira:

install.packages("febr")

Já a versão de desenvolvimento, disponível no GitHub, pode ser instalada – usando o pacote devtools (Wickham e Chang 2017) – da seguinte maneira:

if (!require(devtools)) {
  install.packages(pkgs = "devtools")
}
devtools::install_github(repo = "febr-team/febr-package")

O pacote febr possui três grupos de funções: as funções estruturais, as funções de acesso, e as funções auxiliares – veja tabela abaixo. Uma demonstração básica da forma de uso e aplicações dessas funções é apresentada nas próximas seções.

Funções estruturais

As funções estruturais servem para conhecer a estrutura das tabelas dos conjuntos de dados publicados no febr. Elas também servem para conhecer os padrões de codificação, nomenclatura, unidades de medida e número de casas decimais usados no febr. Todas as funções estruturais são construídas sobre funções do pacote googlesheets (Bryan e Zhao 2018).

A função header (do inglês, header, para cabeçalho) serve para descarregar o cabeçalho – as duas primeiras linhas – de uma das duas tabelas de dados – observacao ou camada – dos conjuntos de dados. Isso permite verificar quais são as variáveis incluídas nos conjuntos de dados, os códigos de identificação utilizados, e as respectivas unidades de medida. Por exemplo, o cabeçalho completo da tabela camada do conjunto de dados ctb0003 é descarregado da seguinte maneira:

cab <- febr::header(dataset = "ctb0003", table = "camada", variable = "all")

A função standard (do inglês, standard, para padrão) fornece uma interface para descarregar informações sobre os padrões usados para as variáveis incluídas nas tabelas observacao e camada de todos os conjuntos de dados. Isso inclui a codificação e nomenclatura, a descrição de cada variável, a unidade de medida e o número de casas decimais, o tipo de dado, e a categoria da variável. Tais informações estão organizadas numa planilha disponível em https://goo.gl/hi77sB. Por exemplo, caso tenhamos interesse em conhecer os padrões usados no febr para as variáveis argila, densidade, carbono e ph, basta usar o seguinte código:

pad <- febr::standard(variable = c("argila", "densidade", "carbono", "ph"))

A função unit (do inglês, unit, para unidade) serve de interface para uma planilha – disponível em https://goo.gl/Vvvsf2 – contendo diversas unidades de medida e as constantes utilizadas para a conversão dos dados entre elas. Essas informações são úteis durante o descarregamento dos dados usando as funções observation e layer – veja mais abaixo. Por exemplo, a densidade do solo é comumente expressa em Mg/m^3 e kg/dm^3. Para descarregar as constantes de transformação entre essas duas unidades de medida, basta usar o seguinte código:

uni <- febr::unit(source = "Mg/m^3", target = "kg/dm^3")

Funções de acesso

As funções de acesso servem para descarregar os dados e metadados dos conjuntos de dados publicados no febr. Isso inclui as tabelas dataset, observacao, camada, e metadado. Assim como as funções estruturais, as funções de acesso também são construídas sobre funções do pacote googlesheets (Bryan e Zhao 2018).

Os dados sobre um ou mais conjuntos de dados, contidos na tabela dataset (do inglês, dataset, para conjunto de dados), podem ser descarregados usando uma função de mesmo nome. Para isso, basta informar o código de identificação do(s) conjunto(s) de dados que se deseja descarregar – conforme catalogado em http://www.ufsm.br/febr/catalog/ –, por exemplo:

conj <- febr::dataset(dataset = c("ctb0003", "ctb0036"))

Já os dados sobre os dados contidos em um ou mais conjuntos de dados, armazenados na tabela metadado, podem ser descarregados usando a função metadata (do inglês, metadata, para metadados), por exemplo:

meta <- febr::metadata(dataset = c("ctb0003", "ctb0036"))

Os dados das observações do solo, contidos na tabela observacao, podem ser descarregados usando a função observation (do inglês, observation, para observação). Assim como as funções header e standard vistas acima, a função observation também possui o argumento variable, que permite selecionar as variáveis que devem ser retornadas. Por exemplo, para retornar apenas a variável taxon do conjunto de dados ctb0003, usamos o seguinte código:

obs <- febr::observation(dataset = "ctb0003", variable = "taxon")

A função layer (do inglês, layer, para camada) serve para descarregar os dados contidos na tabela camada dos conjunto de dados. Por exemplo, para descarregar os dados da tabela camada dos conjuntos de dados ctb0003 e ctb0036, retornando apenas as variáveis argila, carbono e densidade, usamos o seguinte código:

cam <- febr::layer(dataset = c("ctb0003", "ctb0036"), variable = c("argila", "carbono", "densidade"))

A última função de acesso é febr. Ela serve para descarregar todos os dados e metadados de um único conjunto de dados. Essa função aceita os mesmos argumentos das funções observation e layer – que são idênticos devido à similaridade da estrutura das tabelas observacao e camada. Assim, como naquelas funções, é possível solicitar que os dados passem por uma rotina de limpeza e padronização:

tudo <- febr::febr(
  dataset = "ctb0003", variable = "all", merge = TRUE, 
  missing = list(coord = "drop", time = "drop", depth = "drop"),
  standardization = list(
    crs = "EPSG:4674", time.format = "%Y-%m-%d",
    repetition = "combine", combine.fun = "mean",
    transition = "smooth", smoothing.fun = "mean",
    plus.sign = "add", plus.depth = 2.5,
    lessthan.sign = "subtract", lessthan.frac = 0.1,
    units = TRUE, round = TRUE))

Funções auxiliares

As funções auxiliares servem para realizar tarefas complementares às funções estruturais e de acesso, assim apoiando o processamento e uso dos dados descarregados do febr, por exemplo, a criação de objetos de outras classes e a exportação dos dados.

A função febr2spdf serve para criar um objeto de classe SpatialPointsDataFrame (Pebesma e Bivand 2005) a partir da tabela observacao descarregada usando a função observation. O código a seguir demonstra como fazer isso – note que as funções do pacote febr são compatíveis com o uso do operador %>% do pacote magrittr (Bache e Wickham 2014):

library(magrittr)
obs <- 
  febr::observation(dataset = "ctb0003", variable = "taxon") %>% 
  febr::febr2spdf()

Já a função febr2xlsx – construída sobre funções do pacote xlsx (Dragulescu 2014) – serve para escrever os dados de um conjunto de dados para um arquivo XLSX no disco rígido. No caso específico da função febr, que retorna um objeto de classe list composto de itens de classe data.frame, a função febr2xlsx escreve cada um dos data.frames em uma planilha individual do mesmo arquivo XLSX. Por exemplo,

tudo <- 
  febr::febr(dataset = "ctb0003", variable = "all") %>% 
  febr::febr2xlsx(file = "ctb0003.xlsx")

A terceira função auxiliar do pacote febr é goto. A função goto serve de interface para navegação nas diversas páginas na Internet do febr: página principal, visualização geográfica, catálogo de conjuntos de dados, página de busca, manual do mantenedor, pacote para R, GitHub, fórum de discussão, e tabelas com padrões de unidades de medida e de codificação e nomenclatura. Além disso, a função goto serve para visitar as tabelas dos conjuntos de dados. Por exemplo, para visitar a tabela camada do conjunto de dados ctb0036, usamos o seguinte código:

febr::goto(dataset = "ctb0036", table = "camada")

Novas funções auxiliares podem ser criadas à medida que as usuárias do pacote febr apontarem a sua necessidade. Alternativamente, as usuárias são encorajadas a submeter funções auxiliares para inclusão no pacote febr seguindo o modelo de desenvolvimento colaborativo fork & pull.