/*==================================================
project:       Interaction with the PIP API at the country level
Author:        R.Andres Castaneda 
Dependencies:  The World Bank
----------------------------------------------------
Creation Date:     5 Jun 2019 - 15:12:13
Modification Date:  October, 2021 
Do-file version:    01
References:          
Output:             dta
==================================================*/

/*==================================================
0: Program set up
==================================================*/
program define pip_cl, rclass
syntax ,   server(string)        ///
handle(string)        ///
[                       ///
country(string)       ///
year(string)          ///
povline(numlist)      ///
ppp_year(numlist)          ///
coverage(string)      /// 
clear                 ///
pause                 /// 
iso                   /// 
noDIPSQuery           /// 
version(string)       ///
]

version 16.0

if ("`pause'" == "pause") pause on
else                      pause off

qui {
	/*==================================================
	conditions and setup 
	==================================================*/
	
	
	local base = "`server'/`handle'/pip"
	
	
	if ("`povline'" == "")  local povline  1.9
	if ("`ppp_year'" == "")      local ppp_year      -1
	if ("`coverage'" == "") local coverage -1
	
	*---------- download guidance data
	pip_info, clear justdata `pause' 
	
	tempname pip_lkup
	frame copy _pip_lkupb `pip_lkup', replace
	
	frame `pip_lkup' {
		
		
		
		
		levelsof country_code, local(countries) clean
		if (lower("`country'") != "all") {
			
			local uniq_country : list uniq country
			
			local ncountries: list uniq_country  - countries
			local avai_country: list uniq_country  & countries
			
			local countries:  list country | avai_country
			
		}
		
		if ("`ncountries'" != "") {
			if wordcount("`ncountries'") == 1 local be "is"
			if wordcount("`ncountries'") > 1 local be "are"
			
			noi disp as err "Warning: " _c
			noi disp as input `"`ncountries' `be' not part of the country list"' /* 
			*/ _n "available in PIP. See {stata povcalnet info}"
			
		}	
		
		if ("`countries'" == "") {
			noi disp in red "None of the countries provided in {it:country()} is available in PIP"
			error
		}
		
		*---------- alternative macros
		local ct = "`countries'" 
		local pl = "`povline'" 
		local pp = "`ppp'"     
		local yr = "`year'"    
		local cv = "`coverage'"
		
		/*==================================================
		1: Evaluate parameters
		==================================================*/
		
		*----------1.1: counting words
		
		local nct = wordcount("`ct'")  // number of countries
		local npl = wordcount("`pl'")  // number of poverty lines
		local npp = wordcount("`pp'")  // number of PPP values
		local nyr = wordcount("`yr'")  // number of years
		local ncv = wordcount("`cv'")  // number of coverage
		
		matrix A = `nct' \ `npl' \ `npp' \ `nyr' \ `ncv'
		mata:  A = st_matrix("A"); /* 
		*/    B = ((A :== A[1]) + (A :== 1) :>= 1); /* 
		*/    st_local("m", strofreal(mean(B)))
		
		if (`m' != 1) {
			noi disp in r "number of elements in options {it:povline(), ppp(), year()} and " _n /* 
			*/ "{it:coverage()} must be equal to 1 or to the number of countries in option {it:country()}"
			error 197
		}
		
		*----------1.2: Expand macros of size one
		local n = _n
		foreach o in pl pp yr cv {
			if (`n`o'' == 1) {
				local `o': disp _dup(`nct') " ``o'' "
			}
		}
		
		/*==================================================
		2:  Download data
		==================================================*/
		
		*----------2.1: download data
		tempfile clfile
		local queryfull "`base'?format=csv"
		return local queryfull = "`queryfull'"
		
	} // end of temp frame
	
	
	cap import delimited  "`queryfull'", `clear' asdouble
	if (_rc) {
		noi dis ""
		noi dis in red "It was not possible to download data from the PIP API."
		noi dis ""
		noi dis in white `"(1) Please check your Internet connection by "' _c 
		noi dis in white  `"{browse "`server'/`handle'/health-check" :clicking here}"'
		noi dis in white `"(2) Test that the data is retrievable. By"' _c
		noi dis in white  `"{stata pip test: clicking here }"' _c
		noi dis in white  "you should be able to download the data."
		noi dis in white `"(3) Please consider adjusting your Stata timeout parameters. For more details see {help netio}"'
		noi dis in white `"(4) Please send us an email to:"'
		noi dis in white _col(8) `"email: data@worldbank.org"'
		noi dis in white _col(8) `"subject: pip query error on `c(current_date)' `c(current_time)'"'
		noi di ""
		error 673
	}
	
	*---------- 2.2 create filter conditions in loop
	local j = 0
	local n = 1
	local kquery = ""   // whole filter condition to extract data
	foreach ict of local countries {
		
		* corresponding element to each country
		foreach o in pl yr pp cv {
			local i`o': word `n' of ``o''
		}
		
		*---------- coverage
		if inlist("`icv'", "-1", "all") & ("`ipp'" == "-1") {
			local kquery "`kquery' | (country_code == "`ict'" & reporting_year == `iyr')"
			return local kquery_`j' = "`kquery_`j''"
		} 
		else if inlist("`icv'", "-1", "all") & ("`ipp'" != "-1") {
			local kquery "`kquery' | (country_code == "`ict'"  & reporting_year == `iyr'  & ppp ==  "`ipp'")"
			return local kquery_`j' = "`kquery_`j''"
		}
		else if !inlist("`icv'", "-1", "all") & ("`ipp'" == "-1") {
			local kquery "`kquery' | (country_code == "`ict'"  & reporting_year == `iyr'  & survey_coverage == "`icv'")"
			return local kquery_`j' = "`kquery_`j''"
		} 
		else {
			local kquery "`kquery' | (country_code == "`ict'"  & reporting_year == `iyr'  & ppp ==  "`ipp'"  & survey_coverage == "`icv'")"
			return local kquery_`j' = "`kquery_`j''"
		}
		
		local ++j
		local ++n
	} 
	
	local kquery : subinstr  local kquery  "|" " "
	keep if `kquery'
	
}
end
exit
/* End of do-file */

><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><

Notes:
1.
2.
3.


Version Control: