Merge pull request #4 from mtyszler/develop

Develop

README.md

@@ -2,16 +2,20 @@
 [![License: CC BY-SA 4.0](https://img.shields.io/badge/License-CC%20BY--SA%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by-sa/4.0/)
 
 ## Developed by [KIT](http://www.kit.nl) and [COSA](http://thecosa.org/)
-[Last update 16/6/2020] 
+[Last update 3/7/2020] 
 
-'kit_livingincome' provides stata ado-file to produce tables and charts of the Gap to the Living Income Benchmark
+`kit_livingincome` provides stata ado-files to produce tables and charts of the Gap to the Living Income Benchmark.
 
 It produces graphs similar to what can be seen at:
 
 https://www.kit.nl/wp-content/uploads/2019/01/Analysis-of-the-income.pdf
 
 https://docs.wixstatic.com/ugd/0c5ab3_93560a9b816d40c3a28daaa686e972a5.pdf
 
+A detailed Guidance Manual can be found at:
+
+https://www.living-income.com/papersandreports
+
 ### Authors
 
 Marcelo Tyszler. KIT Royal Tropical Institute, Netherlands. m.tyszler@kit.nl
@@ -22,7 +26,7 @@ Carlos de los Rios. COSA. cd@thecosa.org
 
 * Stata version 13 
 
-### Installing `kit_livingincome`
+## Installing `kit_livingincome`
 
 To install the latest development version directly from Github using stata `github` package, type: 
 ```
@@ -36,14 +40,52 @@ net from https://raw.githubusercontent.com/mtyszler/kit_livingincome/master/
 net install kit_livingincome
 ```
 
-### Citation
+### Alternative installation procedures
+
+If you have problems using the commands above, there are 2 possible work-arounds, using the [this zip file](kit_livingincome.zip)
+
+#### Manually installing into your ado library
+
+If using the default settings from STATA:
+
+Windows users: Create a folder called `C:\ado\personal\`, if not existent, and extract the contents of the zip file here.
+
+Mac OS X users: Create a folder called `~/ado/personal`, if not existent, and extract the contents of the zip file here.
+
+To verify your local setting type `sysdir` or `adopath` in STATA.
+
+For more details on how configure local folders type `help adopath` in STATA.
+
+#### Manually installing into your local folder
+
+If none of the options above worked, a final work-around is to extract the contents of the zip file to a local folder. 
+
+The commands will work only when this is the active STATA working directory.
+
+
+### Verifying the installation:
+
+To verify you have the latest version of the package successfully installed type:
+```
+help kitli_gap2bm
+```
+
+or
+
+```
+help kitli_compare2bm
+```
+
+And take notice of the version and date at the top. The latest version is _v1.1, 03jul2020_
+
+## Citation
 
 Please cite the package as follows:
 
 > Tyszler, et al. (2019). Living Income Calculations Toolbox. KIT ROYAL TROPICAL 
 INSTITUTE and COSA. Available at: https://github.com/mtyszler/KIT_LivingIncome/
 
-### License
+## License
 [![License: CC BY-SA 4.0](https://licensebuttons.net/l/by-sa/4.0/80x15.png)](https://creativecommons.org/licenses/by-sa/4.0/)
 
 This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License. 

kit_livingincome.pkg

@@ -1,4 +1,4 @@
-v 1.0
+v 1.1
 d 'kit_livingincome': LIVING INCOME CALCULATIONS AND OUTPUTS: stata package to produce tables and charts of the Gap to the Living Income Benchmark
 d Marcelo Tyszler, PhD, KIT Royal Tropical Institute
 d 
@@ -11,7 +11,7 @@ d
 d package maintained at:
 d https://github.com/mtyszler/KIT_LivingIncome/
 d 
-d Distribution-Date: 20206516
+d Distribution-Date: 20200703
 d
 F kitli_gap2bm.ado
 F kitli_gap2bm.sthlp

kitli_compare2bm.ado

@@ -29,7 +29,7 @@ To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/
 
 -----------------------------------------------------------------------------
 Last Update:
-16/6/2020
+3/07/2020
 
 *****************************************************************************/
 
@@ -45,6 +45,7 @@ program define kitli_compare2bm, sortpreserve
 	colors(string) ///
 	show_graph ///
 	show_detailed_graph ///
+	show_bar_graph ///
 	save_graph_as(string) ///
 	]
 
@@ -53,6 +54,7 @@ program define kitli_compare2bm, sortpreserve
 	********************************************
 	** Prepare observations which will be used 
 	marksample touse, novarlist
+	qui: replace `touse' = 0 if `varlist' == .
 
 	** color can only be provided if graph is requested:
 	if "`show_graph'" == ""  & "`show_detailed_graph'" == ""  & ("`colors'" !="" | "`ytitle'" !="" | `spacing' !=0.02 | `step_size' != -1 ) {
@@ -61,8 +63,8 @@ program define kitli_compare2bm, sortpreserve
 
 
 	* Save graph can only be used if graph is requested
-	if "`save_graph_as'" !="" & "`show_detailed_graph'" == ""  & "`show_graph'" == ""   {
-		display as error "WARNING: {it:save_graph_as} will be ignored if neither {it:show_graph} nor {it:show_detailed_graph} are requested."
+	if "`save_graph_as'" !="" & "`show_detailed_graph'" == ""  & "`show_graph'" == ""  & "`show_bar_graph'" == ""   {
+		display as error "WARNING: {it:save_graph_as} will be ignored if neither {it:show_graph} nor {it:show_detailed_graph}  nor {it:show_bar_graph} are requested."
 	}
 
 
@@ -174,7 +176,7 @@ program define kitli_compare2bm, sortpreserve
 			else if r(max) < = 5000 {
 				local w = 200
 			}
-			else if r(max) < = 10000 {
+			else if r(max) < = 20000 {
 				local w = 1000
 			}
 			else if r(max) < = 50000 {
@@ -488,6 +490,50 @@ program define kitli_compare2bm, sortpreserve
 			}
 		}
 
+	}
+
+	if "`show_bar_graph'" !="" {
+
+		local this_ylabel = " ylabel(0(10)100, grid)"
+
+		if "`grouping_var'" !="" {
+			local this_over = ", over(`grouping_var')"
+			local Note_full = ""
+
+			* Append group information:
+			if "`grouping_var'" !="" {
+
+				foreach group in `group_levels' {
+					qui: sum `hh_income' if  `grouping_var' == `group' & `touse'
+					local group_label: label (`grouping_var') `group'
+					local Note_full= `"`Note_full' "N (`group_label') = `r(N)'""'				
+				}
+			}
+		}
+		else {
+			local this_over = ", "
+			qui: sum `hh_income' if `touse'
+			local Note_full = `""N = `r(N)'""'
+		}
+
+		tempvar temp_bm_not_achieved_pct
+		qui: gen `temp_bm_not_achieved_pct' = `temp_bm_not_achieved'*100
+
+		graph bar (mean)  `temp_bm_not_achieved_pct' if `touse'  `this_over' ///
+		stack legend(label(1 "Share of observations below the Living Income Benchmark")) ///
+		ytitle("`ytitle'") `this_ylabel' ///
+		bar(1, color("red")) ///
+		blabel(bar, format(%9.0f) position(center) ) ///
+		graphregion(color(white)) bgcolor(white) ///
+		title("Share of observations below the Living Income Benchmark") ///
+		note(`Note_full')
+
+
+		if "`save_graph_as'" != "" {
+			graph export "`save_graph_as' bar.png", as(png) width(1000) replace 
+		}
+
+
 	}
 	********************************************
 	* display table with results

kitli_compare2bm.sthlp

@@ -1,5 +1,6 @@
 {smcl}
-{* *! version 1.0  16mjune2020}{...}
+{* *! version 1.1  03jul2020}{...}
+{it: v1.1, 03jul2020}
 
 {title:Title}
 
@@ -38,6 +39,7 @@
 
 {synopt :{cmd:show_graph}} shows main graph comparing to the benchmark  {p_end}
 {synopt :{cmd:show_detailed_graph}} shows detailed graphs (per group if gropuing variables is provided) comparing to the benchmark, mean and median values  {p_end}
+{synopt :{cmd:show_bar_graph}} shows a bar graph of the share below the benchmark  {p_end}
 {synopt :{opt save_graph_as:(text)}} main stub of filename to be saved. Graphs will be saved as png format {p_end}
 
 {synoptline}
@@ -46,7 +48,9 @@
 {title:Description}
 
 {pstd}
-{cmd: kitli_compare2bm} produces tables and density ({help kdensity:kernel smoothened}) plots as fractions about the distribution of total household income with the goal of comparing to the benchmark value. If a grouping variable is used, it creates, optionally, a detailed graph per group and a combined graph.
+{cmd: kitli_compare2bm} produces tables, bar charts and density ({help kdensity:kernel smoothened}) plots as fractions about the distribution of 
+total household income with the goal of comparing to the benchmark value. If a grouping variable is used, it creates, optionally, 
+a detailed graph per group and a combined graph.
 
 {pstd} It produces graphs similar to what can be seen at:
 
@@ -105,7 +109,12 @@
 {cmd:show_detailed_graph} shows the detailed graphs, i.e. distribution, benchmark, mean and median, per group if groups as provided. {p_end}
 
 {pmore}
-{opt save_graph_as:(text)} Main stub for graph saving. Graphs are in ong format. Detailed graphs have the word {it: detailed} appended and group graphs have the group label appended to the file name. {p_end}
+{cmd:show_bar_graph} shows a bar graph with the share of those below the benchmark, per group if groups as provided. {p_end}
+
+{pmore}
+{opt save_graph_as:(text)} Main stub for graph saving. Graphs are in png format. Detailed graphs have the word {it: detailed} appended, 
+the bar graph has the word {it: bar} appended and group graphs have the group label appended to the file name. {p_end}
+
 
 
 {title:Examples}
@@ -138,7 +147,7 @@ Please cite it as such:{p_end}
 
 {phang}
 Tyszler, et al. (2020). Living Income Calculations Toolbox. KIT ROYAL TROPICAL 
-INSTITUTE and COSA. Available at: {browse "include_later":m.tyszler@kit.nl} 
+INSTITUTE and COSA. Available at: {browse "https://github.com/mtyszler/KIT_LivingIncome/"} 
 {p_end}
 
 {phang}