Estimate income poverty KPIs from explicit poverty lines

Builds income-poverty and extreme-income-poverty flags from explicit, auditable poverty lines and estimates their incidence with the package survey-design-aware indicator estimator.

Usage

enemdu_kpi_income_poverty(
  data,
  group_vars = NULL,
  income_var = "ingtot_pc",
  period = NULL,
  mode = c("strict", "manual"),
  poverty_line = NULL,
  extreme_poverty_line = NULL,
  poverty_lines = enemdu_poverty_line_registry(),
  line_source = NULL,
  poverty_var = "pobre",
  extreme_poverty_var = "expobre",
  add_line_vars = TRUE,
  overwrite = FALSE,
  registry = enemdu_indicator_registry(),
  official_validation_status = "not_officially_validated",
  official_validation_note =
    "Estimates have not been compared against official INEC tabulations.",
  ...
)

Arguments

data

A data frame.

group_vars

Optional grouping variables.

income_var

Household per-capita income variable. Defaults to "ingtot_pc".

period

Period identifier used for poverty-line metadata and strict registry lookup.

mode

One of "strict" or "manual".

poverty_line

Manual poverty line. Required in manual mode.

extreme_poverty_line

Manual extreme poverty line. Required in manual mode.

poverty_lines

Poverty-line registry. Defaults to the package template registry.

line_source

Source note required in manual mode.

poverty_var

Output poverty flag variable. Defaults to "pobre".

extreme_poverty_var

Output extreme poverty flag variable. Defaults to "expobre".

add_line_vars

Logical. If TRUE, adds poverty-line variables to the working data before estimation.

overwrite

Logical. If TRUE, overwrites existing poverty output variables.

registry

Indicator registry used by enemdu_indicator_estimate().

official_validation_status

Status label for official validation. Defaults to "not_officially_validated".

official_validation_note

Note explaining the official validation status.

...

Additional arguments passed to enemdu_indicator_estimate().

Value

A tibble with income-poverty KPI estimates and poverty-line provenance metadata.

Details

This function does not derive official poverty lines, does not ingest CPI series, and does not claim official validation. Official validation requires comparing estimates against official INEC tabulations and documenting the evidence.

Examples

if (FALSE) { # \dontrun{
data <- tibble::tibble(
  idhogar = c("h1", "h1", "h2", "h2"),
  hsize = c(2L, 2L, 2L, 2L),
  upm = c(1, 2, 3, 4),
  estrato = c(1, 1, 2, 2),
  fexp = c(1, 1, 1, 1),
  ingtot_pc = c(40, 75, 125, 150)
)

enemdu_kpi_income_poverty(
  data = data,
  period = "2025-12",
  mode = "manual",
  poverty_line = 100,
  extreme_poverty_line = 50,
  line_source = "Synthetic manual lines for examples; not official validation.",
  survey_type = "anual",
  sample_n_min = 1
)
} # }