Skip to contents

pipgd_quantile returns the quantile (i.e., monetary value) that corresponds to the share of the population that lives below that threshold.

Usage

pipgd_quantile(
  params = NULL,
  welfare = NULL,
  weight = NULL,
  n = 10,
  popshare = seq(from = 1/n, to = 1, by = 1/n),
  mean = 1,
  complete = getOption("pipster.return_complete"),
  lorenz = NULL
)

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

n

numeric scalar for the number of quantiles to be used in popshare

popshare

numeric: vector of share of population. Default is seq(from = 1/n, to = 1, by = 1/n)

mean

numeric scalar of distribution mean. Default is 1

complete

logical: If TRUE, returns a list a cumulative returns from previously used get_gd functions. Default is FALSE

lorenz

character or NULL. Lorenz curve selected. It could be "lq" for Lorenz Quadratic or "lb" for Lorenz Beta

Value

Returns a nested list containing distribution statistics: $dist_stats$pop_share is a numeric vector containing the share of the population. $dist_stats$quantile is a numeric vector showing the corresponding quantile. If complete = TRUE, it returns a pipgd_params object with additional details and intermediate calculations.

Details

This is basically the inverse of estimating the poverty rate (headcount or population share) below the poverty line. In this case, you provide the headcount and pipgd_quantile returns the "poverty line".

The quantiles are calculated as function of the mean of the distribution times an x factor. Basically, the quantile is x times the mean. By default, the mean is equal to 1, which implies that, if no mean value is provided, the return value is equal to x.

NOTE: the outcome from pipgd_quantile is not necessarily the inverse of pipgd_pov_headcount. The reason for this is that, pipgd_pov_headcount selects the Lorenz parametrization that fits better at that specified point of the distribution (i.e., the poverty lines). pipgd_quantile, in contrast, use the same Lorenz parametrization for any point. The lorenz used is the one that fits best for all distributional measures.

Examples

# Example 1: Basic usage with default parameters
pipgd_quantile(welfare = pip_gd$L,
               weight  = pip_gd$P)
#> $dist_stats
#> $dist_stats$popshare
#>  [1] 0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9 1.0
#> 
#> $dist_stats$quantile
#>  [1] 0.4581878 0.5697811 0.6679802 0.7617734 0.8582851 0.9657644 1.0978575
#>  [8] 1.2861477 1.6470281 5.8269953
#> 
#> 

# Example 2: Specifying a custom number of quantiles
pipgd_quantile(welfare = pip_gd$L,
               weight  = pip_gd$P,
               n       = 5)
#> $dist_stats
#> $dist_stats$popshare
#> [1] 0.2 0.4 0.6 0.8 1.0
#> 
#> $dist_stats$quantile
#> [1] 0.5697811 0.7617734 0.9657644 1.2861477 5.8269953
#> 
#> 

# Example 3: Using a custom population share vector
custom_popshare_vector <- c(0.05, 0.1, 0.15, 0.2, 0.25, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 0.95)
pipgd_quantile(welfare = pip_gd$L,
               weight  = pip_gd$P,
               popshare = custom_popshare_vector)
#> $dist_stats
#> $dist_stats$popshare
#>  [1] 0.05 0.10 0.15 0.20 0.25 0.30 0.40 0.50 0.60 0.70 0.80 0.90 0.95
#> 
#> $dist_stats$quantile
#>  [1] 0.3929136 0.4581878 0.5163987 0.5697811 0.6199097 0.6679802 0.7617734
#>  [8] 0.8582851 0.9657644 1.0978575 1.2861477 1.6470281 2.0918353
#> 
#> 


# Example 4: Specifying a different Lorenz curve ('lb', Lorenz beta)
pipgd_quantile(welfare = pip_gd$L,
               weight  = pip_gd$P,
               lorenz  = "lb")
#> $dist_stats
#> $dist_stats$popshare
#>  [1] 0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9 1.0
#> 
#> $dist_stats$quantile
#>  [1] 0.4635670 0.5668074 0.6615363 0.7579823 0.8617611 0.9791821 1.1208976
#>  [8] 1.3113561 1.6379028       Inf
#> 
#> 

# Example 5: Detailed output with complete = TRUE and different mean factor
pipgd_quantile(welfare = pip_gd$L,
               weight  = pip_gd$P,
               mean = 1.5,
               complete = TRUE)
#> $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
#> 
#> 
#> $dist_stats
#> $dist_stats$popshare
#>  [1] 0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9 1.0
#> 
#> $dist_stats$quantile
#>  [1] 0.6872817 0.8546717 1.0019703 1.1426602 1.2874277 1.4486466 1.6467862
#>  [8] 1.9292215 2.4705422 8.7404929
#> 
#> 
#> attr(,"class")
#> [1] "pipgd_params"