Package {pulso}

pulso: Load Microdata from Colombia's 'GEIH' ('DANE')

Description

R companion to the 'pulso-co' 'Python' package. Provides programmatic access to microdata from Colombia's Gran Encuesta Integrada de Hogares ('GEIH'), published by 'DANE', and to Banco de la Republica monetary policy data.

Loading microdata

• pulso_load() - Load a single GEIH module for a year/month

• pulso_load_merged() - Load and merge multiple persona-level modules

Describing columns and variables

• pulso_describe() - Describe a survey module

• pulso_describe_column() - Describe a single loaded column

• pulso_describe_variable() - Describe a canonical variable and its epoch mappings

• pulso_list_columns_metadata() - List metadata for all columns in a loaded tibble

• pulso_list_variables() - List canonical variables, optionally by module

Catalog and validation

• pulso_list_validated_range() - List periods with verified downloads

• pulso_validation_status() - Validation info for a specific period

Banco de la Republica

• pulso_tpm() - Monetary policy rate (TPM), with offline fallback

Comparison with Python

This package mirrors the API of the 'pulso-co' 'Python' package. See the package vignette for details.

Author(s)

Maintainer: Esteban Labastidas estebanlabastidas123@gmail.com

Authors:

• Esteban Labastidas estebanlabastidas123@gmail.com

See Also

Useful links:

• https://github.com/Stebandido77/pulso

• Report bugs at https://github.com/Stebandido77/pulso/issues

Describe a GEIH module

Description

Returns a human-readable summary of a GEIH survey module: its survey level, available epochs, and harmonized canonical variables.

Usage

pulso_describe(module)

Arguments

Value

A multi-line character string.

Examples

pulso_describe("ocupados")

Describe metadata for a single column

Description

Pretty-prints metadata for a column in a tibble loaded with metadata = TRUE. Output format mirrors Python's pulso.describe_column().

Usage

pulso_describe_column(df, column)

Arguments

Value

A multi-line character string.

Examples

df <- pulso_load(2024, 6, "ocupados", metadata = TRUE)
cat(pulso_describe_column(df, "P6020"))

Describe a harmonized variable

Description

Returns a human-readable summary of a canonical variable defined in variable_map.json: its module, description, source mappings per epoch, and any comparability warning.

Usage

pulso_describe_variable(variable_name)

Arguments

Value

A single multi-line character string.

Examples

pulso_describe_variable("sexo")
pulso_describe_variable("edad")

List metadata for all columns of a tibble

Description

Returns a tibble summary of all columns with their metadata.

Usage

pulso_list_columns_metadata(df)

Arguments

Value

A tibble with columns: column, label, type, module, source, has_categories.

Examples

df <- pulso_load(2024, 6, "ocupados", metadata = TRUE)
summary <- pulso_list_columns_metadata(df)
print(summary)

List validated GEIH periods

Description

Returns the registry entries for which the downloaded data has been manually validated against DANE published figures.

Usage

pulso_list_validated_range()

Value

A tibble with one row per validated (year, month) pair, with columns: year (integer), month (integer), epoch (character), validated (logical, always TRUE), validated_at (character, ISO-8601 or NA), num_modules (integer). Sorted by year, month ascending.

Examples

pulso_list_validated_range()

List harmonized variables from the variable map

Description

Returns a tibble summarizing all canonical variables defined in variable_map.json, optionally filtered by module.

Usage

pulso_list_variables(module = NULL)

Arguments

Value

A tibble with one row per variable and columns:

canonical_name

chr. Key used throughout the pulso package.

module

chr. Survey module the variable belongs to.

description_es

chr. Spanish description, or NA if absent.

comparability

chr. Always NA in this version (see Note).

has_warning

lgl. TRUE when a comparability_warning is present and non-empty for the variable.

num_epochs

int. Number of epoch mappings defined.

Rows are sorted ascending by canonical_name.

Note

The comparability column is always NA_character_ in the current version because the comparability field (expected values: "high" / "limited") has not yet been added to variable_map.json. Only comparability_warning (free text) is present in the data.

Examples

# All variables
pulso_list_variables()

# Subset by module
pulso_list_variables(module = "ocupados")

Load GEIH microdata for a single year-month-module

Description

Downloads and parses microdata from Colombia's Gran Encuesta Integrada de Hogares (GEIH), published by DANE.

Usage

pulso_load(
  year,
  month,
  module,
  area = NULL,
  harmonize = TRUE,
  cache = TRUE,
  metadata = FALSE,
  allow_unvalidated = FALSE
)

Arguments

Value

A tibble with the microdata. If metadata = TRUE, the tibble has an attribute "pulso_metadata" with structured column info.

Examples

df <- pulso_load(year = 2024, month = 6, module = "ocupados",
                 metadata = TRUE)
cat(pulso_describe_column(df, "P6020"))

Load and merge GEIH microdata across multiple modules

Description

Downloads, parses, and joins microdata from multiple GEIH modules for a single year-month. All modules must be at the same survey level (persona or hogar).

Usage

pulso_load_merged(
  year,
  month,
  modules,
  harmonize = TRUE,
  cache = TRUE,
  metadata = FALSE,
  allow_unvalidated = FALSE
)

Arguments

Value

A tibble with columns from all requested modules, joined on shared identifier keys (directorio, secuencia_p, orden for persona-level modules). The join is an outer join by default so that modules covering different person subsets (e.g., ocupados vs desocupados) are combined correctly.

Note

Mixed-level merges (persona + hogar modules in the same call) are deferred to v0.2.0. If you need a hogar-level module, merge the result manually after separate calls.

Examples

df <- pulso_load_merged(2024, 6, c("ocupados", "caracteristicas_generales"))
nrow(df)

Fetch Tasa de Politica Monetaria (TPM) from Banco de la Republica

Description

Returns Colombia's monetary policy rate as a tibble. Data source: Banco de la Republica SDMX API (DF_CBR_DAILY_HIST). When the API is unavailable, falls back to a bundled snapshot extending to 2026-04-21.

Usage

pulso_tpm(start = NULL, end = NULL, use_fixture = NULL)

Arguments

Value

A tibble with columns:

fecha

Date. Observation date.

valor

numeric. TPM rate in percentage points.

serie

character. Always "tpm".

Examples

# Recent TPM
tpm_2024 <- pulso_tpm(start = "2024-01-01", end = "2024-12-31")
# Full history (uses fixture if API down)
tpm_all <- pulso_tpm()

Validation status for a GEIH period

Description

Returns structured metadata about a specific year-month entry in the pulso registry, including whether it has been manually validated against published DANE figures.

Usage

pulso_validation_status(year, month)

Arguments

Value

A one-row tibble with columns: year, month, epoch, validated, validated_by, validated_at, source_url, file_size_mb, modules_available, checksum_sha256.

Examples

pulso_validation_status(2024, 6)