Introduction to sidra package

library(sidra)

Introdução

O pacote sidra fornece uma interface simples para acessar a API de dados do SIDRA (Sistema IBGE de Recuperação Automática), permitindo que você consulte dados do IBGE diretamente do R, a partir da api rest tornada disponível em servicodados.ibge.gov.br.

Este documento fornece uma introdução ao pacote e apresenta exemplos básicos para ajudá-lo a começar.

Instalação

Para instalar o pacote diretamente do GitHub, utilize o código abaixo:

# Instalar remotes, se necessário
# install.packages("remotes")

# Instalar o pacote sidra
remotes::install_github("rodrigoesborges/sidra")

Após a instalação, carregue o pacote com:

library(sidra)

Funções Principais

O pacote sidra contém diversas funções para acessar diferentes seções da API SIDRA. Abaixo, uma descrição das funções principais.

Função sidra()

Esta é a função principal do pacote, que permite fazer consultas gerais à API SIDRA com diversos parâmetros. Use esta função para acessar dados diretamente especificando a tabela, variáveis, classificadores, períodos e níveis geográficos.

sidra(tabela, classificador = "", filtro_cats = "", nivel = 1, filtro_niveis = "all", periodo = "all", variavel = "allxp", inicio = NULL, fim = NULL)
    tabela: Número da tabela desejada.
    classificador: Classificador a ser detalhado. O padrão retorna todos os classificadores disponíveis.
    filtro_cats: Define subconjunto do classificador.
    nivel: Define o nível geográfico, por exemplo, N1 para Brasil, N6 para Município.
    filtro_niveis: Define um subconjunto do nível especificado.
    periodo: Período dos dados; "all" para todos os períodos disponíveis.
    variavel: Variáveis a serem retornadas; "allxp" exclui variáveis calculadas pela SIDRA.
    inicio, fim: Início e fim do período desejado.

Funções para Classificações (tab_class.R)

Essas funções retornam informações sobre classificações disponíveis para uma tabela específica, incluindo os códigos de classificadores.

tab_class(tabela): Retorna classificações disponíveis para uma tabela específica.
    tabela: Número da tabela de interesse.

Funções para Fonte dos Dados (tab_fonte.R)

Essa função retorna a fonte dos dados, i.e. a Pesquisa primária fonte, para uma tabela específica, permitindo entender a origem e confiabilidade dos dados.

tab_fonte(tabela): Retorna a fonte de dados para a tabela especificada.
    tabela: Número da tabela de interesse.

Funções para Metadados da Tabela (tab_meta.R)

Essas funções fornecem metadados sobre uma tabela específica, oferecendo informações detalhadas sobre o conteúdo da tabela.

tab_meta(tabela): Retorna metadados para uma tabela específica.
    tabela: Número da tabela de interesse.

Funções para Níveis Geográficos (tab_niveis.R)

Essas funções retornam informações sobre os níveis geográficos disponíveis para uma tabela, como Brasil, Região, Estado, ou Município.

tab_niveis(tabela): Retorna níveis geográficos disponíveis para a tabela especificada.
    tabela: Número da tabela de interesse.

Funções para Períodos (tab_periodos.R)

Essas funções permitem listar os períodos disponíveis para uma tabela, como anos ou meses, dependendo da periodicidade dos dados.

tab_periodos(tabela): Retorna os períodos disponíveis para a tabela especificada.
    tabela: Número da tabela de interesse.

Funções para Variáveis (tab_vars.R)

Essas funções listam as variáveis disponíveis em uma tabela específica, como diferentes métricas ou indicadores que podem ser selecionados.

tab_vars(tabela): Retorna variáveis disponíveis para a tabela especificada.
    tabela: Número da tabela de interesse.

Exemplos de Uso

Aqui estão exemplos de como usar essas funções para consultar dados específicos na API SIDRA.

Listar Classificações

Para listar as classificações disponíveis para uma tabela específica, como a tabela 1612:

classificacoes <- tab_class(1612)
print(classificacoes)

Para obter a fonte dos dados de uma tabela específica:

Obter Fonte dos Dados

fonte <- tab_fonte(1612)
print(fonte)

Obter Metadados da Tabela

Para acessar os metadados de uma tabela específica, como a tabela 1612:

metadados <- tab_meta(1612)
print(metadados)

Listar Níveis Geográficos

Para listar os níveis geográficos disponíveis para a tabela 1612:

niveis <- tab_niveis(1612)
print(niveis)

Listar Períodos Disponíveis

Para listar os períodos disponíveis para a tabela 1612:

periodos <- tab_periodos(1612)
print(periodos)

Listar Variáveis Disponíveis

Para listar as variáveis disponíveis para uma tabela específica, como a tabela 1612:

variaveis <- tab_vars(1612)
print(variaveis)

Consultar Dados Específicos com sidra()

A função sidra() permite fazer consultas específicas de dados. Neste exemplo, buscamos dados da tabela 1612, com o classificador 81, no nível geográfico de Estados.

dados <- sidra(1612, classificador = 81, nivel = 3)
head(dados)

Avisos e Dicas

Limites de consulta: Algumas consultas podem exceder o limite de 100.000 registros permitido pela API do IBGE. Nesse caso, por definição o pacote busca dividir a consulta em requisições menores a partir de segmentação dos períodos requisitados. Ainda que robusto, pode não funcionar para todos os casos, pelo qual sugerimos faça a segmentação manualmente da requisição se necessário.

Níveis e Classificadores: Ao utilizar filtro_niveis ou filtro_cats, certifique-se de que eles tenham o mesmo tamanho do argumento nivel ou classificador, respectivamente.

Conclusão

O pacote sidra facilita a consulta aos dados do IBGE, possibilitando um fluxo de trabalho mais ágil para análises de dados diretamente no R. Para maiores informações, visite a documentação da API SIDRA e explore as funções adicionais do pacote.

Esperamos que esta vignette ajude você a começar a usar o sidra e realizar análises com dados do IBGE.

Rodrigo E. S. Borges