*! version 1.0.0 20 sep 2019

Title

povcalnet -- Access World Bank Global Poverty and Inequality measures.

Website: https://worldbank.github.io/povcalnet/

Syntax

povcalnet [subcommand],
[Parameters Options]

Parameters

country:(3-letter code) list of country code (accepts multiples) or all.
Cannot be used with option region()

region(WB code) list of region code (accepts multiple) or all.
Cannot be used with option country()

year(numlist|string) list of years (accepts up to 10), or all, or last. Default "all".

povline:(#) list of poverty lines (in 2011 PPP-adjusted USD) to calculate
poverty measures (accepts up to 5). Default is 1.9.

popshare:(#) list of population shares to calculate poverty lines (in 2011 PPP-adjusted USD) and poverty measures. No default. Do not combine with povline:

Options

clear replace data in memory.

aggregate calculates poverty measures for regions or user-specified
groups of countries instead of country-level estimated.

coverage(string) loads coverage level ("national", "urban", "rural", "all"). Default "all".

fillgaps loads all countries used to create regional aggregates.

information presents a clickable version of the available surveys, countries and regions.

ppp(#) allows the selection of PPP.

querytimes(integer) Number of times the API is hit before defaulting to failure.
Default is 5. Advance option. Just use it if Internet connection is poor

subcommands

information presents a clickable version of the available surveys,
countries and regions. Same as option information

cl country-level query that changes the default combinatorial
arrangement of parameters for a one-on-one correspondence.
See below for a detailed explanation.

wb downloads World Bank's regional and global aggregation

test executes the last query in browser regardless of failure by
povcalnet.

Internal options

server(string) This option is only available for developers of the
povcalnet package.

Note: povcalnet requires Internet connection.

Sections

Sections are presented under the following headings:

Command description
Parameters description
Options description
Subcommands
Stored results
Examples
Disclaimer
References
Acknowledgments
Authors
Contact
How to cite
Region and country codes

(Go up to Sections Menu)

Description

The povcalnet commands allows Stata users to compute poverty and inequality
indicators for more than 160 countries and regions in the World Bank's database of household
surveys. It has the same functionality as the PovcalNet website. PovcalNet is a
computational tool that allows users to estimate poverty rates for regions, sets of
countries or individual countries, over time and at any poverty line.

PovcalNet is managed jointly by the Data and Research Group in the World Bank's
Development Economics Division. It draws heavily upon a strong collaboration with the
Poverty and Equity Global Practice, which is responsible for the gathering and
harmonization of the underlying survey data.

In addition to the mean and median, povcalnet reports the following measures
for poverty (at chosen poverty line) and inequality:

Poverty measures Inequality measures

Headcount ratio Gini index
Poverty gap Mean log deviations
Poverty severity Decile shares
Watts index

The underlying welfare aggregate is per capita household income or consumption
expressed in 2011 PPP-adjusted USD. Poverty lines are expressed in daily amounts, while
means and medians are monthly. For more information on the definition of the indicators,
click here.
For more information on the methodology, click here

Type of calculations

:

The PovcalNet API allows two types of calculations:

Survey-year: Will load poverty measures for a reference year that is common
across countries. Regional and global aggregates are calculated only for
reference-years. Countries without a survey in the

reference-year: are extrapolated or interpolated using national accounts growth
rates, and assuming distribution-neutrality. povcalnet wb returns the global and
regional poverty aggregates used by the World Bank.

Important: Choosing option aggregate displays (population-weighted)
averages for the specified group of countries. Option fillgaps reports the
underlying lined-up country estimates for a reference-year. Poverty measures
calculated for both survey-years and reference-years include Headcount ratio,
Poverty Gap, Squared Poverty Gap. Inequality measures, including the Gini index,
mean log deviation and decile shares, are calculated only in survey-years where
micro data is available. Inequality measures are not reported for reference-years.

Combinatorial and one-on-one queries

:

Be default, povcalnet creates a combinatorial query of the parameters selected,
so that the output contains all the possible combinations between country(),
povline(), year(), and coverage(). Option ppp() is not part of the
combinatorial query. Alternatively, the user may select the subcommand cl to
parse a one-on-one (i.e., country by country) request. In this case, the first
country listed in country() will be combined with the first year in
year(), the first poverty lines in povline(), the first coverage area
in coverage(), and similarly for subsequent elements in the parameter
country(). If only one element is added to parameters povline(),
year(), or coverage(), it would be applied to all the elements in the
parameter countr(). caution: if only one element is added
to option ppp(), it would be applied to all the countries listed in country().

(Go up to Sections Menu)

Parameters description

country(string)Countries and Economies Abbreviations.
If specified with year(string), this option will return all the specific
countries and years for which there is actual survey data. When selecting multiple
countries, use the corresponding three-letter codes separated by spaces. The option
all is a shorthand for calling all countries.

region(string)Regions Abbreviations If
specified with year(string), this option will return all the specific countries
and years that belong to the specified region(s).
For example, region(LAC) will return all countries in Latin America and the
Caribbean for which there's an actual survey in the given years.
When selecting multiple regions, use the corresponding three-letter codes separated
by spaces. The option all is a shorthand for calling all regions, which is
equivalent to calling all countries.

year(#) Four digit years are accepted. When selecting multiple years, use
spaced to separate them. The option all is a shorthand for calling all
possible years, while the last option will download the latest available year
for each country.

povline(#) The poverty lines for which the poverty measures will be calculated.
When selecting multiple poverty lines, use less than 4 decimals and separate
each value with spaces. If left empty, the default poverty line of $1.9 is used.
Poverty lines are expressed in 2011 PPP-adjusted USD per capita per day.

povline(#) The desired population share (headcount) for which the poverty lines as poverty measures will be calculated.
This has not default, and should not be combined with povline.
The resulting poverty lines are expressed in 2011 PPP-adjusted USD per capita per day.

(Go up to Sections Menu)

Options description

aggregate Will calculate the aggregated poverty measures for the given set of
countries or regions.

Note 1: If option country(all) is combined with
option aggregate, povcalnet executes instead povcalnet wb,
which returns the
default global aggregates
used by the World Bank as explained in more detail below. In contrast, to aggregate
all countries in a particular reference year, users need to list them all in the
country() option. One way to do so is as follows:

. povcalnet info, clear
. levelsof country_code, local(all) clean
. povcalnet, country(`all') year(2015) clear aggregate

Note 2: Aggregation can only be done for the reference years (As of
Sep 2018: 1981, 1984, 1987, 1990, 1993, 1996, 1999, 2002, 2005, 2008, 2010, 2011,
2012, 2013 and 2015). Using the option last or all, povcalnet
loads the most up-to-date year(s).

fillgaps Loads all country-level estimates that are used to create the
aggregates in the reference years. This means that estimates use the same reference
years as aggregate estimates.

Note: Countries without a survey in the reference-year have been
extrapolated or interpolated using national accounts growth rates and assuming
distribution-neutrality (see Chapter 6
here).
Therefore, changes at the country-level from one reference year to the next need
to be interpreted carefully and may not be the result of a new household survey.

PPP(#) Allows the selection of PPP exchange rate. This option only
works if one, and only one, country is selected.

coverage(string) Selects coverage level of estimates. By default, all coverage
levels are loaded, but the user may select "national", "urban", or "rural".
Only one level of coverage can be selected per query.

information Presents a clickable version of the available surveys, countries
and regions. Selecting countries from the menu loads the survey-year estimates.
Choosing regions loads the regional aggregates in the reference years.

Note: If option clear is added, data in memory is replaced
with a PovcalNet guidance database. If option clear is not included,
povcalnet preserves data in memory but displays a clickable interface of survey
availability in the results window.

clear replaces data in memory.

(Go up to Sections Menu)

Subcommands

info Same as option info above.

cl Stands for country-level queries. It changes combinatorial query of parameters
for one-on-one correspondence of parameters. See above
for a detailed explanation.

wb Downloads World Bank's regional and global aggregation. These functions
differ from option aggregate in two ways: [1] wb uses a predefined set of countries
in each region, whereas option aggregate allows users to select their own set
of countries for aggregation. [2] The World Bank aggregation (queried by the wb
subcommand) assumes that the poverty rate for an economy without a household survey is
the regional average. This creates differences in two types of estimates: [a] When a
region includes countries without a household survey, the number of poor is different
between the two methods even when users query the same set of countries. The number of
poor according to the World Bank method is obtained as the product of the region’s
headcount index and the total regional population (which includes the population of
countries without any household survey). In contrast, when using aggregate,
the number of poor is the product of the region’s headcount index and the total
population of the economies included in the aggregation. [b] In computing the poverty
estimates for the world, the World Bank aggregation takes the population-weighted
average of the regional estimates. Each region is weighted using the total regional
population, including the population of countries without any household survey.
Countries without a survey are thus implicitly assigned the regional poverty rate. In
contrast, when using the option aggregate, only countries with a survey are considered
(which are then weighted by their population).

test Executes the last query in browser regardless of failure by
povcalnet. It makes use of the global "${pcn_query}".

Stored results

povcalnet stores the following in r(). Suffix _# refers to the number of
poverty lines included in povlines():

queries

r(query_ys_#) Years

r(query_pl_#) Poverty lines

r(query_ct_#) Countries and coverages

r(query_ds_#) Whether aggregation was used

r(query_#) concatenation of the queries above

API parts

r(server) Protocol (http://) and server name

r(site_name) Site names

r(handler) Action handler

r(base) concatenation of server, site_name, and handler

additional info

r(queryfull_#) Complete query

r(npl) Number of poverty lines

pcn_query Global macro with query information in case povcalnet fails.
"${pcn_query}" to display

Examples

(Go up to Sections Menu)

1. Basic examples

1.1. Load latest available survey-year estimates for Colombia and Argentina

povcalnet, country(col arg) year(last) clear

1.2. Load clickable menu

povcalnet, info

1.3. Load only urban coverage level

povcalnet, country(all) coverage("urban") clear

2. inIllustration of differences between queries

2.1. Country estimation at $1.9 in 2015. Since there are no surveys in ARG and IND in
2015, results are loaded for COL and BRA

povcalnet, country(COL BRA ARG IND) year(2015) clear

2.2. fill-gaps. Filling gaps for ARG and IND. Only works for reference years.

povcalnet, country(COL BRA ARG IND) year(2015) clear fillgaps

2.3. Estimate aggregates over the economies listed in country().

povcalnet, country(COL BRA ARG IND) year(2015) clear aggregate

2.4. World Bank aggregation (country() is not available)

povcalnet wb, clear year(2015)

povcalnet wb, clear region(SAR LAC)

povcalnet wb, clear // all reference years

2.5. One-on-one query.

povcalnet cl, country(COL BRA ARG IND) year(2011) clear coverage("national national urban national")

3. Samples uniquely identified by country/year

3.1 National coverage (when available) and longest possible time series for each country,
even if welfare type changes from one year to another.

. povcalnet, clear

* keep only national
. bysort countrycode datatype year: egen _ncover = count(coveragetype)
. gen _tokeepn = ( (inlist(coveragetype, 3, 4) & _ncover > 1) | _ncover == 1)

. keep if _tokeepn == 1

* Keep longest series per country
. by countrycode datatype, sort: gen _ndtype = _n == 1
. by countrycode : replace _ndtype = sum(_ndtype)
. by countrycode : replace _ndtype = _ndtype[_N] // number of datatype per country

. duplicates tag countrycode year, gen(_yrep) // duplicate year

.bysort countrycode datatype: egen _type_length = count(year) // length of type series
.bysort countrycode: egen _type_max = max(_type_length) // longest type series
.replace _type_max = (_type_max == _type_length)

* in case of same elngth in series, keep consumption
. by countrycode _type_max, sort: gen _ntmax = _n == 1
. by countrycode : replace _ntmax = sum(_ntmax)
. by countrycode : replace _ntmax = _ntmax[_N] // number of datatype per country

. gen _tokeepl = ((_type_max == 1 & _ntmax == 2) | ///
. (datatype == 1 & _ntmax == 1 & _ndtype == 2) | ///
. _yrep == 0)
.
. keep if _tokeepl == 1
. drop _*

(click to run)

3.2 National coverage (when available) and longest possible time series for each country, restrict to same welfare type throughout.

. bysort countrycode datatype year: egen _ncover = count(coveragetype)
. gen _tokeepn = ( (inlist(coveragetype, 3, 4) & _ncover > 1) | _ncover == 1)

. keep if _tokeepn == 1
* Keep longest series per country
. by countrycode datatype, sort: gen _ndtype = _n == 1
. by countrycode : replace _ndtype = sum(_ndtype)
. by countrycode : replace _ndtype = _ndtype[_N] // number of datatype per country

. bysort countrycode datatype: egen _type_length = count(year)
. bysort countrycode: egen _type_max = max(_type_length)
. replace _type_max = (_type_max == _type_length)

* in case of same elngth in series, keep consumption
. by countrycode _type_max, sort: gen _ntmax = _n == 1
. by countrycode : replace _ntmax = sum(_ntmax)
. by countrycode : replace _ntmax = _ntmax[_N] // max

. gen _tokeepl = ((_type_max == 1 & _ntmax == 2) | ///
. (datatype == 1 & _ntmax == 1 & _ndtype == 2)) | ///
. _ndtype == 1

. keep if _tokeepl == 1
. drop _*

(click to run)

4. Analytical examples

4.1 Graph of trend in poverty headcount ratio and number of poor for the world

. povcalnet wb, clear

. keep if year > 1989
. keep if regioncode == "WLD"
. gen poorpop = headcount*population
. gen hcpercent = round(headcount*100, 0.1)
. gen poorpopround = round(poorpop, 1)

. twoway (sc hcpercent year, yaxis(1) mlab(hcpercent) ///
. mlabpos(7) mlabsize(vsmall) c(l)) ///
. (sc poorpopround year, yaxis(2) mlab(poorpopround) ///
. mlabsize(vsmall) mlabpos(1) c(l)), ///
. yti("Poverty Rate (%)" " ", size(small) axis(1)) ///
. ylab(0(10)40, labs(small) nogrid angle(0) axis(1)) ///
. yti("Number of Poor (million)", size(small) axis(2)) ///
. ylab(0(400)2000, labs(small) angle(0) axis(2)) ///
. xlabel(,labs(small)) xtitle("Year", size(small)) ///
. graphregion(c(white)) ysize(5) xsize(5) ///
. legend(order( ///
. 1 "Poverty Rate (% of people living below $1.90)" ///
. 2 "Number of people who live below $1.90") si(vsmall) ///
. row(2)) scheme(s2color)

(click to run)

4.2 Graph of trends in poverty headcount ratio by region, multiple poverty lines ($1.9, $3.2, $5.5)

. povcalnet wb, povline(1.9 3.2 5.5) clear
. drop if inlist(regioncode, "OHI", "WLD") | year<1990
. keep povertyline region year headcount
. replace povertyline = povertyline*100
. replace headcount = headcount*100

. tostring povertyline, replace format(%12.0f) force
. reshape wide headcount,i(year region) j(povertyline) string

. local title "Poverty Headcount Ratio (1990-2015), by region"

. twoway (sc headcount190 year, c(l) msiz(small)) ///
. (sc headcount320 year, c(l) msiz(small)) ///
. (sc headcount550 year, c(l) msiz(small)), ///
. by(reg, title("`title'", si(med)) ///
. note("Source: PovcalNet", si(vsmall)) graphregion(c(white))) ///
. xlab(1990(5)2015 , labsi(vsmall)) xti("Year", si(vsmall)) ///
. ylab(0(25)100, labsi(vsmall) angle(0)) ///
. yti("Poverty headcount (%)", si(vsmall)) ///
. leg(order(1 "$1.9" 2 "$3.2" 3 "$5.5") r(1) si(vsmall)) ///
. sub(, si(small))	scheme(s2color)
(click to run)

4.3 Millions of poor by region

. povcalnet wb, clear
. keep if year > 1989
. gen poorpop = headcount * population
. gen hcpercent = round(headcount*100, 0.1)
. gen poorpopround = round(poorpop, 1)
. encode region, gen(rid)

. levelsof rid, local(regions)
. foreach region of local regions {
. local legend = `"`legend' `region' "`: label rid `region''" "'
. }

. keep year rid poorpop
. reshape wide poorpop,i(year) j(rid)
. foreach i of numlist 2(1)7{
. egen poorpopacc`i'=rowtotal(poorpop1 - poorpop`i')
. }

. twoway (area poorpop1 year) ///
. (rarea poorpopacc2 poorpop1 year) ///
. (rarea poorpopacc3 poorpopacc2 year) ///
. (rarea poorpopacc4 poorpopacc3 year) ///
. (rarea poorpopacc5 poorpopacc4 year) ///
. (rarea poorpopacc6 poorpopacc5 year) ///
. (rarea poorpopacc7 poorpopacc6 year) ///
. (line poorpopacc7 year, lwidth(midthick) lcolor(gs0)), ///
. ytitle("Millions of Poor" " ", size(small)) ///
. xtitle(" " "", size(small)) scheme(s2color) ///
. graphregion(c(white)) ysize(7) xsize(8) ///
. ylabel(,labs(small) nogrid angle(verticle)) xlabel(,labs(small)) ///
. legend(order(`legend') si(vsmall))
(click to run)

4.4 Graph of population distribution across income categories in Latin America, by country

. povcalnet, region(lac) year(last) povline(3.2 5.5 15) clear
. keep if datatype==2 & year>=2014 // keep income surveys
. keep povertyline countrycode countryname year headcount
. replace povertyline = povertyline*100
. replace headcount = headcount*100
. tostring povertyline, replace format(%12.0f) force
. reshape wide headcount,i(year countrycode countryname ) j(povertyline) string

. gen percentage_0 = headcount320
. gen percentage_1 = headcount550 - headcount320
. gen percentage_2 = headcount1500 - headcount550
. gen percentage_3 = 100 - headcount1500

. keep countrycode countryname year percentage_*
. reshape long percentage_,i(year countrycode countryname ) j(category)
. la define category 0 "Poor LMI (< $3.2)" 1 "Poor UMI ($3.2-$5.5)" ///
2 "Vulnerable ($5.5-$15)" 3 "Middle class (> $15)"
. la val category category
. la var category ""

. local title "Distribution of Income in Latin America and Caribbean, by country"
. local note "Source: PovcalNet, using the latest survey after 2014 for each country."
. local yti "Population share in each income category (%)"

. graph bar (mean) percentage, inten(*0.7) o(category) o(countrycode, ///
. lab(labsi(small) angle(vertical))) stack asy ///
. blab(bar, pos(center) format(%3.1f) si(tiny)) ///
. ti("`title'", si(small)) note("`note'", si(*.7)) ///
. graphregion(c(white)) ysize(6) xsize(6.5) ///
. legend(si(vsmall) r(3)) yti("`yti'", si(small)) ///
. ylab(,labs(small) nogrid angle(0)) scheme(s2color)
(click to run)

5. Calculating global and regional aggregates using country-level lined-up data

The povcalnet command can also be used to replicate the global and
regional estimates published by the World Bank starting from country-level
lined-up estimates. The user can access the code for this example here
https://povcalnet-team.github.io/Global-Regional-Estimates/.

(click to run)

Disclaimer

(Go up to Sections Menu)

PovcalNet was developed for the sole purpose of public replication of the
World Bank’s poverty measures for its widely used international poverty lines,
including $1.90 a day and $3.20 a day in 2011 PPP.
The methods built into PovcalNet are considered reliable for that purpose.

However, we cannot be confident that the methods work well for other
purposes, including tracing out the entire distribution of income. We would
especially warn that estimates of the densities near the bottom and top
tails of the distribution could be quite unreliable, and no attempt has been made
by the World Bank’s staff to validate the tool for such purposes.

The term country, used interchangeably with economy, does not imply
political independence but refers to any territory for which authorities report
separate social or economic statistics.

References

(Go up to Sections Menu)

Castaneda Aguilar, R. A., C. Lakner, E. B. Prydz, J. Soler Lopez, R. Wu and Q. Zhao (2019)
"Estimating Global Poverty in Stata: The povcalnet command", Global Poverty Monitoring Technical
Note, No. 9, World Bank, Washington, DC
Link

Acknowledgments

(Go up to Sections Menu)

The authors would like to thank Joao-Pedro Azevedo, Tony Fujs, Dean Jolliffe,
Aart Kraay, Kihoon Lee, Daniel Mahler, Minh Cong Nguyen, Marco Ranaldi and Prem
Sangraula, as well as seminar participants at the World Bank, for comments received
on earlier versions of this code. In developing this code, we closely followed the
example of wbopendata developed by Joao-Pedro Azevedo.

(Go up to Sections Menu)

Authors

R.Andres Castaneda, Christoph Lakner, Espen Beer Prydz, Jorge Soler Lopez,
Ruoxuan Wu, and Qinghua Zhao

Maintainer

R.Andres Castaneda, The World Bank

Email: acastanedaa@worldbank.org

GitHub: randrescastaneda

Contact

Any comments, suggestions, or bugs can be reported in the
GitHub issues page.
All the files are available in the GitHub repository

Thanks for citing povcalnet as follows

(Go up to Sections Menu)

Castaneda Aguilar, R. A., C. Lakner, E. B. Prydz, J. S. Lopez, R. Wu and Q. Zhao
(2019) "povcalnet: Stata module to access World Bank’s Global Poverty and Inequality data,"
Statistical Software Components 2019, Boston College Department of Economics.

Please make reference to the date when the database was downloaded, as statistics may change