Compute FGT poverty family measures and Watts index for Microdata

Usage

md_compute_fgt(
  fgt_data = NULL,
  welfare = NULL,
  weight = rep(1, length(welfare)),
  povline = fmedian(welfare, w = weight)/2,
  alpha = 0,
  return_data = FALSE,
  include_povline = FALSE
)

md_compute_headcount(
  welfare,
  weight = rep(1, length(welfare)),
  povline = fmedian(welfare, w = weight)/2,
  return_data = FALSE,
  include_povline = FALSE
)

md_compute_pov_gap(
  welfare,
  weight = rep(1, length(welfare)),
  povline = fmedian(welfare, w = weight)/2,
  return_data = FALSE,
  include_povline = FALSE
)

md_compute_pov_severity(
  welfare,
  weight = rep(1, length(welfare)),
  povline = fmedian(welfare, w = weight)/2,
  return_data = FALSE,
  include_povline = FALSE
)

md_compute_watts(welfare, weight = rep(1, length(welfare)), povline)

Arguments

fgt_data: list of previously computed fgt calculations
welfare: numeric vector with either income or consumption
weight: numeric vector with sample weights. Default is 1.
povline: poverty line. Default is the half the weighted median of welfare. Allows for vector.
alpha: numeric. Alpha parameter of FGT measures. if 0, the default, it estimates the poverty headcount. If 1, the poverty gap, and if 2, the poverty severity. In practice, you can use higher levels of alpha, but their theoretical interpretation usually goes up to a value of 2.
return_data: logical: whether to return a list to be used in subsequent calls of md_compute_fgt in the parameter fgt_data.
include_povline: logical: Whether to include the poverty line as threshold for poverty measure. The default is FALSE, as absolute poverty is defined as those household below the poverty line. Yet, it might be useful to include the value of the poverty line for a very limited set of analysis (seldom used).

Value

either a vector with the fgt measure selected in argument alpha or a list of fgt estimations if return_data is TRUE

Details

md_compute_fgt works in two ways. It could either receive a list of previously computed calculations in argument fgt_data or receive the standard poverty calculation inputs such as welfare, weights and povline. The first modality ensures efficiency in computations as the poverty status of each observation and their relative distance to the poverty line is calculated only once.

wrappers

There are a few functions that are basically wrappers of md_compute_fgt. They do not serve any purpose beyond ease to the user to identify the right measure.

md_compute_headcount Computes poverty headcount, which is equivalent to md_compute_fgt(alpha = 0)

md_compute_pov_gap Computes poverty gap, which is equivalent to md_compute_fgt(alpha = 1)

md_compute_pov_severity Computes poverty severity, which is equivalent to md_compute_fgt(alpha = 2)

md_compute_watts is not a wrapper of md_compute_fgt but it is part of the poverty measures, so it is included in this documentation. Notice that the arguments are the same as of the functions above.

inclusion of poverty line

when include_povline is TRUE, the value of the povline is artificially modify to povline + e where e is a very small number (1e-10), ensure the inclusion of the line.

Examples

if (FALSE) { # \dontrun{
welfare <- md_ABC_2010_income$welfare/1e6
weight  <- md_ABC_2010_income$weight

wna     <- !is.na(welfare)
welfare <- welfare[wna]
weight  <- weight[wna]

md_compute_fgt(welfare = welfare,
               weight  = weight,
               povline = 5)

# Multiple values of alpha using the return_data argument
fgt <- md_compute_fgt(welfare     = welfare,
                      weight      = weight,
                      povline     = 5,
                      return_data =  TRUE) |>
  md_compute_fgt(alpha = 1,
                 return_data =  TRUE) |>
  md_compute_fgt(alpha = 2,
                 return_data =  TRUE)

c(fgt$FGT0, fgt$FGT1, fgt$FGT2)

# multiple poverty lines
dtgft <- md_compute_fgt(welfare = welfare,
weight  = weight,
povline = seq(from = 1, to = 10, by = .1))
attributes(dtgft)


fgt <- md_compute_fgt(welfare     = welfare,
                      weight      = weight,
                      povline     = seq(from = 1, to = 10, by = .1),
                      return_data =  TRUE) |>
  md_compute_fgt(alpha = 1,
                 return_data =  TRUE) |>
  md_compute_fgt(alpha = 2,
                 return_data =  TRUE)

dt_fgt <- data.frame(povline = fgt$povline,
                     FGT0    = fgt$FGT0,
                     FGT1    = fgt$FGT1,
                     FGT2    = fgt$FGT2)
} # }

if (FALSE) { # \dontrun{
 md_compute_watts(welfare = c(0.0355,0.0513,0.0689,0.0882),
                  weight = c(0.1041,0.1411,0.1792,0.2182),
                  povline = 1.9)

md_compute_watts(welfare = c(0.0355,0.0513,0.0689,0.0882),
                 weight = c(0.1041,0.1411,0.1792,0.2182),
                 povline = c(1.9, 2.5))
} # }