povcalnetR

library(povcalnetR)

The povcalnetR package allows to easily query the PovcalNet API from R.

Here are a few examples to get you started:

Using default options

By default, the povcalnet function return all available

povcalnet()
#> # A tibble: 1,962 x 31
#>    countrycode countryname regioncode coveragetype  year datayear datatype
#>    <chr>       <chr>       <chr>      <chr>        <dbl>    <dbl> <chr>   
#>  1 ALB         Albania     ECA        N             1996     1996 consump~
#>  2 ALB         Albania     ECA        N             2002     2002 consump~
#>  3 ALB         Albania     ECA        N             2005     2005 consump~
#>  4 ALB         Albania     ECA        N             2008     2008 consump~
#>  5 ALB         Albania     ECA        N             2012     2012 consump~
#>  6 ALB         Albania     ECA        N             2014     2014 consump~
#>  7 ALB         Albania     ECA        N             2015     2015 consump~
#>  8 ALB         Albania     ECA        N             2016     2016 consump~
#>  9 ALB         Albania     ECA        N             2017     2017 consump~
#> 10 DZA         Algeria     MNA        N             1988     1988 consump~
#> # ... with 1,952 more rows, and 24 more variables: isinterpolated <dbl>,
#> #   usemicrodata <dbl>, ppp <dbl>, povertyline <dbl>, mean <dbl>,
#> #   headcount <dbl>, povertygap <dbl>, povertygapsq <dbl>, watts <dbl>,
#> #   gini <dbl>, median <dbl>, mld <dbl>, polarization <dbl>, population <dbl>,
#> #   decile1 <dbl>, decile2 <dbl>, decile3 <dbl>, decile4 <dbl>, decile5 <dbl>,
#> #   decile6 <dbl>, decile7 <dbl>, decile8 <dbl>, decile9 <dbl>, decile10 <dbl>

Basic options

Filter by country

# Specify ONE country
povcalnet(country = "ALB")
#> # A tibble: 9 x 31
#>   countrycode countryname regioncode coveragetype  year datayear datatype
#>   <chr>       <chr>       <chr>      <chr>        <dbl>    <dbl> <chr>   
#> 1 ALB         Albania     ECA        N             1996     1996 consump~
#> 2 ALB         Albania     ECA        N             2002     2002 consump~
#> 3 ALB         Albania     ECA        N             2005     2005 consump~
#> 4 ALB         Albania     ECA        N             2008     2008 consump~
#> 5 ALB         Albania     ECA        N             2012     2012 consump~
#> 6 ALB         Albania     ECA        N             2014     2014 consump~
#> 7 ALB         Albania     ECA        N             2015     2015 consump~
#> 8 ALB         Albania     ECA        N             2016     2016 consump~
#> 9 ALB         Albania     ECA        N             2017     2017 consump~
#> # ... with 24 more variables: isinterpolated <dbl>, usemicrodata <dbl>,
#> #   ppp <dbl>, povertyline <dbl>, mean <dbl>, headcount <dbl>,
#> #   povertygap <dbl>, povertygapsq <dbl>, watts <dbl>, gini <dbl>,
#> #   median <dbl>, mld <dbl>, polarization <dbl>, population <dbl>,
#> #   decile1 <dbl>, decile2 <dbl>, decile3 <dbl>, decile4 <dbl>, decile5 <dbl>,
#> #   decile6 <dbl>, decile7 <dbl>, decile8 <dbl>, decile9 <dbl>, decile10 <dbl>

# Specify MULTIPLE countries
povcalnet(country = c("ALB", "CHN"))
#> # A tibble: 60 x 31
#>    countrycode countryname regioncode coveragetype  year datayear datatype
#>    <chr>       <chr>       <chr>      <chr>        <dbl>    <dbl> <chr>   
#>  1 ALB         Albania     ECA        N             1996     1996 consump~
#>  2 ALB         Albania     ECA        N             2002     2002 consump~
#>  3 ALB         Albania     ECA        N             2005     2005 consump~
#>  4 ALB         Albania     ECA        N             2008     2008 consump~
#>  5 ALB         Albania     ECA        N             2012     2012 consump~
#>  6 ALB         Albania     ECA        N             2014     2014 consump~
#>  7 ALB         Albania     ECA        N             2015     2015 consump~
#>  8 ALB         Albania     ECA        N             2016     2016 consump~
#>  9 ALB         Albania     ECA        N             2017     2017 consump~
#> 10 CHN         China       EAP        A             1981     1981 income  
#> # ... with 50 more rows, and 24 more variables: isinterpolated <dbl>,
#> #   usemicrodata <dbl>, ppp <dbl>, povertyline <dbl>, mean <dbl>,
#> #   headcount <dbl>, povertygap <dbl>, povertygapsq <dbl>, watts <dbl>,
#> #   gini <dbl>, median <dbl>, mld <dbl>, polarization <dbl>, population <dbl>,
#> #   decile1 <dbl>, decile2 <dbl>, decile3 <dbl>, decile4 <dbl>, decile5 <dbl>,
#> #   decile6 <dbl>, decile7 <dbl>, decile8 <dbl>, decile9 <dbl>, decile10 <dbl>

Filter by year

By default, povcalnet will only return data if a survey is available for the requested country and the requested year

# Survey year NOT available
povcalnet(country = "ALB", year = 2012)
#> # A tibble: 1 x 31
#>   countrycode countryname regioncode coveragetype  year datayear datatype
#>   <chr>       <chr>       <chr>      <chr>        <dbl>    <dbl> <chr>   
#> 1 ALB         Albania     ECA        N             2012     2012 consump~
#> # ... with 24 more variables: isinterpolated <dbl>, usemicrodata <dbl>,
#> #   ppp <dbl>, povertyline <dbl>, mean <dbl>, headcount <dbl>,
#> #   povertygap <dbl>, povertygapsq <dbl>, watts <dbl>, gini <dbl>,
#> #   median <dbl>, mld <dbl>, polarization <dbl>, population <dbl>,
#> #   decile1 <dbl>, decile2 <dbl>, decile3 <dbl>, decile4 <dbl>, decile5 <dbl>,
#> #   decile6 <dbl>, decile7 <dbl>, decile8 <dbl>, decile9 <dbl>, decile10 <dbl>

# Survey year NOT available - Empty response
povcalnet(country = "ALB", year = 2018)
#> # A tibble: 0 x 31
#> # ... with 31 variables: countrycode <chr>, countryname <chr>,
#> #   regioncode <chr>, coveragetype <chr>, year <chr>, datayear <chr>,
#> #   datatype <chr>, isinterpolated <chr>, usemicrodata <chr>, ppp <chr>,
#> #   povertyline <chr>, mean <chr>, headcount <chr>, povertygap <chr>,
#> #   povertygapsq <chr>, watts <chr>, gini <chr>, median <chr>, mld <chr>,
#> #   polarization <chr>, population <chr>, decile1 <chr>, decile2 <chr>,
#> #   decile3 <chr>, decile4 <chr>, decile5 <chr>, decile6 <chr>, decile7 <chr>,
#> #   decile8 <chr>, decile9 <chr>, decile10 <chr>

Modify the poverty line

povcalnet(country = "ALB", povline = 3.2)
#> # A tibble: 9 x 31
#>   countrycode countryname regioncode coveragetype  year datayear datatype
#>   <chr>       <chr>       <chr>      <chr>        <dbl>    <dbl> <chr>   
#> 1 ALB         Albania     ECA        N             1996     1996 consump~
#> 2 ALB         Albania     ECA        N             2002     2002 consump~
#> 3 ALB         Albania     ECA        N             2005     2005 consump~
#> 4 ALB         Albania     ECA        N             2008     2008 consump~
#> 5 ALB         Albania     ECA        N             2012     2012 consump~
#> 6 ALB         Albania     ECA        N             2014     2014 consump~
#> 7 ALB         Albania     ECA        N             2015     2015 consump~
#> 8 ALB         Albania     ECA        N             2016     2016 consump~
#> 9 ALB         Albania     ECA        N             2017     2017 consump~
#> # ... with 24 more variables: isinterpolated <dbl>, usemicrodata <dbl>,
#> #   ppp <dbl>, povertyline <dbl>, mean <dbl>, headcount <dbl>,
#> #   povertygap <dbl>, povertygapsq <dbl>, watts <dbl>, gini <dbl>,
#> #   median <dbl>, mld <dbl>, polarization <dbl>, population <dbl>,
#> #   decile1 <dbl>, decile2 <dbl>, decile3 <dbl>, decile4 <dbl>, decile5 <dbl>,
#> #   decile6 <dbl>, decile7 <dbl>, decile8 <dbl>, decile9 <dbl>, decile10 <dbl>

Other features

Get estimates when survey year is not available

The fill_gaps argument will trigger the interpolation / extrapolation of poverty estimates when survey year is not available

# fill_gaps = FALSE (default)
povcalnet(country = "HTI")
#> # A tibble: 3 x 31
#>   countrycode countryname regioncode coveragetype  year datayear datatype
#>   <chr>       <chr>       <chr>      <chr>        <dbl>    <dbl> <chr>   
#> 1 HTI         Haiti       LAC        N             2001     2001 income  
#> 2 HTI         Haiti       LAC        N             2012     2012 consump~
#> 3 HTI         Haiti       LAC        N             2012     2012 income  
#> # ... with 24 more variables: isinterpolated <dbl>, usemicrodata <dbl>,
#> #   ppp <dbl>, povertyline <dbl>, mean <dbl>, headcount <dbl>,
#> #   povertygap <dbl>, povertygapsq <dbl>, watts <dbl>, gini <dbl>,
#> #   median <dbl>, mld <dbl>, polarization <dbl>, population <dbl>,
#> #   decile1 <dbl>, decile2 <dbl>, decile3 <dbl>, decile4 <dbl>, decile5 <dbl>,
#> #   decile6 <dbl>, decile7 <dbl>, decile8 <dbl>, decile9 <dbl>, decile10 <dbl>

# fill_gaps = TRUE
povcalnet(country = "HTI", fill_gaps = TRUE)
#> # A tibble: 16 x 31
#>    countrycode countryname regioncode coveragetype  year datayear datatype
#>    <chr>       <chr>       <chr>      <chr>        <dbl>    <dbl> <chr>   
#>  1 HTI         Haiti       XX         N             1981     2001 income  
#>  2 HTI         Haiti       XX         N             1984     2001 income  
#>  3 HTI         Haiti       XX         N             1987     2001 income  
#>  4 HTI         Haiti       XX         N             1990     2001 income  
#>  5 HTI         Haiti       XX         N             1993     2001 income  
#>  6 HTI         Haiti       XX         N             1996     2001 income  
#>  7 HTI         Haiti       XX         N             1999     2001 income  
#>  8 HTI         Haiti       XX         N             2002       NA income  
#>  9 HTI         Haiti       XX         N             2005       NA income  
#> 10 HTI         Haiti       XX         N             2008       NA income  
#> 11 HTI         Haiti       XX         N             2010       NA income  
#> 12 HTI         Haiti       XX         N             2011       NA income  
#> 13 HTI         Haiti       XX         N             2012     2012 consump~
#> 14 HTI         Haiti       XX         N             2013     2012 consump~
#> 15 HTI         Haiti       XX         N             2015     2012 consump~
#> 16 HTI         Haiti       XX         N             2018     2012 consump~
#> # ... with 24 more variables: isinterpolated <dbl>, usemicrodata <dbl>,
#> #   ppp <dbl>, povertyline <dbl>, mean <dbl>, headcount <dbl>,
#> #   povertygap <dbl>, povertygapsq <dbl>, watts <dbl>, gini <dbl>,
#> #   median <dbl>, mld <dbl>, polarization <dbl>, population <dbl>,
#> #   decile1 <dbl>, decile2 <dbl>, decile3 <dbl>, decile4 <dbl>, decile5 <dbl>,
#> #   decile6 <dbl>, decile7 <dbl>, decile8 <dbl>, decile9 <dbl>, decile10 <dbl>

Compute custom aggregates

The povcalnet function can also be used to compute aggregate welfare statistics of custom group of countries

# World aggregate
povcalnet(country = "all", aggregate = TRUE)
#> # A tibble: 16 x 9
#>    regiontitle regioncode  year povertyline  mean headcount povertygap
#>    <chr>       <chr>      <dbl>       <dbl> <dbl>     <dbl>      <dbl>
#>  1 World Total WLD         2018         1.9   NA     NA        NA     
#>  2 World Total WLD         2015         1.9  462.     0.100     0.0310
#>  3 World Total WLD         2013         1.9  445.     0.112     0.0334
#>  4 World Total WLD         2012         1.9  436.     0.128     0.0375
#>  5 World Total WLD         2011         1.9  429.     0.137     0.0405
#>  6 World Total WLD         2010         1.9  423.     0.157     0.0465
#>  7 World Total WLD         2008         1.9  412.     0.181     0.0540
#>  8 World Total WLD         2005         1.9  384.     0.207     0.0630
#>  9 World Total WLD         2002         1.9  361.     0.255     0.0823
#> 10 World Total WLD         1999         1.9  340.     0.286     0.0953
#> 11 World Total WLD         1996         1.9  331.     0.295     0.0981
#> 12 World Total WLD         1993         1.9  317.     0.340     0.120 
#> 13 World Total WLD         1990         1.9  322.     0.360     0.128 
#> 14 World Total WLD         1987         1.9  317.     0.355     0.126 
#> 15 World Total WLD         1984         1.9  303.     0.394     0.147 
#> 16 World Total WLD         1981         1.9  296.     0.423     0.180 
#> # ... with 2 more variables: povertygapsq <dbl>, population <dbl>

# Custom aggregate
povcalnet(country = c("CHL", "ARG", "BOL"), aggregate = TRUE)
#> # A tibble: 16 x 9
#>    regiontitle regioncode  year povertyline  mean headcount povertygap
#>    <chr>       <chr>      <dbl>       <dbl> <dbl>     <dbl>      <dbl>
#>  1 XX          XX          2018         1.9  651.    0.0137    0.00518
#>  2 XX          XX          2015         1.9  652.    0.0147    0.00657
#>  3 XX          XX          2013         1.9  655.    0.0162    0.00721
#>  4 XX          XX          2012         1.9  634.    0.0188    0.00869
#>  5 XX          XX          2011         1.9  619.    0.0183    0.00739
#>  6 XX          XX          2010         1.9  583.    0.0294    0.0124 
#>  7 XX          XX          2008         1.9  551.    0.0355    0.0153 
#>  8 XX          XX          2005         1.9  476.    0.0566    0.0254 
#>  9 XX          XX          2002         1.9  334.    0.130     0.0575 
#> 10 XX          XX          1999         1.9  452.    0.0764    0.0419 
#> 11 XX          XX          1996         1.9  464.    0.0651    0.0345 
#> 12 XX          XX          1993         1.9  470.    0.0496    0.0206 
#> 13 XX          XX          1990         1.9  452.    0.0502    0.0179 
#> 14 XX          XX          1987         1.9  570.    0.0547    0.0183 
#> 15 XX          XX          1984         1.9  591.    0.0628    0.0211 
#> 16 XX          XX          1981         1.9  575.    0.0416    0.0149 
#> # ... with 2 more variables: povertygapsq <dbl>, population <dbl>