Package 'censobr'

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

list_files	Logical. Whether to print a message with the address of all censobr data sets cached locally. Defaults to TRUE.
print_tree	Logical. Whether the cache files should be printed in a tree-like format. This parameter only works if list_files = TRUE. Defaults to FALSE.
delete_file	String. The file name or a string pattern that matches the file path of a file cached locally and which should be deleted. Defaults to NULL, so that no file is deleted. If delete_file = "all", then all of the cached files are deleted.
verbose	A logical. Whether the function should print informative messages. Defaults to TRUE.

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

year	Numeric. Year of reference in the format yyyy.
dataset	Character. The type of data dictionary to be opened. Options include c("microdata", "tracts", "population", "households", "families", "mortality", "emigration"). In the case of "microdata", the function opens an Excel file with the data dictionary of all variables, including auxiliary documentation.
showProgress	Logical. Defaults to TRUE display download progress bar. The progress bar only reflects only the downloading time, not the time to load the data to memory.
cache	Logical. Whether the function should read the data cached locally, which is much faster. Defaults to TRUE. The first time the user runs the function, censobr will download the file and store it locally so that the file only needs to be download once. If FALSE, the function will download the data again and overwrite the local file.
verbose	A logical. Whether the function should print informative messages. Defaults to TRUE.

Value

Returns NULL and opens an .html, .pdf or excel file

See Also

Other Census documentation: interview_manual()

Examples

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

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

data_dictionary(
  year = 1980,
  dataset = 'households'
  )

---

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()

---

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 = NULL,
  showProgress = TRUE,
  cache = TRUE,
  verbose = TRUE
)

Arguments

year	Numeric. Year of reference in the format yyyy.
showProgress	Logical. Defaults to TRUE display download progress bar. The progress bar only reflects only the downloading time, not the time to load the data to memory.
cache	Logical. Whether the function should read the data cached locally, which is much faster. Defaults to TRUE. The first time the user runs the function, censobr will download the file and store it locally so that the file only needs to be download once. If FALSE, the function will download the data again and overwrite the local file.
verbose	A logical. Whether the function should print informative messages. Defaults to TRUE.

Value

Opens a .pdf file on the browser

See Also

Other Census documentation: data_dictionary()

Examples

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

---

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 = 2010,
  type = NULL,
  showProgress = TRUE,
  cache = TRUE,
  verbose = TRUE
)

Arguments

year	Numeric. Year of reference in the format yyyy.
type	Character. The type of questionnaire used in the survey, whether the "long" one used in the sample component of the census, or the "short" one, which is answered by more households. Options include c("long", "short").
showProgress	Logical. Defaults to TRUE display download progress bar. The progress bar only reflects only the downloading time, not the time to load the data to memory.
cache	Logical. Whether the function should read the data cached locally, which is much faster. Defaults to TRUE. The first time the user runs the function, censobr will download the file and store it locally so that the file only needs to be download once. If FALSE, the function will download the data again and overwrite the local file.
verbose	A logical. Whether the function should print informative messages. Defaults to TRUE.

Value

Opens a .pdf file on the browser

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

year	Numeric. Year of reference in the format yyyy.
columns	String. A vector of column names to keep. The rest of the columns are not read. Defaults to NULL and read all columns.
add_labels	Character. Whether the function should add labels to the responses of categorical variables. When add_labels = "pt", the function adds labels in Portuguese. Defaults to NULL.
merge_households	Logical. Indicate whether the function should merge household variables to the output data. Defaults to FALSE.
as_data_frame	Logical. When FALSE (Default), the function returns an Arrow Dataset, which allows users to work with larger-than-memory data. If TRUE, the function returns data.frame.
showProgress	Logical. Defaults to TRUE display download progress bar. The progress bar only reflects only the downloading time, not the time to load the data to memory.
cache	Logical. Whether the function should read the data cached locally, which is much faster. Defaults to TRUE. The first time the user runs the function, censobr will download the file and store it locally so that the file only needs to be download once. If FALSE, the function will download the data again and overwrite the local file.
verbose	A logical. Whether the function should print informative messages. Defaults to TRUE.

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

year	Numeric. Year of reference in the format yyyy.
columns	String. A vector of column names to keep. The rest of the columns are not read. Defaults to NULL and read all columns.
add_labels	Character. Whether the function should add labels to the responses of categorical variables. When add_labels = "pt", the function adds labels in Portuguese. Defaults to NULL.
as_data_frame	Logical. When FALSE (Default), the function returns an Arrow Dataset, which allows users to work with larger-than-memory data. If TRUE, the function returns data.frame.
showProgress	Logical. Defaults to TRUE display download progress bar. The progress bar only reflects only the downloading time, not the time to load the data to memory.
cache	Logical. Whether the function should read the data cached locally, which is much faster. Defaults to TRUE. The first time the user runs the function, censobr will download the file and store it locally so that the file only needs to be download once. If FALSE, the function will download the data again and overwrite the local file.
verbose	A logical. Whether the function should print informative messages. Defaults to TRUE.

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

year	Numeric. Year of reference in the format yyyy.
columns	String. A vector of column names to keep. The rest of the columns are not read. Defaults to NULL and read all columns.
add_labels	Character. Whether the function should add labels to the responses of categorical variables. When add_labels = "pt", the function adds labels in Portuguese. Defaults to NULL.
as_data_frame	Logical. When FALSE (Default), the function returns an Arrow Dataset, which allows users to work with larger-than-memory data. If TRUE, the function returns data.frame.
showProgress	Logical. Defaults to TRUE display download progress bar. The progress bar only reflects only the downloading time, not the time to load the data to memory.
cache	Logical. Whether the function should read the data cached locally, which is much faster. Defaults to TRUE. The first time the user runs the function, censobr will download the file and store it locally so that the file only needs to be download once. If FALSE, the function will download the data again and overwrite the local file.
verbose	A logical. Whether the function should print informative messages. Defaults to TRUE.

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

year	Numeric. Year of reference in the format yyyy.
columns	String. A vector of column names to keep. The rest of the columns are not read. Defaults to NULL and read all columns.
add_labels	Character. Whether the function should add labels to the responses of categorical variables. When add_labels = "pt", the function adds labels in Portuguese. Defaults to NULL.
merge_households	Logical. Indicate whether the function should merge household variables to the output data. Defaults to FALSE.
as_data_frame	Logical. When FALSE (Default), the function returns an Arrow Dataset, which allows users to work with larger-than-memory data. If TRUE, the function returns data.frame.
showProgress	Logical. Defaults to TRUE display download progress bar. The progress bar only reflects only the downloading time, not the time to load the data to memory.
cache	Logical. Whether the function should read the data cached locally, which is much faster. Defaults to TRUE. The first time the user runs the function, censobr will download the file and store it locally so that the file only needs to be download once. If FALSE, the function will download the data again and overwrite the local file.
verbose	A logical. Whether the function should print informative messages. Defaults to TRUE.

Value

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

See Also

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

Examples

library(censobr)

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

# dplyr::glimpse(df)

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

# dplyr::glimpse(df)

---

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
)

Arguments

year	Numeric. Year of reference in the format yyyy.
columns	String. A vector of column names to keep. The rest of the columns are not read. Defaults to NULL and read all columns.
add_labels	Character. Whether the function should add labels to the responses of categorical variables. When add_labels = "pt", the function adds labels in Portuguese. Defaults to NULL.
as_data_frame	Logical. When FALSE (Default), the function returns an Arrow Dataset, which allows users to work with larger-than-memory data. If TRUE, the function returns data.frame.
showProgress	Logical. Defaults to TRUE display download progress bar. The progress bar only reflects only the downloading time, not the time to load the data to memory.
cache	Logical. Whether the function should read the data cached locally, which is much faster. Defaults to TRUE. The first time the user runs the function, censobr will download the file and store it locally so that the file only needs to be download once. If FALSE, the function will download the data again and overwrite the local file.
verbose	A logical. Whether the function should print informative messages. Defaults to TRUE.

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

year	Numeric. Year of reference in the format yyyy.
dataset	Character. The dataset to be opened. The following options are available for each edition of the census: 2000 Census c("Basico", "Domicilio", "Responsavel", "Pessoa", "Instrucao", "Morador"). 2010 Census c("Basico", "Domicilio", "DomicilioRenda", "Responsavel", "ResponsavelRenda", "Pessoa", "PessoaRenda", "Entorno"). 2022 Census c("Basico", "Domicilio", "ResponsavelRenda", "Pessoas", "Indigenas", "Quilombolas", "Entorno", "Obitos", "Preliminares"). The censobr package exposes all original IBGE census tracts datasets, regrouping them into broader themes and appending geographic identifiers so that they align seamlessly with geobr shapefiles. For a complete description of the datasets, themes, and variables, check data_dictionary(year = 2000, dataset = "tracts"), data_dictionary(year = 2010, dataset = "tracts"), data_dictionary(year = 2022, dataset = "tracts").
as_data_frame	Logical. When FALSE (Default), the function returns an Arrow Dataset, which allows users to work with larger-than-memory data. If TRUE, the function returns data.frame.
showProgress	Logical. Defaults to TRUE display download progress bar. The progress bar only reflects only the downloading time, not the time to load the data to memory.
cache	Logical. Whether the function should read the data cached locally, which is much faster. Defaults to TRUE. The first time the user runs the function, censobr will download the file and store it locally so that the file only needs to be download once. If FALSE, the function will download the data again and overwrite the local file.
verbose	A logical. Whether the function should print informative messages. Defaults to TRUE.

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
  )

---

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

path	String. The path to an existing directory. It defaults to path = NULL, to use the default directory
verbose	A logical. Whether the function should print informative messages. Defaults to TRUE.

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)

---