AmericasBarometer Labels Guide"

In lapop: Processing, Visualizing, and Labeling Americas Barometer Data

knitr::opts_chunk$set(echo = TRUE, message = FALSE, warning = FALSE)
knitr::opts_chunk$set(fig.width = 12, fig.height = 6)

Introduction

This concise guide demonstrates how R users can effectively work with AmericasBarometer datasets to access variable metadata directly eliminating the need for external codebooks. While these features are more readily visible in Stata, they often require specific approaches in R. The guide outlines:

1. The multilingual structure and storage of AmericasBarometer data (including variable labels and value labels).

2. How to implement our custom LAPOP Lab functions for seamless dataset analysis.

Installing LAPOP Lab package

The lapop package contains custom functions to analyze data and plot figures following the LAPOP Lab's guidelines.

If you do not have the LAPOP Lab package already installed in your machine you can install it using the devtools package below:

# Install the LAPOP Lab package:
devtools::install_github("https://github.com/lapop-central/lapop", 
                         force=TRUE, 
                         build_vignettes = TRUE)

After installation is successful, you will need to load the package into your library:

library(lapop)
# Note: no need for lapop_fonts() 
# because we are not plotting figures

How LAPOP Lab stores variables metadata

LAPOP Lab's AmericasBarometer stores variable labels and value labels in parallel languages (i.e., Spanish/English/Portuguese) directly within the dataset structure. This allows researchers to access metadata without external codebooks by:

Embedding language-specific labels as attributes in Stata-formatted files and to use standardized variable naming conventions that maintain consistency across survey waves since 2004. Therefore, Metadata is structured to facilitate longitudinal analysis. The project employs Stata-formatted datasets (.dta) with embedded metadata, preserving:

• Variable labels (i.e., question wording).

• Value labels (i.e., responses options).

• Missing value codes (i.e., Not Applicable, Don't Know, Refused).

As a result, a key advantage is LAPOP Lab's active metadata preservation even when distributing data through third-party platforms like ICPSR or NORC, the Stata-formatted metadata remains intact, allowing R/python users to still access labels via the readstata13 package.

How to load AmericasBarometer Data in R

The preferred method for loading LAPOP Lab datasets is to use the read.dta13() function from the readstata13 package. Below, I show a key difference between this recommended approach and two alternative methods commonly used by researchers: haven::read_dta() and rio::import().

In the R programming language, attributes are additional metadata that can be attached to R objects. Attributes provide a way to store extra information about an object beyond its basic data structure. To access the attributes of an object, you can use the attr() or attributes() base functions.

# READSTATA13 PACKAGE (RECOMMENDED FOR LABELS)
data1 <- read.dta13("./BRA 2023 LAPOP AmericasBarometer (v1.0s).dta")
names(attributes(data1))

# HAVEN PACKAGE (RECOMMENDED FOR PLOTTING)
data2 <- read_dta("./BRA 2023 LAPOP AmericasBarometer (v1.0s).dta")
names(attributes(data2))

# RIO PACKAGE (NOT RECOMMENDED)
data3 <- import("./BRA 2023 LAPOP AmericasBarometer (v1.0s).dta")
names(attributes(data3))

The methods haven and rio packages do not recover all the metadata from dta files. Thereby, we proceed with the dataset loaded with the readstata13 package.

AmericasBarometer Variables Labels (Question Wording)

AmericasBarometer variable labels are stored as notes in Stata .dta files. We can find them inside the "expansion.fields" attribute.

The varlabels object created is a nested list (much like a JSON object) that will contain multilingual notes with the question wording of each variable. For instance, for the variable ing4 in the Brazil AB 2023 dataset will contain notes with the question wording and lead-in in English, Spanish, and Portuguese.

data(bra23)

# Extracting attributes from expasion.fields
names(attributes(bra23))
varlabels = attr(bra23, "expansion.fields")

How do I find the correct language labels?

It is important to keep in mind that note numbers may change across countries datasets and years depending on the language the survey was fielded. For Brazil, it is Brazilian-Portuguese, whereas in most other countries it is in Spanish but also in English like in Jamaica.

A streamlined approach for users who want to quickly find the values of the notes on variable labels without assigning to the dataset would be assessing those notes directly with a combination of lapply() and Filter() functions from base R, or also compact() and map() functions from the purrr package.

Both approaches extract the third element (x[3]) from each list in the "expansion.fields" attribute of the dataset, but only if the first element (x[1]) equals "ing4" (i.e., the variable of interest). Both produce a semi-structured list of matching third nested elements.

# Base R approach:
# The base R version uses lapply to iterate over the list and returns NULL when 
# the condition isn't met, then Filter(Negate(is.null), ...) removes those NULLs.
head(
  Filter(Negate(is.null), lapply(attr(bra23, "expansion.fields"), 
  function(x) {
    if (x[1] == "ing4") list(note_id = x[2], note_value = x[3])})), n = 3)

# purrr package approach
#  The purrr version uses map() to do the same, and also remove NULL results. 
tail(
  purrr::map_dfr(attr(bra23, "expansion.fields"), ~ {
  if (.x[1] == "ing4") 
    data.frame(
      note_id = .x[2],
      note_value = .x[3],
      stringsAsFactors = FALSE
    )
})
)

To ease the researchers and analysts job, LAPOP Lab developed custom functions to deal with those labels in R. First, we will use lpr_extract_notes to transform the nested lists from expansion.fields attribute into a long dataframe format that will contain 3 columns: variable_name, note_id, and note_value

# Extract AB notes with lpr function
BRA23notes <- lpr_extract_notes(bra23)
head(BRA23notes, n = 10) # columns names
table(BRA23notes$note_id) # note information available!

One can assign variable labels to their preferred language as attributes to the dataset using another LAPOP Lab function called lpr_set_attr() and than access it during data analysis without the need of an accompanying codebook.

# English
bra23<-lpr_set_attr(bra23, BRA23notes, verbose = F,
                    noteid = "note2", 
                    attribute_name = "qwording_en") 
# Spanish
bra23<-lpr_set_attr(bra23, BRA23notes, verbose = F,
                    noteid = "note1", 
                    attribute_name = "qwording_es")

# Portuguese
bra23<-lpr_set_attr(bra23, BRA23notes, verbose = F,
                    noteid = "note3", 
                    attribute_name = "qwording_pt") 

# Printing languages
attr(bra23$ing4, "qwording_en") # English
attr(bra23$ing4, "qwording_es") # Spanish
attr(bra23$ing4, "qwording_pt") # Portuguese

AmericasBarometer Values Labels (Response Options)

AmericasBarometer values labels (i.e., response options) differently from the variable labels are stored inside the "label.table" attribute. To extract them we will use another LAPOP Lab custom function called lpr_format_labels that will set up the response options as an attribute across languages. Default language is English and default attribute name is roslabel but the function allows custom attribute names as shown below:

bra23 <- lpr_set_ros(bra23) # Default English

bra23 <- lpr_set_ros(bra23, lang_id = "es", 
                     attribute_name = "respuestas") # Spanish

bra23 <- lpr_set_ros(bra23, lang_id = "pt", 
                     attribute_name = "ROsLabels_pt") # Portuguese

# Printing ROs
attr(bra23$ing4, "roslabel") # English
attr(bra23$ing4, "respuestas") # Spanish
attr(bra23$ing4, "ROsLabels_pt") # Portuguese

Takeaways (TLDR)

Data Structure

AmericasBarometer datasets are distributed in Stata .dta format with multilingual metadata (question wording and response options) embedded as attributes. These support cross-national and longitudinal comparability.

Preferred Loading Method

Use the readstata13::read.dta13() function to preserve full metadata structure. Other methods such as haven::read_dta() or rio::import() often fail to import these critical attributes.

Variable Labels (Question Wording):

Stored in the "expansion.fields" attribute. Use the custom lpr_extract_notes() function to convert this into a tidy data frame.

Assign preferred language labels to each variable with lpr_set_attr() using the appropriate noteid.

Value Labels (Response Options):

Stored in the "label.table" attribute. Use lpr_set_ros() to assign these response labels as attributes in English, Spanish, or Portuguese.

Quick Access Options

For advanced users, the guide also demonstrates streamlined methods using lapply() and purrr::map() to quickly view variable labels without modifying the dataset.

lapop documentation built on April 30, 2026, 1:07 a.m.