# 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.