Compute the Weighted Poverty Gap (Shortfall)

Calculates the average shortfall (gap) between individual/household income and the relative poverty line, weighted by the population weights and restricted to those below the poverty line.

Usage

run_weighted_poverty_shortfall(
  data_list,
  var_name,
  wgt_name = NULL,
  times_median = 0.5,
  type = c("type_4", "type_2"),
  percent = FALSE,
  na.rm = TRUE
)

Arguments

data_list

A named list of data frames.

var_name

A string specifying the variable name (e.g., "dhi", "pilabour").

wgt_name

A string (optional). The name of the weight variable. If NULL, equal weights are assumed.

times_median

A numeric scalar. The multiple of the median used to define the poverty threshold (default is 0.5).

type

A character vector indicating the percentile estimation type (passed to compute_weighted_percentiles). Default is "type_4".

percent

Logical. If TRUE, returns the relative shortfall as a percentage of the poverty line. If FALSE, returns the absolute daily shortfall (default is FALSE).

na.rm

Logical. Should missing values be removed before computation? Default is TRUE.

Value

A named list. Each list element is named by country and contains a named numeric vector, where the names are years and the values represent:

• The average daily shortfall in monetary units (if percent = FALSE), or

• The average relative shortfall in percentage terms (if percent = TRUE), among individuals or households below the poverty threshold.

Examples

if (FALSE) { # \dontrun{
library(lissyrtools)
library(purrr)
library(dplyr)

datasets <- lissyrtools::lissyuse(data = c("de", "es", "uk"), vars = c("dhi"), from = 2016)

datasets <- datasets %>%
  map(~ .x %>% filter(!is.na(dhi))) %>%
  map(~ .x %>% mutate(new_wgt = hwgt * nhhmem)) %>%
  apply_iqr_top_bottom_coding("dhi", "hwgt", type = "type_2") %>%
  apply_sqrt_equivalisation("dhi")

# Compute average poverty shortfall in absolute (daily monetary) terms
abs_gap <- run_weighted_poverty_shortfall(
  data_list = datasets,
  var_name = "dhi",
  wgt_name = "new_wgt"
)

# Compute average poverty shortfall in percentage of the poverty line
rel_gap <- run_weighted_poverty_shortfall(
  data_list = datasets,
  var_name = "dhi",
  wgt_name = "new_wgt",
  percent = TRUE
)

# Compute average poverty shortfall in absolute (daily monetary) terms, converted to international dollars at 2017 prices. 
abs_gap_dollars <- datasets %>% 
  apply_ppp_adjustment("dhi", "lis", "lisppp") %>% 
  run_weighted_poverty_shortfall(
  var_name = "dhi",
  wgt_name = "new_wgt"
)

print(abs_gap)
print(rel_gap)
print(abs_gap_dollars)
} # }