Package 'pulso'

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

module

Character. Module name (e.g., "ocupados"). Must be one of the modules registered in sources.json.

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

df	A tibble loaded with pulso_load(..., metadata = TRUE).
column	Character. Column name to describe.

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

variable_name

Character. Canonical variable name (e.g., "sexo"). The lookup is case-insensitive.

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

df	A tibble loaded with pulso_load(..., metadata = TRUE).

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

module

Character or NULL. When non-NULL, restricts output to variables whose module field equals this value (exact match, case-sensitive). Available modules in the current variable map: caracteristicas_generales, desocupados, inactivos, ocupados, otros_ingresos, vivienda_hogares.

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

year	Integer. Year (2007 to current year).
month	Integer. Month (1-12).
module	Character. Module name (e.g., "ocupados").
area	Character or NULL. Optional area filter. NOT IMPLEMENTED in v0.1.0.
harmonize	Logical. Whether to apply harmonization. Default TRUE.
cache	Logical. Whether to cache downloads. Default TRUE.
metadata	Logical. Whether to attach DANE metadata to result. Default FALSE for Python parity. When TRUE, attaches metadata via attr(df, "pulso_metadata") and triggers lazy download of codebook on first call.
allow_unvalidated	Logical. When FALSE (default), raises pulso_data_not_validated for periods not yet manually validated against DANE published figures. Set TRUE to load anyway with a warning.

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

year	Integer. Year (2007 to current year).
month	Integer. Month (1-12).
modules	Character vector. Module names to merge (length >= 2). Use pulso_load for a single module.
harmonize	Logical. Whether to lowercase column names. Default TRUE.
cache	Logical. Whether to cache downloads. Default TRUE.
metadata	Logical. Whether to attach DANE metadata. Default FALSE.
allow_unvalidated	Logical. Passed through to each pulso_load() call. Default FALSE. When TRUE, metadata is composed from the first module's column index as a v0.1.0 approximation (multi-module metadata composition is planned for v0.2.0).

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

start	Optional start date as character "YYYY-MM-DD" or Date.
end	Optional end date as character "YYYY-MM-DD" or Date.
use_fixture	Logical or NULL. If NULL (default), auto-detect: tries API first, falls back to snapshot if unavailable. If TRUE, always use bundled snapshot. If FALSE, force API call.

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

year	Integer. Year (2007 to current year).
month	Integer. Month (1-12).

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)

---