Title

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

            povcalnet [subcommand], [Parameters Options]


          Parameters                   Description
          ------------------------------------------------------------------------------------------
            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.

          Options                      Description
          ------------------------------------------------------------------------------------------
            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.
            iso                         uses ISO3 for country/economy codes in the output.
            ppp(#)                      allows the selection of PPP.

          subcommands                  Description
          ------------------------------------------------------------------------------------------
            information                presents a clickable version of the available surveys,
                                         countries and regions. Same as option information
            cl                         parses the parameters of the query in a one-on-one
                                         correspondence instead of the default combinational query.
                                         See below for a detailed explanation.  See below for a
                                         detailed explanation.
            wb                         downloads World Bank's regional and global aggegation
            test                       executes the last query in browser regardless of failure by
                                         povcalnet.
          ------------------------------------------------------------------------------------------

          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
                      Acknowledgements
                      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 achosen 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.

                                              (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.

          iso Uses ISO3 for country/economy codes in output. However, users still need to use
              Countries and Economies Abbreviations when calling the command (i.e. option
              country()).

          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
              covarege 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 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

          addtional 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 avialable)

              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) fillgaps 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)



      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, J. S. Lopez, E. B. Prydz, R. Wu and Q. Zhao (2018)
              "Estimating Global Poverty in Stata: The povcalnet command", Global Poverty Monitoring
              Technical Note 107, World Bank. [NEED TO ADD HYPERLINK]

      Acknowledgements
                                              (Go up to Sections Menu)

          The authors would like to thank Tony Fujs, Dean Jolliffe, Aart Kraay, Kihoon Lee, Daniel
          Mahler and , Minh Cong Nguyen and Marco Ranaldi, 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,
          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, J. S. Lopez, E. B. Prydz, R. Wu and Q. Zhao (2019)
              "povcalnet: Stata module to access World Bank’s Global Poverty and Inequality data,"
              Statistical Software Components YYYY, Boston College Department of Economics.
              http://ideas.repec.org/c/boc/bocode/ZZZZZ.html

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