add_gerda_covariates: Add County-Level Covariates to GERDA Election Data

In gerda: German Election Database (GERDA)

Add County-Level Covariates to GERDA Election Data

Description

Convenience function to merge INKAR county-level (Kreis) covariates with GERDA election data. This is the recommended way to add covariates, as it automatically uses the correct join keys and prevents common merge errors.

The function works with both county-level and municipal-level election data:

• County-level data: Direct merge using county codes

• Municipal-level data: Automatically extracts county code from municipal AGS (first 5 digits) and merges

Important: Covariates are always at the county level. When merging with municipal data, all municipalities within the same county will receive identical covariate values.

The function performs a left join, keeping all rows from the election data and adding covariates where available. This automatically retains only election years.

Usage

add_gerda_covariates(election_data, unmatched = "warn")

Arguments

election_data	A data frame containing GERDA election data. Must contain a column with county or municipal codes (see Details) and election_year.
unmatched	How to handle rows within the 1995-2022 INKAR coverage window whose join keys do not match. One of "warn" (default), "error", or "ignore". Rows outside 1995-2022 are reported separately and do not trigger this action.

Details

Required Columns

The input data must contain election_year and one of:

• county_code: 5-digit county code (AGS) for county-level data

• ags: 8-digit municipal code (AGS) for municipal-level data

The function automatically detects which column is present and performs the appropriate merge. For municipal data, the county code is extracted from the first 5 digits of the AGS.

Data Level

Covariates are at the county (Kreis) level:

• County-level merge: One-to-one match, each county gets its covariates

• Municipal-level merge: Many-to-one match, all municipalities in the same county receive identical covariate values

Data Availability

Covariates are available from 1995-2022. For GERDA federal elections:

• Elections 1990, 1994: No covariates (before 1995)

• Elections 1998-2021: Covariates available

Missing Data

Some covariates have missing values. Use gerda_covariates_codebook() to check data availability for specific variables.

Validation and Diagnostics

Geographic identifiers must be character vectors containing exactly five digits (county_code) or eight digits (ags). Numeric identifiers are rejected because leading zeros may already have been lost. Before joining, the function verifies reference-key uniqueness and rejects output-column conflicts. It then verifies that the join has not changed the input row count and reports unexpected unmatched rows separately from years outside INKAR coverage. Missing join keys are always classified as unexpected. Use unmatched = "error" in unattended pipelines.

Value

The input data frame with additional columns for all 30 county-level covariates. The number of rows remains unchanged. A machine-readable join report is attached and can be retrieved with gerda_join_diagnostics().

See Also

• gerda_covariates for direct access to the covariate data

• gerda_covariates_codebook for variable descriptions

• load_gerda_web for loading GERDA election data

• gerda_join_diagnostics for inspecting match results

Examples

## Not run: 
library(gerda)
library(dplyr)

# Example 1: County-level election data
county_data <- load_gerda_web("federal_cty_harm") %>%
  add_gerda_covariates()

# Check the result
names(county_data) # See new covariate columns
table(county_data$election_year) # Only election years

# Example 2: Municipal-level election data
# Note: All municipalities in the same county will get identical covariates
muni_data <- load_gerda_web("federal_muni_harm_21") %>%
  add_gerda_covariates()

# Verify: municipalities in same county have same covariate values.
# The county code is the first 5 digits of the 8-digit municipal AGS.
muni_data %>%
  mutate(county_code = substr(ags, 1, 5)) %>%
  group_by(county_code, election_year) %>%
  summarize(
    n_munis = n(),
    unemp_range = max(unemployment_rate) - min(unemployment_rate)
  )

# Analyze with covariates
county_data %>%
  filter(election_year == 2021) %>%
  filter(!is.na(unemployment_rate)) %>%
  summarize(cor_unemployment_afd = cor(unemployment_rate, afd))

## End(Not run)

gerda documentation built on July 27, 2026, 5:09 p.m.