Estimate Watts poverty index — pipgd

Computes Watts Index from either beta or quadratic Lorenz fit. The first distribution-sensitive poverty measure was proposed in 1968 by Watts. It is defined as the mean across the population of the proportionate poverty gaps, as measured by the log of the ratio of the poverty line to income, where the mean is formed over the whole population, counting the nonpoor as having a zero poverty gap.

Usage

pipgd_watts(
  params = NULL,
  welfare = NULL,
  weight = NULL,
  mean = 1,
  times_mean = 1,
  popshare = NULL,
  povline = ifelse(is.null(popshare), mean * times_mean, NA_real_),
  format = c("dt", "list", "atomic"),
  lorenz = NULL,
  complete = getOption("pipster.return_complete")
)

Arguments

params: list of parameters from pipgd_validate_lorenz()
welfare: numeric vector of cumulative share of welfare (income/consumption)
weight: numeric vector of cumulative share of the population
mean: numeric scalar of distribution mean. Default is 1
times_mean: numeric factor that multiplies the mean to create a relative poverty line. Default is 1
popshare: numeric: range (0,1). Share of population. Provide share of population instead of poverty line
povline: numeric: value of poverty line. Default is the mean value
format: character: either "dt" for data.table, "list" or "atomic" for a single numeric vector, whose names are corresponding selected Lorenz for each value. Default is "dt"
lorenz: character or NULL. Lorenz curve selected. It could be "lq" for Lorenz Quadratic or "lb" for Lorenz Beta
complete: logical: If TRUE, returns a list a cumulative returns from previously used get_gd functions. Default is FALSE

Value

Returns a data.table and data.frame object with two variables: watts and lorenz. Check format argument to change the output format. If complete = TRUE, it returns a pipgd_params object with additional details and intermediate calculations.

Examples

# Example 1: Basic usage with the pip_gd dataset and default poverty line
pipgd_watts(welfare = pip_gd$L,
            weight  = pip_gd$P)
#>    povline     watts lorenz
#>      <num>     <num> <char>
#> 1:       1 0.2775801     lb

# Example 2: Specifying a different poverty line and output as a list
pipgd_watts(welfare = pip_gd$L,
            weight  = pip_gd$P,
            povline = 1.9,
            format  = "list")
#> $pl1.9
#> $pl1.9$pov_stats
#> $pl1.9$pov_stats$watts
#> [1] 0.7973243
#> 
#> $pl1.9$pov_stats$lorenz
#> [1] "lb"
#> 
#> 
#> 


# Example 3: Detailed output with complete = TRUE
pipgd_watts(welfare  = pip_gd$L,
            weight   = pip_gd$P,
            format   = "list",
            complete = TRUE)
#> $pl1
#> $gd_params
#> $gd_params$lq
#> $gd_params$lq$reg_results
#> $gd_params$lq$reg_results$ymean
#> [1] 0.1219752
#> 
#> $gd_params$lq$reg_results$sst
#> [1] 0.08456216
#> 
#> $gd_params$lq$reg_results$coef
#>          A          B          C 
#>  0.8877478 -1.4514459  0.2026400 
#> 
#> $gd_params$lq$reg_results$sse
#> [1] 3.418058e-06
#> 
#> $gd_params$lq$reg_results$r2
#> [1] 0.9999596
#> 
#> $gd_params$lq$reg_results$mse
#> [1] 3.797842e-07
#> 
#> $gd_params$lq$reg_results$se
#> [1] 0.006673127 0.019034521 0.012827923
#> 
#> 
#> $gd_params$lq$key_values
#> $gd_params$lq$key_values$e
#> [1] -0.638942
#> 
#> $gd_params$lq$key_values$m
#> [1] -1.444296
#> 
#> $gd_params$lq$key_values$n
#> [1] 1.044219
#> 
#> $gd_params$lq$key_values$r
#> [1] 1.857124
#> 
#> $gd_params$lq$key_values$s1
#> [1] -0.2814192
#> 
#> $gd_params$lq$key_values$s2
#> [1] 1.004414
#> 
#> 
#> $gd_params$lq$validity
#> $gd_params$lq$validity$is_normal
#> [1] TRUE
#> 
#> $gd_params$lq$validity$is_valid
#> [1] TRUE
#> 
#> $gd_params$lq$validity$headcount
#> [1] 0.6284604
#> 
#> 
#> 
#> $gd_params$lb
#> $gd_params$lb$reg_results
#> $gd_params$lb$reg_results$ymean
#> [1] -2.496791
#> 
#> $gd_params$lb$reg_results$sst
#> [1] 10.98072
#> 
#> $gd_params$lb$reg_results$coef
#>         A         B         C 
#> 0.5613532 0.9309501 0.5800259 
#> 
#> $gd_params$lb$reg_results$sse
#> [1] 0.003204989
#> 
#> $gd_params$lb$reg_results$r2
#> [1] 0.9997081
#> 
#> $gd_params$lb$reg_results$mse
#> [1] 0.0003561098
#> 
#> $gd_params$lb$reg_results$se
#> [1] 0.014871578 0.005505620 0.006407669
#> 
#> 
#> $gd_params$lb$key_values
#> [1] NA
#> 
#> $gd_params$lb$validity
#> $gd_params$lb$validity$is_valid
#> [1] TRUE
#> 
#> $gd_params$lb$validity$is_normal
#> [1] TRUE
#> attr(,"label")
#> [1] "Normality with a mean of 1 and a poverty line of 1;1 times the mean."
#> 
#> $gd_params$lb$validity$headcount
#> [1] 0.6161877
#> 
#> 
#> 
#> 
#> $data
#> $data$welfare
#>  [1] 0.00208 0.01013 0.03122 0.07083 0.12808 0.23498 0.34887 0.51994 0.64270
#> [10] 0.79201 0.86966 0.91277 1.00000
#> attr(,"label")
#> [1] "Cumulative share of welfare"
#> 
#> $data$weight
#>  [1] 0.0092 0.0339 0.0850 0.1640 0.2609 0.4133 0.5497 0.7196 0.8196 0.9174
#> [11] 0.9570 0.9751 1.0000
#> attr(,"label")
#> [1] "Cumulative share of population"
#> 
#> 
#> $selected_lorenz
#> $selected_lorenz$for_dist
#> [1] "lq"
#> 
#> $selected_lorenz$for_pov
#> [1] "lb"
#> 
#> $selected_lorenz$use_lq_for_dist
#> [1] TRUE
#> 
#> $selected_lorenz$use_lq_for_pov
#> [1] FALSE
#> 
#> 
#> $pov_stats
#> $pov_stats$headcount
#> [1] 0.6161877
#> 
#> $pov_stats$lorenz
#> [1] "lb"
#> 
#> $pov_stats$watts
#> [1] 0.2775801
#> 
#> 
#> attr(,"class")
#> [1] "pipgd_params"
#> 

# Example 4: Custom mean and times_mean with data.table format
pipgd_watts(welfare    = pip_gd$L,
            weight     = pip_gd$P,
            mean       = 109.9,
            times_mean = 1.5)
#>    povline     watts lorenz
#>      <num>     <num> <char>
#> 1:  164.85 0.5828177     lb