Package {censobr}

Type:	Package
Title:	Download Data from Brazil's Population Census
Version:	1.0.0
Description:	Easy access to data from Brazil's population censuses. The package provides a simple and efficient way to download and read the data sets and the documentation of all the population censuses taken in and after 1960 in the country. The package is built on top of the 'Arrow' platform https://arrow.apache.org/docs/r/, which allows users to work with larger-than-memory census data using 'dplyr' familiar functions. https://arrow.apache.org/docs/r/articles/arrow.html#analyzing-arrow-data-with-dplyr.
License:	MIT + file LICENSE
URL:	https://github.com/ipea/censobr, https://ipea.github.io/censobr/
BugReports:	https://github.com/ipea/censobr/issues
Depends:	R (≥ 4.1.0)
Imports:	arrow (≥ 15.0.1), checkmate, cli, dplyr, duckdb, fs, glue, httr2 (≥ 1.0.0), rlang, tools
Suggests:	covr, DBI, dbplyr, geobr (≥ 2.0.1), ggplot2 (≥ 3.3.1), rmarkdown, kableExtra, knitr, scales, testthat, withr
VignetteBuilder:	knitr
Encoding:	UTF-8
Config/roxygen2/version:	8.1.0
Config/testthat/edition:	3
NeedsCompilation:	no
Packaged:	2026-09-19 00:47:58 UTC; rafap
Author:	Rafael H. M. Pereira [aut, cre], Rogério J. Barbosa [aut], Pedro Herculano Souza [ctb], Diego Rabatone Oliveira [ctb], Neal Richardson [ctb], Haydee Svab [ctb], Ipea - Institute for Applied Economic Research [cph, fnd]
Maintainer:	Rafael H. M. Pereira <rafa.pereira.br@gmail.com>
Repository:	CRAN
Date/Publication:	2026-09-21 10:00:34 UTC

censobr: Download Data from Brazil's Population Census

Description

Download data data from Brazil's population Census.

Usage

Please check the vignettes and data documentation on the website.

Author(s)

Maintainer: Rafael H. M. Pereira rafa.pereira.br@gmail.com (ORCID)

Authors:

• Rafael H. M. Pereira rafa.pereira.br@gmail.com (ORCID)

• Rogério J. Barbosa antrologos@gmail.com (ORCID)

Other contributors:

• Pedro Herculano Souza pedro.souza@ipea.gov.br [contributor]

• Diego Rabatone Oliveira diraol@diraol.eng.br [contributor]

• Neal Richardson neal.p.richardson@gmail.com [contributor]

• Haydee Svab haydee.svab@gmail.com [contributor]

• Ipea - Institute for Applied Economic Research [copyright holder, funder]

See Also

Useful links:

• https://github.com/ipea/censobr

• https://ipea.github.io/censobr/

• Report bugs at https://github.com/ipea/censobr/issues

Safely use arrow to open a Parquet file

Description

This function handles some failure modes, including if the Parquet file is corrupted.

Usage

arrow_open_dataset(filename)

Arguments

Value

An arrow::Dataset

Message when caching file

Description

Message when caching file

Usage

cache_message(
  local_file = parent.frame()$local_file,
  cache = parent.frame()$cache,
  verbose = parent.frame()$verbose
)

Arguments

Value

A message

Manage cached files from the censobr package

Description

Manage cached files from the censobr package

Usage

censobr_cache(
  list_files = TRUE,
  print_tree = FALSE,
  delete_file = NULL,
  verbose = TRUE
)

Arguments

Details

censobr caches data in a directory versioned by data release, so a new data release does not read files downloaded from the previous one. Files from previous releases are deleted automatically the first time data is downloaded in a session, and can be deleted at any time with delete_file = "old". Set options(censobr.keep_old_cache = TRUE) to keep them, for example to go on working with an older data release. Microdata imported with import_microdata22() are never deleted automatically, because censobr cannot download them again.

Value

A message indicating which file exist and/or which ones have been deleted from the local cache directory.

See Also

Other Cache data: get_censobr_cache_dir(), set_censobr_cache_dir()

Examples

# list all files cached
censobr_cache(list_files = TRUE)

# delete particular file
censobr_cache(delete_file = '2010_deaths')

Data dictionary of Brazil's census data

Description

Open on a browser the data dictionary of Brazil's census data.

Usage

data_dictionary(
  year,
  dataset,
  showProgress = TRUE,
  cache = TRUE,
  verbose = TRUE
)

Arguments

Value

Returns the path to the downloaded file. When verbose = TRUE and the session is interactive, the file is also opened and the path is returned invisibly.

See Also

Other Census documentation: interview_manual()

Examples

# Open data dictionary
data_dictionary(
  year = 2022,
  dataset = 'microdata'
  )

data_dictionary(
  year = 2022,
  dataset = 'tracts'
  )

Delete files cached from previous data releases

Description

The cache directory is versioned by data release (⁠{cache_dir}/data_release_{tag}⁠), so bumping the data release leaves the files of the previous one behind. This deletes them.

Usage

delete_old_cache_dirs(verbose = TRUE)

Arguments

Details

Only directories named ⁠data_release_*⁠ are considered, and the current release is matched by equality rather than by pattern: the cache directory can be any directory the user chose with set_censobr_cache_dir(), so anything else living there is none of the package's business.

Microdata imported with import_microdata22() are never deleted. They come from a zip file IBGE distributes under controlled access, so censobr cannot download them again. A release directory that still holds those files is kept.

Set options(censobr.keep_old_cache = TRUE) to disable this entirely, for example to keep working with an older data release.

Value

The paths deleted, invisibly.

Download file from url

Description

Download file from url

Usage

download_file(
  file_url = parent.frame()$file_url,
  showProgress = parent.frame()$showProgress,
  cache = parent.frame()$cache,
  verbose = parent.frame()$verbose
)

Arguments

Value

A string to the address of the file

Is a downloaded file incomplete?

Description

Is a downloaded file incomplete?

Usage

download_is_incomplete(actual, expected, encoding)

Arguments

Value

Logical.

Error when a required argument is not declared

Description

Error when a required argument is not declared

Usage

error_arg_not_declared(arg, options)

Arguments

Value

An informative error

Error when requested columns are absent from the data

Description

Error when requested columns are absent from the data

Usage

error_columns_absent(absent)

Arguments

Value

An informative error

Error when merge_households is requested without columns

Description

Error when merge_households is requested without columns

Usage

error_merge_households_needs_columns()

Value

An informative error

Error when merge_households is requested for a year that does not support it

Description

Defensive only. Since the 1960 household key was documented, the merge_households entry of the year registry matches the entry of the data set being read, so no year that clears the availability check can reach this error. It is kept so that the two registries diverging again fails loudly instead of silently returning an unmerged result.

Usage

error_merge_households_years(y)

Arguments

Value

An informative error

Error missing data sets

Description

Error missing data sets

Usage

error_missing_datasets(d)

Arguments

Value

An informative error

Error missing years

Description

Error missing years

Usage

error_missing_years(y)

Arguments

Value

An informative error

Error when the year is not declared

Description

Error when the year is not declared

Usage

error_year_not_declared()

Value

An informative error

Get path to cache directory for censobr files

Description

Get the path to the cache directory currently being used for for the censobr files

Usage

get_censobr_cache_dir()

Value

Path to cache dir

See Also

Other Cache data: censobr_cache(), set_censobr_cache_dir()

Examples

# get path to cache directory
get_censobr_cache_dir()

Import controlled-access microdata of the 2022 census into censobr cache

Description

Import controlled-access microdata of the sample component of Brazil's 2022 Population Census ("dados controlados") from a zip file obtained from IBGE, convert the csv files it contains into Parquet, and save them in the local censobr cache directory.

Unlike the microdata of previous censuses, the 2022 controlled-access microdata are distributed by IBGE under controlled access and cannot be redistributed by censobr directly. Users need to request the data directly from IBGE at https://microdados.ibge.gov.br/ and run this function once on the zip file they receive from IBGE. From then on, the data are available locally like any other data set cached by the censobr package, and no download is attempted.

One Parquet file is written per table, following the file naming convention used by censobr:

After that the tables sit in the cache and are read from disk, with no further processing. The data imported via import_microdata22() lives in the cache directory even if censobr updates to a new data release. This means you only need to import the data once. Nonetheless, we strongly recommend you store the original .zip from IBGE somewhere safe in case you need to import that data again.

Usage

import_microdata22(zip_path, verbose = TRUE)

Arguments

Value

Returns NULL invisibly and prints message. The function is called for its side effect of writing Parquet files to the censobr cache directory, whose location can be checked with get_censobr_cache_dir().

Examples

## Not run: 

# **pointing to a temp cache dir just so this example does not overite cache**
temp_cache_dir <- fs::path_temp("temp_example")
censobr::set_censobr_cache_dir(temp_cache_dir)

# path to fake zip file
# **the real zip file has to be requested from IBGE beforehand**
path_to_zip <- system.file(
  "extdata/microdata_2022_controlado_fake.zip",
  package = "censobr"
)

# import controlled-access microdata 2022
censobr::import_microdata22(zip_path = path_to_zip)

# check files in cache dir
censobr::censobr_cache()

# set cache back to original dir
censobr::set_censobr_cache_dir(path = NULL)

## End(Not run)

Interview manual of the data collection of Brazil's censuses

Description

Open on a browser the interview manual of the data collection of Brazil's censuses

Usage

interview_manual(year, showProgress = TRUE, cache = TRUE, verbose = TRUE)

Arguments

Value

Returns the path to the downloaded file. When verbose = TRUE and the session is interactive, the file is also opened and the path is returned invisibly.

See Also

Other Census documentation: data_dictionary()

Examples

# Open interview manual on the browser
interview_manual(
  year = 2010,
  showProgress = FALSE
  )

Add household variables to the data set

Description

Streams the main table through DuckDB's native parquet reader and joins it to the (already downloaded, already labelled) household table, writing the result to a temporary parquet file so a wide main table never round-trips through memory.

Usage

merge_household_var(
  df,
  year = parent.frame()$year,
  columns = NULL,
  add_labels = parent.frame()$add_labels,
  showProgress = parent.frame()$showProgress,
  cache = TRUE,
  verbose = parent.frame()$verbose
)

Arguments

Value

An arrow Dataset with additional household variables, or invisible(NULL) if the household data could not be downloaded or the merge failed.

Build the release URL, download it, and open it as an arrow Dataset

Description

Contains no input validation, so that errors raised by the calling function keep being attributed to that function rather than to this helper.

Usage

open_censobr_data(dataset, year, showProgress, cache, verbose)

Arguments

Value

An arrow Dataset, or NULL if the download or the file failed.

Delete files from previous data releases once per session

Description

Wraps delete_old_cache_dirs() so that the check runs only the first time a versioned cache directory is resolved in a session. The cache directory already checked is recorded, rather than a flag, so that a user who switches directories with set_censobr_cache_dir() gets the new one checked too.

Usage

prune_old_cache_once(verbose = TRUE)

Arguments

Value

The paths deleted, invisibly.

Questionnaires used in the data collection of Brazil's censuses

Description

Open on a browser the questionnaire used in the data collection of Brazil's censuses

Usage

questionnaire(year, type, showProgress = TRUE, cache = TRUE, verbose = TRUE)

Arguments

Value

Returns the path to the downloaded file. When verbose = TRUE and the session is interactive, the file is also opened and the path is returned invisibly.

Examples

library(censobr)

# Open questionnaire on browser
questionnaire(year = 2010, type = 'long', showProgress = FALSE)

Download microdata of emigration records from Brazil's census

Description

Download microdata of emigration records from Brazil's census. Data collected in the sample component of the questionnaire.

Usage

read_emigration(
  year,
  columns = NULL,
  add_labels = NULL,
  merge_households = FALSE,
  as_data_frame = FALSE,
  showProgress = TRUE,
  cache = TRUE,
  verbose = TRUE
)

Arguments

Value

An arrow Dataset or a "data.frame" object.

See Also

Other Microdata: read_families(), read_households(), read_mortality(), read_population()

Examples

# return data as arrow Dataset
df <- read_emigration(
  year = 2010,
  showProgress = FALSE
  )

# return data as data.frame
df <- read_emigration(
  year = 2010,
  as_data_frame = TRUE,
  showProgress = FALSE
  )

Download microdata of family records from Brazil's census

Description

Download microdata of family records from Brazil's census. Data collected in the sample component of the questionnaire.

Usage

read_families(
  year,
  columns = NULL,
  add_labels = NULL,
  as_data_frame = FALSE,
  showProgress = TRUE,
  cache = TRUE,
  verbose = TRUE
)

Arguments

Value

An arrow Dataset or a "data.frame" object.

See Also

Other Microdata: read_emigration(), read_households(), read_mortality(), read_population()

Examples

# return data as arrow Dataset
df <- read_families(
  year = 2000,
  showProgress = FALSE
  )

Download microdata of household records from Brazil's census

Description

Download microdata of household records from Brazil's census. Data collected in the sample component of the questionnaire.

Usage

read_households(
  year,
  columns = NULL,
  add_labels = NULL,
  as_data_frame = FALSE,
  showProgress = TRUE,
  cache = TRUE,
  verbose = TRUE
)

Arguments

Value

An arrow Dataset or a "data.frame" object.

1960 Census

The 1960 microdata version available in censobr is a combination of two versions of the Demographic Census sample. The 25% sample data from the 1960 Census was never fully processed by IBGE - several states did not have their questionnaires digitized. Currently, this dataset only has data from 16 states of the Federation (and from a contested border region between Minas Gerais and Espirito Santo called Serra dos Aimores). Information is missing for the states of the former Northern Region, Maranhão, Piaui, Guanabara, Santa Catarina, and Espírito Santo. In 1965, IBGE decided to draw a probabilistic sub-sample of approximately 1.27% of the population, including all units of the federation. With this data, IBGE produced several official reports at the time. The data from censobr is the combination of these two datasets.

We pre-processed the 1.27% sample data to ensured data consistency, given the original data was partially corrupted. We also created a sample weight variable to correct for unbalanced data and to expand te sample to the total population. For the data from the 25% sample, the weights expand to the municipal totals. Meanwhile, for the data from the 1.27% sample, the weights expand to the state totals. Additionally, we constructed a few variables that allow for the approximate incorporation of the complex sample design, enabling the proper calculation of standard errors and confidence intervals.

You can read more about the 1960 Census and find a thorough documentation of how this dataset was processed on this link https://github.com/antrologos/ConsistenciaCenso1960Br.

See Also

Other Microdata: read_emigration(), read_families(), read_mortality(), read_population()

Examples

# return data as arrow Dataset
df <- read_households(
  year = 2010,
  showProgress = FALSE
  )

Download microdata of death records from Brazil's census

Description

Download microdata of death records from Brazil's census. Data collected in the sample component of the questionnaire.

Usage

read_mortality(
  year,
  columns = NULL,
  add_labels = NULL,
  merge_households = FALSE,
  as_data_frame = FALSE,
  showProgress = TRUE,
  cache = TRUE,
  verbose = TRUE
)

Arguments

Value

An arrow Dataset or a "data.frame" object.

See Also

Other Microdata: read_emigration(), read_families(), read_households(), read_population()

Examples

# return data as arrow Dataset
df <- read_mortality(
  year = 2010,
  showProgress = FALSE
  )

# return data as data.frame
df <- read_mortality(
  year = 2010,
  as_data_frame = TRUE,
  showProgress = FALSE
  )

Download microdata of population records from Brazil's census

Description

Download microdata of population records from Brazil's census. Data collected in the sample component of the questionnaire.

Usage

read_population(
  year,
  columns = NULL,
  add_labels = NULL,
  as_data_frame = FALSE,
  showProgress = TRUE,
  cache = TRUE,
  verbose = TRUE,
  merge_households = FALSE
)

Arguments

Details

merge_households = TRUE is available for every census year the function serves, and requires columns to be set. For 1980 and 1991 the population microdata already include all variables of the household data set, so merge_households = TRUE has no effect and a message says so. Merging household variables into the full population microdata produces about 300 columns and can require more than 20GB of memory; naming the columns you need keeps the operation fast and light, typically a few seconds. The merge writes a temporary parquet file that is removed when the R session ends.

Value

An arrow Dataset or a "data.frame" object.

1960 Census

The 1960 microdata version available in censobr is a combination of two versions of the Demographic Census sample. The 25% sample data from the 1960 Census was never fully processed by IBGE - several states did not have their questionnaires digitized. Currently, this dataset only has data from 16 states of the Federation (and from a contested border region between Minas Gerais and Espirito Santo called Serra dos Aimores). Information is missing for the states of the former Northern Region, Maranhão, Piaui, Guanabara, Santa Catarina, and Espírito Santo. In 1965, IBGE decided to draw a probabilistic sub-sample of approximately 1.27% of the population, including all units of the federation. With this data, IBGE produced several official reports at the time. The data from censobr is the combination of these two datasets.

We pre-processed the 1.27% sample data to ensured data consistency, given the original data was partially corrupted. We also created a sample weight variable to correct for unbalanced data and to expand te sample to the total population. For the data from the 25% sample, the weights expand to the municipal totals. Meanwhile, for the data from the 1.27% sample, the weights expand to the state totals. Additionally, we constructed a few variables that allow for the approximate incorporation of the complex sample design, enabling the proper calculation of standard errors and confidence intervals.

You can read more about the 1960 Census and find a thorough documentation of how this dataset was processed on this link https://github.com/antrologos/ConsistenciaCenso1960Br.

See Also

Other Microdata: read_emigration(), read_families(), read_households(), read_mortality()

Examples

# return data as arrow Dataset
df <- read_population(
  year = 2010,
  showProgress = FALSE
  )

Download census tract-level data from Brazil's censuses

Description

Download census tract-level aggregate data from Brazil's censuses.

Usage

read_tracts(
  year,
  dataset,
  as_data_frame = FALSE,
  showProgress = TRUE,
  cache = TRUE,
  verbose = TRUE
)

Arguments

Value

An arrow Dataset or a "data.frame" object.

Examples

library(censobr)

# return data as arrow Dataset
df <- read_tracts(
  year = 2022,
  dataset = 'Domicilio',
  showProgress = FALSE
  )

# return data as data.frame
df <- read_tracts(
  year = 2010,
  dataset = 'Basico',
  as_data_frame = TRUE,
  showProgress = FALSE
  )

Column types of the microdata tables of the 2022 census

Description

Column types of the four tables in the controlled-access microdata of the 2022 census, taken from the layout file distributed by IBGE ("Layout Microdados CD2022 - acesso Controlado.xlsx"), which declares the width (⁠POSICAO INICIAL⁠, ⁠POSICAO FINAL⁠, INT) and the number of decimal places (DEC) of every variable.

The width and the decimal places give the type:

• DEC > 0 becomes float64(). There are only seven such variables. The sample weights carry 13 decimal places and the income variables carry 9 digits plus 2 decimals, so neither fits in a 32 bit float.

• DEC == 0 becomes an integer sized by INT: up to 4, int32() up to 9 and int64() for the 10 digit codes. The "area de ponderacao" is one of the latter: from state 22 onwards it is above 2147483647 and overflows a 32 bit integer.

• F0101 and M0101 are the exception and become string(): they carry a letter prefix, "F001" and "M001". P0101 looks like them but is not, it is a plain count of 1 to 36, so it stays an integer.

Every type was checked against the data: each of the 330 variables was scanned across all 27 state files of its table, recording the largest value, whether any value carries letters, and whether any carries decimals. The type here is the wider of what the layout declares and what the values require.

Note that the codes are stored as integers, so the leading zeros of the categorical variables are not kept: F0120 is 8, not "08". This departs from the microdata of the other censuses, where the codes are strings.

Declaring the schema also bypasses the type inference of arrow, which reads only the first block of the first file and therefore mistypes the variables that happen to be blank in it.

These are functions, and not stored objects, because an arrow::schema() is an external pointer: an object created when the package is built would be restored as a null pointer when the package is loaded.

Usage

schema_households()

schema_families()

schema_mortality()

schema_population()

Value

An arrow::schema().

Set custom cache directory for censobr files

Description

Set custom directory for caching files from the censobr package. The user only needs to run this function once. This set directory is persistent across R sessions.

Usage

set_censobr_cache_dir(path, verbose = TRUE)

Arguments

Value

A message pointing to the directory where censobr files are cached.

See Also

Other Cache data: censobr_cache(), get_censobr_cache_dir()

Examples

# Set custom cache directory
tempd <- tempdir()
set_censobr_cache_dir(path = tempd)

# back to default path
set_censobr_cache_dir(path = NULL)

Check if user is using the default cache dir of censobr

Description

Check if user is using the default cache dir of censobr

Usage

using_default_censobr_cache_dir()

Value

TRUE or FALSE

Warning when the 2022 microdata have not been imported yet

Description

Warning when the 2022 microdata have not been imported yet

Usage

warning_microdata22_not_imported(call = rlang::caller_env())

Arguments

Value

An informative warning