Introduction to irpfR

The irpfR package provides a high-level interface to access and clean the Personal Income Tax (IRPF) Open Data from the Brazilian Federal Revenue (Receita Federal do Brasil). This vignette demonstrates the typical workflow: discovering available datasets, understanding their attributes through built-in metadata, and downloading cleaned data for analysis.

1. Discovering Available Data

The Brazilian Federal Revenue publishes data in several “sections” (e.g., assets, debts, income brackets). You can list all sections currently supported by the package using get_sections():

library(irpfR)

# List available datasets
sections <- get_sections()
#> Fetching available sections for IRPF data...
head(sections)
#> # A tibble: 6 × 2
#>   secao                                 descricao                               
#>   <chr>                                 <chr>                                   
#> 1 bens_e_direitos                       Números das Declarações do Imposto de R…
#> 2 faixa_de_base_de_calculo_anual        Resumo das declarações por faixa de bas…
#> 3 rendimentos_isentos_e_nao_tributaveis Agregado dos rendimentos isentos e não …
#> 4 residencia_capital                    Resumo das declarações dos contribuinte…
#> 5 dividas_e_onus                        Total de valores declarados por tipo de…
#> 6 residencia_uf                         Resumo das declarações dos contribuinte…

2. Inspecting Metadata

Government CSV files often have cryptic column names or complex tax definitions. To understand the content of a section before downloading it, use get_metadata():

# Get descriptions for the "Assets and Rights" (Bens e Direitos) section
metadata <- get_metadata("bens_e_direitos")
#> Fetching metadata for section: 'bens_e_direitos'...
head(metadata)
#> # A tibble: 6 × 2
#>   atributo                                              descricao               
#>   <chr>                                                 <chr>                   
#> 1 ano_calendario                                        Informa o ano calendári…
#> 2 acoes_inclusive_as_provenientes_de_linha_telefonica   Ações declaradas como b…
#> 3 aeronave                                              Aeronaves declaradas.   
#> 4 apartamento                                           Apartamentos declarados.
#> 5 aplicacao_de_renda_fixa_cdb_rdb_e_outros              Aplicações de renda fix…
#> 6 bem_relacionado_com_o_exercicio_da_atividade_autonoma Bens de atividade autôn…

3. Downloading and Cleaning Data

The core function of the package is get_irpf(). It performs several automated engineering tasks:

Download: Connects to the RFB servers and handles the file transfer.
Encoding: Corrects UTF-8/Latin1 issues common in Brazilian government files.
Tidying: Converts “wide” tables into a “long” (tidy) format, making them ready for ggplot2 or dplyr.
Smart Scaling: Financial values are converted from millions to absolute BRL, while counts (like number of taxpayers) remain as raw integers.

# Download data for "Assets and Rights"
df_bens <- get_irpf("bens_e_direitos")
#> Accessing Brazilian Federal Revenue database for section: 'bens_e_direitos'...
#> Downloading file (this may take a while depending on your connection)...
#> Download complete! Cleaning and structuring data...
#> Data ready for analysis!

# The resulting data is tidy
# Columns: ano_calendario, atributo, valor
head(df_bens)
#> # A tibble: 6 × 3
#>   ano_calendario atributo                                                  valor
#>            <dbl> <chr>                                                     <dbl>
#> 1           2020 acoes_inclusive_as_provenientes_de_linha_telefonica     6.17e11
#> 2           2020 aeronave                                                3.87e 9
#> 3           2020 apartamento                                             1.61e12
#> 4           2020 aplicacao_de_renda_fixa_cdb_rdb_e_outros                8.51e11
#> 5           2020 bem_relacionado_com_o_exercicio_da_atividade_autonoma   6.02e 9
#> 6           2020 benfeitorias                                            3.75e10

Why use irpfR?

Directly reading raw files from the government portal can be challenging due to inconsistent decimal marks (using commas), non-standard NA characters (like - or *), and varying numerical scales.irpfR encapsulates all these rules, allowing researchers to focus on the economic analysis rather than data cleaning.