*! version 1.0.0 dec 2022

Title

pip -- Access poverty and inequality data from the
World Bank's Poverty and Inequality Platform (PIP).
The pip command allows Stata users to access the poverty and inequality indicators
available in the PIP platform and estimate poverty at any line. PIP contains more
indicators than its predecessor(povcalnet). See below for a comparison
between the indicators in the pip and povcalnet commands.

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

Syntax

pip [subcommand],
[Parameters Options]

Description of parameters and options

Parameters

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

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

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

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

povline:(#) List of poverty lines (in PPP specified, see option ppp_year(#)) to calculate
poverty measures (accepts up to 5). Default is 2.15 and 2017 PPPs.

popshare:(#) List of quantiles. No default. Cannot be used with option povline:

fillgaps Loads country-level estimates (including extrapolations and interpolations) used to create regional and global aggregates.

Options

version(string) Combination of numbers in the format %Y%m%d_YYYY_RV_AV_SSS
(click here for explanation of each component). This version() option supersedes
the next 3 options ppp_year(), release() & identity(), as the combination of these parameters uniquely identifies a dataset.

ppp_year:(#) PPP round (2011 or 2017).

release(numlist) 8 digit number with the PIP release date in the format YYYYMMDD.

identity(string)* Version of data to run the query on (e.g., prod, int, test). See description of each identity here.

server(string)* Name of server to query (e.g, prod, dev, qa). See description of each server here.

*Note: The server() and identity() options are available internally only for Bank staff.
For a detailed description of the server() and identity() options see here.

Operational

clear Replaces data in memory.

querytimes(integer) Number of times the API is hit before defaulting to failure.
Default is 5. Advanced option. Use only if internet connection is poor.

table(string) Loads one auxiliary table, this option is used along with the tables subcommand.

Subcommands

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

wb Downloads World Bank's regional and global aggregation.

tables Provides clickable list of auxiliary tables for download.

cleanup Deletes all pip data from current stata memory.

dropframe (Programmer's option) Deletes auxiliary PIP frames in memory.

dropglobal (Programmer's option) Deletes auxiliary PIP global macros in memory.

versions Display available versions of PIP data.

test Open in browser last pip call. Type disp "${pip_query}" to see the parameters of the API query.

Note: pip requires an internet connection.

Sections

Sections are presented under the following headings:

Command description
Memory use and frames
Parameters description
Options description
Operational description
Subcommands description
List of pip and povcalnet variables
Stored results
Examples
Disclaimer
References
Acknowledgments
Authors
Contact
How to cite
Region and country codes

(Go up to Sections Menu)

Description

The pip command has the same functionality as the PIP website.
It allows Stata users to compute poverty and inequality indicators for over 160 countries
in the World Bank's database of household surveys. PIP is a computational tool that allows
users to conduct country-specific, cross-country, as well as global and regional poverty analyses.
Users are able estimate rates over time and at any poverty line specified. pip reports a
wide range of measures for poverty (at any chosen poverty line) and inequality. See full list of indicators
available in pip below.

The underlying welfare aggregate is the per capita household income or consumption
expressed in 2017 PPP USD (with an option to select the 2011 PPPs). Poverty lines are expressed in daily amounts, as well as
the means and medians. For more information on the methodology, click here.

PIP is the result of a close collaboration between World Bank staff accross the Development Data Group, the Development Research Group, and the Poverty and Inequality Global Practice.

Memory use and frames

:

pip makes use of the `frames` feature--available since Stata 16--to store a lot of information in memory. This is partly the reason why the first call of pip in a new Stata session is slower compared to subsequent calls. When closing Stata, you may see a pop-up
message reading "Frames in memory have changed". That is perfectly normal and should not cause any concern.
However, make sure you save the frames that you created and wish to keep. You can do that by typing frames dir.
Frames created by pip are prefixed by _pip and are marked by an *, meaning they have not been saved. If you do not wish to save any frames in use, just click "Exit without saving." You can also delete all PIP data in memory using the command pip cleanup.

Type of calculations

:

The pip API reports two types of results:

Survey-year: Estimates refer to the survey period.

Reference-year: Loads poverty measures for a reference year that is common across countries.
Regional and global aggregates are calculated only for reference-years. Survey-year estimates are extrapolated
or interpolated to a common reference year. These extrapolations and interpolations require additional assumptions,
namely that (a) growth in household income or consumption can be approximated by growth in national accounts and
(b) all parts of the distribution grow at the same rate. pip wb returns the global and regional poverty aggregates
used by the World Bank.

Important: The option fillgaps reports the underlying country estimates for a reference-year.
These may coincide with the survey-year estimates if the country has a survey in the reference year. In other cases,
these would be extrapolated from the nearest survey or interpolated between two surveys.

Poverty measures that are calculated for both survey-years and reference-years include the headcount ratio, poverty gap,
and squared poverty gap. Inequality measures, including the Gini index, the mean log deviation and decile shares,
are calculated only in survey-years and are not reported for reference-years.

(Go up to Sections Menu)

Parameters description

country(string) Countries and Economies Abbreviations.
If specified with year(#), this option will return all the countries for which there is
actual survey data in the year specified. 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(#), this option will return all the countries in the specified region(s)
that have a survey in that year. For example, region(LAC) will return all countries in Latin
America and the Caribbean that have a survey in the specific year. 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.

coverage(string) Selects the geographic coverage of the 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.

year(#) Four digit years are accepted. When selecting multiple years, use
spaces to separate them. The option all is a shorthand for calling all
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 $2.15 is used.
By default, poverty lines are expressed in 2017 PPP USD per capita per day.
If option ppp_ppp(2011) is specified, the poverty lines are expressed in 2011 PPPs.

popshare(#) The desired quantile. For example, specifying popshare(0.1) returns the first
decile as the value of the poverty line. In other words, the estimated poverty line will be the
nearest income or consumption level such that the incomes of 10% of the population fall below it.
This has no default, and cannot be combined with povline. The quantile (recorded in the variable
poverty_line) is expressed in 2017 PPP USD per capita per day (unless option ppp_year(2011) is specified,
in which case it is reported in 2011 PPPs).

fillgaps Loads all country-level estimates that are used to create the
global and regional aggregates in the reference years.

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.

(Go up to Sections Menu)

Options description

version A detailed description of the version option is available here.

ppp_year Allows to specify PPP round (version) that will be used to calculate estimates. Default PPP round year is 2017. The other option are the 2011 PPPs.

release Allows to specify the PIP release date in the format YYYYMMDD.

identity A detailed description of the identity option is available here.

server A detailed description of the server option is available here.

(Go up to Sections Menu)

Operational description

clear replaces data in memory.

querytimes Number of times the API is hit before defaulting to failure. Default is 5. Advanced option. Use only if internet connection is poor.

table Allows to load one auxiliary table, this option is used along with tables subcommand.

(Go up to Sections Menu)

Subcommands

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 pip guidance database. If option clear is not included,
pip preserves data in memory but displays a clickable interface of survey
availability in the results window.

wb Download the World Bank's regional and global aggregates. It can be
combined with year() to filter the aggregated data.

tables Provides access to the auxiliary tables.
Default command pip tables a list of auxiliary tables using the 2017 PPPs.
Users can also specify PPP year as pip tables, ppp_year(2017).

cleanup Deletes all PIP data from Stata's memory.

test By typing pip test, pip makes use of the global
"${pip_query}" to query your browser directly and test whether the data is
downloadable.

install Install the stamble version of pip from SSC (pip install ssc) or
the development version from GitHub (pip install gh). the install subcommand
is intended to keep your search path clean. Say that you install the
dev version from GitHub in the regular way and then
you install the stable from SSC. By doing that, you are creating
two entries in the stata.trk file, making Stata believe that you have pip
installed twice, which in fact you do. You can confirm this by typing the following,

github install worldbank/pip // development
ssc install pip, replace // stable

* You can't uninstall pip directly
ado uninstall pip
criterion matches more than one package

* This is because you have two versions of pip installed
ado dir pip

[318] package pip from https://raw.githubusercontent.com/worldbank/pip/master
'PIP': Poverty and Inequality Platform Stata wrapper

[319] package pip from http://fmwww.bc.edu/repec/bocode/p
'PIP': module to access poverty and inequality data from the World Bank's Poverty and
Inequality Platform (PIP)

By using the install subcommand, pip makes sure all the conflicting installations
are solved. You can install pip from SSC and from GitHub, one after the other, and you
won't have conflicting installations.
Be aware that if you have more than one version installed in your search path,
pip is going to request you to confirm that you want to uninstall both versions by type
yes in the conosole and hitting enter.

pip install ssc

There is more than one version of PIP installed in the same search path, PLUS.
You need to uninstall pip in PLUS or change installation path with option path()
Type yes in the console and hit enter to confirm you agree to uninstall pip.

uninstall You can uninstall any version of pip in your search path by typing,
pip uninstall. In this way, you can install pip from scratch from either SSC
of GitHub.

update This subcommand makes sure your pip version is up to date. By default,
the first time that you use pip in a session, it will search for any new available versions
available on the either SSC of GitHub, depending on where you installed it from (this is
why the first time takes longer than the others). However, it could be the
case that you're using an old version on purpose and now want to get the newer version
without leaving your Stata session. Just type pip update.

Stored results

pip stores the following in r(). Suffix _# is a count of the
poverty line included in povlines():

queries

r(query_ys_#) Years

r(query_pl_#) Poverty lines

r(query_ct_#) Countries

r(query_cv_#) 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) Total number of poverty lines

pip_query Global macro with query information in case pip fails.
"${pip_query}" to display

(Go up to Sections Menu)

List of pip and povcalnet variables

The following list compares the variables names available in pip with its predecessor command povcalnet.
Only the variables available in povcalnet are listed.

pip variable povcalnet variable

country_code countrycode
country_name countryname
region_code regioncode
year year
welfare_time datayear
welfare_type datatype
poverty_line povertyline
mean mean
headcount headcount
poverty_gap povgap
poverty_severity povgapsqr
watts watts
gini gini
median median
mld mld
polarization polarization
population population
decile1 decile1
decile2 decile2
decile3 decile3
decile4 decile4
decile5 decile5
decile6 decile6
decile7 decile7
decile8 decile8
decile9 decile9
decile10 decile10
ppp ppp
is_interpolated isinterpolated
distribution_type usemicrodata
survey_coverage coveragetype

Examples

(Go up to Sections Menu)

1. Basic examples

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

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

1.2. Load clickable menu

pip, info

1.3. Load only urban coverage level

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

2. Illustration of differences between queries

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

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

2.2. Reference-year estimation. Filling gaps for ARG and moving the IND estimate
from 2015-2016 to 2015. Only works for reference years.

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

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

pip wb, clear year(2015)

pip wb, clear region(SAR LAC)

pip wb, clear // all regions and reference years

3. Samples uniquely identified by country/year

3.1 Longest possible time series for each country, even if welfare type or survey coverage
changes from one year to another (national coverage is preferred).

pip, clear
* Prepare reporting_level variable
label define level 3 "national" 2 "urban" 1 "rural"
encode reporting_level, gen(reporting_level_2) label(level)

* keep only national when more than one is available
bysort country_code welfare_type year: egen _ncover = count(reporting_level_2)
gen _tokeepn = ( (inlist(reporting_level_2, 3, 4) & _ncover > 1) | _ncover == 1)

keep if _tokeepn == 1

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

duplicates tag country_code year, gen(_yrep) // duplicate year

bysort country_code welfare_type: egen _type_length = count(year) // length of type series
bysort country_code: egen _type_max = max(_type_length) // longest type series
replace _type_max = (_type_max == _type_length)

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

gen _tokeepl = ((_type_max == 1 & _ntmax == 2) | ///
(welfare_type == 1 & _ntmax == 1 & _ndtype == 2) | ///
_yrep == 0)

keep if _tokeepl == 1
drop _*

(click to run)

3.2 Longest possible time series for each country, restrict to same welfare type throughout,
but letting survey coverage vary (preferring national).

pip, clear

* Prepare reporting_level variable
label define level 3 "national" 2 "urban" 1 "rural"
encode reporting_level, gen(reporting_level_2) label(level)

bysort country_code welfare_type year: egen _ncover = count(reporting_level_2)
gen _tokeepn = ( (inlist(reporting_level_2, 3, 4) & _ncover > 1) | _ncover == 1)

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

bysort country_code welfare_type: egen _type_length = count(year)
bysort country_code: egen _type_max = max(_type_length)
replace _type_max = (_type_max == _type_length)

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

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

keep if _tokeepl == 1
drop _*

(click to run)

3.3 Longest series for a country with the same welfare type.
Not necessarily the latest

pip, clear
*Series length by welfare type
bysort country_code welfare_type: gen series = _N
*Longest
bysort country_code : egen longest_series=max(series)
tab country_code if series !=longest_series
keep if series == longest_series

*2. If same length: keep most recent
bys country_code welfare_type series: egen latest_year=max(year)
bysort country_code: egen most_recent=max(latest_year)

tab country_code if longest_series==series & latest_year!=most_recent
drop if most_recent>latest_year

*3. Not Applicable: if equal length and most recent: keep consumption
bys country_code: egen preferred_welfare=min(welfare_type)
drop if welfare_type != preferred_welfare

(click to run)

4. Analytical examples

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

pip wb, clear

keep if year > 1989
keep if region_code == "WLD"
gen poorpop = headcount*population / 1000000
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 $2.15)" ///
2 "Number of people who live below $2.15") si(vsmall) ///
row(2)) scheme(s2color)

(click to run)

4.2 Graph of trends in poverty headcount ratio by region, multiple poverty lines ($2.15, $3.65, $6.85)

pip wb, povline(2.15 3.65 6.85) clear
drop if inlist(region_code, "OHI", "WLD") | year<1990
keep poverty_line region_name year headcount
replace poverty_line = poverty_line*100
replace headcount = headcount*100

tostring poverty_line, replace format(%12.0f) force
reshape wide headcount,i(year region_name) j(poverty_line) string

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

twoway (sc headcount215 year, c(l) msiz(small)) ///
(sc headcount365 year, c(l) msiz(small)) ///
(sc headcount685 year, c(l) msiz(small)), ///
by(reg, title("`title'", si(med)) ///
note("Source: pip", si(vsmall)) graphregion(c(white))) ///
ylabel(, format(%2.0f)) ///
xlab(1990(5)2019 , labsi(vsmall)) xti("Year", si(vsmall)) ///
ylab(0(25)100, labsi(vsmall) angle(0)) ///
yti("Poverty headcount (%)", si(vsmall)) ///
leg(order(1 "$2.15" 2 "$3.65" 3 "$6.85") r(1) si(vsmall)) ///
sub(, si(small))	scheme(s2color)
(click to run)

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

pip, region(lac) year(last) povline(2.15 3.65 6.85) clear
keep if welfare_type==2 & year>=2014 // keep income surveys
keep poverty_line country_code country_name year headcount
replace poverty_line = poverty_line*100
replace headcount = headcount*100
tostring poverty_line, replace format(%12.0f) force
reshape wide headcount,i(year country_code country_name ) j(poverty_line) string

gen percentage_0 = headcount215
gen percentage_1 = headcount365 - headcount215
gen percentage_2 = headcount685 - headcount365
gen percentage_3 = 100 - headcount685

keep country_code country_name year percentage_*
reshape long percentage_,i(year country_code country_name ) j(category)
la define category 0 "Extreme poor (< $2.15)" 1 "Poor LIMIC ($2.15-$3.65)" ///
2 "Poor UMIC ($3.65-$6.85)" 3 "Non-poor (> $6.85)"
la val category category
la var category ""

local title "Distribution of Income in Latin America and Caribbean, by country"
local note "Source: World Bank PIP, 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(country_code, ///
lab(labsi(small) angle(vertical)) sort(1) descending) 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)

Disclaimer

(Go up to Sections Menu)

To calculate global poverty estimates, survey-year estimates are extrapolated
or interpolated to a common reference year. These extrapolations and interpolations require
additional assumptions, namely that (a) growth in household income or consumption can be
approximated by growth in national accounts and (b) all parts of the distribution grow at
the same rate. Given these assumptions, users are cautioned against using reference-year
estimates (available using the fillgaps option) for comparing a country's poverty trend over time.
For that purpose, users should rely on the survey-year estimates and are advised to take into
account breaks in survey comparability. For details on the methodology please visit the
PIP Methodology Handbook and the Global Poverty Monitoring Technical Notes.

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.Andres, T. Fujs, C. Lakner, S. K. Tetteh-Baah(2023)
"Estimating Global Poverty in Stata: The PIP command",
Global Poverty Monitoring Technical Notes, World Bank, Washington, DC

Acknowledgments

(Go up to Sections Menu)

The author would like to thank Tefera Bekele Degefu, Ifeanyi Nzegwu Edochie, Tony Fujs,
Dean Jolliffe, Daniel Mahler, Minh
Cong Nguyen, Christoph Lakner, Marta Schoch, Samuel Kofi Tetteh Baah, Martha Viveros, Nishan Yonzan,
and Haoyu Wu for comments received on earlier versions of this code. This command builds on the earlier
povcalnet command, which was developed with the help of Espen Prydz, Jorge Soler Lopez, Ruoxuan Wu and Qinghua Zhao.

(Go up to Sections Menu)

Author

R.Andres Castaneda, The World Bank

Email: acastanedaa@worldbank.org

GitHub: randrescastaneda

Contributor

Tefera Bekele Degefu

Maintainer

PIP Technical Team, The World Bank

Email: pip@worldbank.org

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 this Stata command as follows

Castaneda, R.Andres. (2023)
"pip: Stata Module to Access World Bank’s Global Poverty and Inequality Data"
(version 0.9.0). Stata. Washington, DC: World Bank Group.
https://worldbank.github.io/pip/

Thanks for citing pip data as follows

World Bank. (2022). Poverty and Inequality Platform (version {version_ID})
[Data set]. World Bank Group. www.pip.worldbank.org. Accessed {date}

Available version_IDs:

2017 PPPs: 20220909_2017_01_02_PROD

2011 PPPs: 20220909_2011_02_02_PROD

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

(Go up to Sections Menu)