tidy_balance_sheets: Process and reshape balances CSV exports from the Brazilian...

In bacenR: Access Data from Brazilian Central Bank: IFdata, Active Institutions, Balance Sheets and Normative Acts

Process and reshape balances CSV exports from the Brazilian Central Bank (Bacen) downloaded via get_balance_sheets().

Description

tidy_balance_sheets reads raw CSV export files produced by the BCB and downloaded via get_balance_sheets(), normalizes filenames, locates the header row, imports rows matching a specific document number, cleans column names, pivots account balances so that each account becomes a column and each row corresponds to an institution/date, and optionally writes per-institution-type CSVs.

Usage

tidy_balance_sheets(path_raw, out_dir, doc_filter = 4010, save = TRUE)

Arguments

path_raw	Character scalar. Directory containing the raw CSV files. Filenames are expected to start with a YYYYMM prefix (e.g. "202012COOPERATIVAS.CSV"). The function will look for files matching "\.CSV$" (case-insensitive).
out_dir	Character scalar. Directory where output CSVs will be saved when save = TRUE. If it does not exist it will be created.
doc_filter	Numeric or integer scalar. The numeric value used to filter rows in the imported tables by the column DOCUMENTO (e.g. 4010). Other options are: 4010, 4413, 4423, 4433, 4060, 4016 and 4066. Check the webpage for more details: BCB balance page
save	Logical scalar. If TRUE (default) the processed data frames are also written to disk as CSV files (one per institution type). If FALSE the function only returns the processed data.frames.

Details

Behavior and implementation notes:

• Filenames are first normalized by removing all underscores. If a target filename after normalization already exists, the function aborts to avoid overwriting files.

• The function extracts year/month and an institution type token from the file basename by assuming the first six characters are YYYYMM and the remaining characters (without the ".CSV") represent the type.

• For each file the function reads the file as text and attempts to locate the header row by scanning lines until it finds a row that contains (case-insensitive) tokens matching:

  • "DOCUMENTO" (or "DOCUMENTOS"),

  • "CNPJ",

  • and "DATA BASE" (variants matched by regex such as "DATA_BASE" or "#DATA_BASE"). The delimiter for that header line is heuristically detected among semicolon (";"), comma (","), or whitespace. For whitespace-delimited data the function uses read.table's default behavior.

• After locating the header, the table is read with utils::read.table using header = TRUE, the detected separator, latin1 encoding, and check.names = FALSE. Rows where the DOCUMENTO column equals doc_filter are kept.

• Column names are cleaned via janitor::clean_names() before the wide pivot. The function expects at least the following cleaned column names to be present: conta, saldo, and data. The pivot uses the id columns (data, documento, cnpj, nome_instituicao), conta as names and saldo as values.

• If save = TRUE each resulting data.frame is written to CSV using readr::write_csv() to the path returned by output_filename(type_inst) (wrapped with out_dir).

• The function will stop with informative errors in several situations: missing CSVs in path_raw, failure to find a header line with the required tokens, missing required columns after import/cleaning, or failure to rename files when removing underscores.

Value

A named list of data.frames (one element per unique institution type detected in the filenames). Each data.frame has one row per unique combination of (data, documento, cnpj, nome_instituicao) and one column per account (the "conta" values) with balances populated from the "saldo" column.

Note

The function prints a message reminding that the numeric values in the balance sheets are not adjusted for inflation. See: https://www.bcb.gov.br/estabilidadefinanceira/balancetesbalancospatrimoniais

Examples

# First, download balance sheets
get_balance_sheets(
  institution = "BANCOS",
  months = 12,
  first_year = 2023,
  final_year = 2023,
  out_dir = tempdir(),
  overwrite = FALSE
)

# Now, tidy the files
# Do not write outputs
tidy_balance_sheets(
  path_raw = tempdir(),
  out_dir = tempdir(),
  doc_filter = 4010,
  save = FALSE
)

# Write outputs
tidy_balance_sheets(
  path_raw = tempdir(),
  out_dir = tempdir(),
  doc_filter = 4016,
  save = TRUE
)

bacenR documentation built on Oct. 24, 2026, 1:07 a.m.