diff --git a/README.md b/README.md index 9f4f5b3..4f100c9 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ [![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 3/7/2020] +[Last update 21/7/2020] `kit_livingincome` provides stata ado-files to produce tables and charts of the Gap to the Living Income Benchmark. @@ -22,6 +22,15 @@ Marcelo Tyszler. KIT Royal Tropical Institute, Netherlands. m.tyszler@kit.nl Carlos de los Rios. COSA. cd@thecosa.org +#### Other Contributors + +Elena Serfilippi. KIT Royal Tropical Institute, Netherlands. + +Esther Smits. KIT Royal Tropical Institute, Netherlands. + +Suchitra Yegna Narayan. Laudes Foundation + + ### Requirements * Stata version 13 @@ -76,7 +85,7 @@ or help kitli_compare2bm ``` -And take notice of the version and date at the top. The latest version is _v1.1, 03jul2020_ +And take notice of the version and date at the top. The latest version is _v1.2, 21jul2020_ ## Citation diff --git a/kit_livingincome.pkg b/kit_livingincome.pkg index 9903642..8795366 100644 --- a/kit_livingincome.pkg +++ b/kit_livingincome.pkg @@ -1,4 +1,4 @@ -v 1.1 +v 1.2 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: 20200703 +d Distribution-Date: 20200721 d F kitli_gap2bm.ado F kitli_gap2bm.sthlp diff --git a/kit_livingincome.zip b/kit_livingincome.zip index 2fe9676..a717ca4 100644 Binary files a/kit_livingincome.zip and b/kit_livingincome.zip differ diff --git a/kitli_compare2bm.ado b/kitli_compare2bm.ado index 461240d..4be1bb4 100644 --- a/kitli_compare2bm.ado +++ b/kitli_compare2bm.ado @@ -29,21 +29,23 @@ To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/ ----------------------------------------------------------------------------- Last Update: -3/07/2020 +21/07/2020 *****************************************************************************/ version 13 capture program drop kitli_compare2bm -program define kitli_compare2bm, sortpreserve +program define kitli_compare2bm, sortpreserve rclass syntax varname(numeric) [if] [in], /// hh_income(varname numeric) /// [grouping_var(varname numeric) /// + label_benchmark(string) /// ytitle(string) /// spacing(real 0.02) /// + placement(string) /// step_size(integer -1) /// colors(string) /// - show_graph /// + show_distribution_graph /// show_detailed_graph /// show_bar_graph /// save_graph_as(string) /// @@ -56,19 +58,25 @@ program define kitli_compare2bm, sortpreserve 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 ) { - display as error "WARNING: Graph options will be ignored if neither {it:show_graph} nor {it:show_detailed_graph} are requested." + if "`show_distribution_graph'" == "" & "`show_detailed_graph'" == "" & ("`colors'" !="" | "`ytitle'" !="" | `spacing' !=0.02 | `step_size' != -1 | "`placement'" !="" ) { + display as error "WARNING: Graph options will be ignored if neither {it:show_distribution_graph} nor {it:show_detailed_graph} are requested." } * Save graph can only be used if graph is 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." + if "`save_graph_as'" !="" & "`show_detailed_graph'" == "" & "`show_distribution_graph'" == "" & "`show_bar_graph'" == "" { + display as error "WARNING: {it:save_graph_as} will be ignored if neither {it:show_distribution_graph} nor {it:show_detailed_graph} nor {it:show_bar_graph} are requested." } - ** load defaults in case optional arguments are skipped: + ** load defaults in case optional arguments are skipped: + capture confirm existence `label_benchmark' + if _rc == 6 { + local label_benchmark = "Living Income Benchmark" + } + capture confirm existence `colors' if _rc == 6 { local colors = "ebblue%30 | blue%30 | green%30 | orange%30" @@ -79,6 +87,15 @@ program define kitli_compare2bm, sortpreserve local ytitle = "Proportion of households (%)" } + capture confirm existence `placement' + if _rc == 6 { + local placement = "right" + } + + if "`placement'" != "right" & "`placement'" != "left" { + display as error "WARNING: {it:placement} is provided with value different than {it:right} or {it:left}. This may cause errors in rendering the graph. Consult the help file for valid parameter values" + } + ******************************************** * Identify groups: if "`grouping_var'" !="" { @@ -120,7 +137,7 @@ program define kitli_compare2bm, sortpreserve } ******************************************** - if "`show_graph'" !="" | "`show_detailed_graph'" !="" | { + if "`show_distribution_graph'" !="" | "`show_detailed_graph'" !="" | { local Note_full = `""N (All) = `r(N)'""' local labels_cmd = `"label( 1 "All") "' @@ -221,6 +238,11 @@ program define kitli_compare2bm, sortpreserve capture drop temp_x_`group' temp_y_`group' capture tempvar temp_x_`group' temp_y_`group' kdensity `hh_income' if `grouping_var' == `group' & `touse', gen(`temp_x_`group'' `temp_y_`group'') nograph kernel(gaus) `extras' + if `r(scale)' == . { + display as error "ERROR: density estimation failed. Please check variables provided, and/or provide a different step size for estimation" + error 321 + exit + } qui: replace `temp_y_`group'' = `temp_y_`group''*`r(scale)' qui: sum `temp_y_`group'' local current_max = max(`r(max)',`current_max') @@ -245,9 +267,19 @@ program define kitli_compare2bm, sortpreserve capture tempvar temp_x temp_y if "`grouping_var'" !="" { kdensity `hh_income' if `touse' & `grouping_var' !=., gen(`temp_x' `temp_y') nograph kernel(gaus) `extras' + if `r(scale)' == . { + display as error "ERROR: density estimation failed. Please check variables provided, and/or provide a different step size for estimation" + error 321 + exit + } } else { qui: kdensity `hh_income' if `touse' , gen(`temp_x' `temp_y') nograph kernel(gaus) `extras' + if `r(scale)' == . { + display as error "ERROR: density estimation failed. Please check variables provided, and/or provide a different step size for estimation" + error 321 + exit + } } qui: replace `temp_y' = `temp_y'*`r(scale)' qui: sum `temp_y' @@ -307,12 +339,12 @@ program define kitli_compare2bm, sortpreserve capture graph drop "detailed_`counter'" line `temp_y_`group'' `temp_x_`group'', color(`this_color') recast(area) /// ytitle("`ytitle'") `ticks_x' `ticks_y' xlabel(, labsize(small)) note("`Note'") graphregion(color(white)) /// - legend(label( 1 "`group_label'") label(2 "Living Income Benchmark") label(3 "mean") label(4 "median")) || /// + legend(label( 1 "`group_label'") label(2 "`label_benchmark'") label(3 "mean") label(4 "median")) || /// pci 0 `li_benchmark_`counter'' `h' `li_benchmark_`counter'', color(red) || /// pci 0 `this_mean' `h' `this_mean', color(blue) || /// pci 0 `this_median' `h' `this_median', color(green) /// xtitle("`hh_income_label'") /// - text(`h' `li_benchmark_`counter'' "`share_li_`counter'' below the benchmark", place(right)) /// + text(`h' `li_benchmark_`counter'' "`share_li_`counter'' below the benchmark", place(`placement')) /// name("detailed_`counter'") if "`save_graph_as'" != "" { @@ -347,12 +379,12 @@ program define kitli_compare2bm, sortpreserve capture graph drop "detailed_all_groups" line `temp_y' `temp_x', color(`this_color') recast(area) /// ytitle("`ytitle'") `ticks_x' `ticks_y' xlabel(, labsize(small)) note("`Note'") graphregion(color(white)) /// - legend(label( 1 "All groups") label(2 "Living Income Benchmark") label(3 "mean") label(4 "median")) || /// + legend(label( 1 "All groups") label(2 "`label_benchmark'") label(3 "mean") label(4 "median")) || /// pci 0 `li_benchmark_`counter'' `h' `li_benchmark_`counter'', color(red) || /// pci 0 `this_mean' `h' `this_mean', color(blue) || /// pci 0 `this_median' `h' `this_median', color(green) /// xtitle("`hh_income_label'") /// - text(`h' `li_benchmark_`counter'' "`share_li_`counter'' below the benchmark", place(right)) /// + text(`h' `li_benchmark_`counter'' "`share_li_`counter'' below the benchmark", place(`placement')) /// name("detailed_all_groups") if "`save_graph_as'" != "" { @@ -386,12 +418,12 @@ program define kitli_compare2bm, sortpreserve capture graph drop "detailed" line `temp_y' `temp_x', color(`this_color') recast(area) /// ytitle("`ytitle'") `ticks_x' `ticks_y' xlabel(, labsize(small)) note("`Note'") graphregion(color(white)) /// - legend(label( 1 "All") label(2 "Living Income Benchmark") label(3 "mean") label(4 "median")) || /// + legend(label( 1 "All") label(2 "`label_benchmark'") label(3 "mean") label(4 "median")) || /// pci 0 `li_benchmark_`counter'' `h' `li_benchmark_`counter'', color(red) || /// pci 0 `this_mean' `h' `this_mean', color(blue) || /// pci 0 `this_median' `h' `this_median', color(green) /// xtitle("`hh_income_label'") /// - text(`h' `li_benchmark_`counter'' "`share_li_`counter'' below the benchmark", place(right)) /// + text(`h' `li_benchmark_`counter'' "`share_li_`counter'' below the benchmark", place(`placement')) /// name("detailed") if "`save_graph_as'" != "" { @@ -402,7 +434,7 @@ program define kitli_compare2bm, sortpreserve } - if "`show_graph'" !="" | { + if "`show_distribution_graph'" !="" | { ** All together ** Decide on the heights, ordering by benchmark value: if "`grouping_var'" !="" { @@ -459,7 +491,7 @@ program define kitli_compare2bm, sortpreserve gettoken this_color all_colors: all_colors, parse("|") } local group_bm_line = "`group_bm_line' || pci 0 `li_benchmark_`counter'' `h_`counter'' `li_benchmark_`counter'', color(`this_color')" - local group_bm_box = `"`group_bm_box' text(`h_`counter'' `li_benchmark_`counter'' "Living Income `group_label': `share_li_`counter'' below", size(small) place(right) box margin(1 1 1 1) fcolor(`this_color'))"' + local group_bm_box = `"`group_bm_box' text(`h_`counter'' `li_benchmark_`counter'' "`label_benchmark' `group_label': `share_li_`counter'' below", size(small) place(`placement') box margin(1 1 1 1) fcolor(`this_color'))"' local counter = `counter'+1 @@ -470,7 +502,7 @@ program define kitli_compare2bm, sortpreserve else { gettoken this_color all_colors: all_colors, parse("|") local group_bm_line = " || pci 0 `li_benchmark_1' `h_1' `li_benchmark_1', color(`this_color')" - local group_bm_box = `" text(`h_1' `li_benchmark_1' "Living Income Benchmark: `share_li_1' below", size(small) place(right) box margin(1 1 1 1) fcolor(`this_color'))"' + local group_bm_box = `" text(`h_1' `li_benchmark_1' "`label_benchmark': `share_li_1' below", size(small) place(`placement') box margin(1 1 1 1) fcolor(`this_color'))"' } @@ -486,7 +518,7 @@ program define kitli_compare2bm, sortpreserve * save graph * if "`save_graph_as'" != "" { - graph export "`save_graph_as'.png", as(png) width(1000) replace + graph export "`save_graph_as' distribution.png", as(png) width(1000) replace } } @@ -520,12 +552,12 @@ program define kitli_compare2bm, sortpreserve 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")) /// + stack legend(label(1 "Share of observations below the `label_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") /// + title("Share of observations below the `label_benchmark'") /// note(`Note_full') @@ -535,13 +567,17 @@ program define kitli_compare2bm, sortpreserve } - ******************************************** - * display table with results + *************************************************** + * display table with results (and store in r-class) + + local txt_spacing = 35 + local txt_spacing = max(`txt_spacing', strlen("Below the `label_benchmark': ")) display in b _newline - display in b "Share of observations below the Living Income Benchmark" + display in b "Share of observations below the `label_benchmark'" if "`grouping_var'" !="" { // show per group, than total + return local grouping_var = "`grouping_var'" ** per groups foreach group in `group_levels' { @@ -550,11 +586,13 @@ program define kitli_compare2bm, sortpreserve qui: sum `temp_bm_not_achieved' if `grouping_var' == `group' & `touse' local share_li = `r(mean)'*100 + return scalar share_below_`group' = `share_li' + return scalar N_`group' = `r(N)' display in b "" display in b "`group_label'" display in b "n = `r(N)'" display in b "" - display as text %35s "Below the Living Income Benchmark: " /* + display as text %`txt_spacing's "Below the `label_benchmark': " /* */ as result /* */ %9.1f `share_li' "%" di as text "{hline 73}" @@ -563,11 +601,13 @@ program define kitli_compare2bm, sortpreserve ** all groups together qui: sum `temp_bm_not_achieved' if `grouping_var' != . & `touse' local share_li = `r(mean)'*100 + return scalar share_below = `share_li' + return scalar N = `r(N)' display in b "" display in b "All groups" display in b "n = `r(N)'" display in b "" - display as text %35s "Below the Living Income Benchmark: " /* + display as text %`txt_spacing's "Below the `label_benchmark': " /* */ as result /* */ %9.1f `share_li' "%" di as text "{hline 73}" @@ -576,10 +616,12 @@ program define kitli_compare2bm, sortpreserve qui: sum `temp_bm_not_achieved' if `touse' local share_li = `r(mean)'*100 + return scalar share_below = `share_li' + return scalar N = `r(N)' display in b "" display in b "n = `r(N)'" display in b "" - display as text %35s "Below the Living Income Benchmark: " /* + display as text %`txt_spacing's "Below the `label_benchmark': " /* */ as result /* */ %9.1f `share_li' "%" di as text "{hline 73}" diff --git a/kitli_compare2bm.sthlp b/kitli_compare2bm.sthlp index 2d73e2f..46298cf 100644 --- a/kitli_compare2bm.sthlp +++ b/kitli_compare2bm.sthlp @@ -1,11 +1,12 @@ {smcl} -{* *! version 1.1 03jul2020}{...} -{it: v1.1, 03jul2020} +{* *! version 1.2 21jul2020}{...} +{it: v1.2, 21jul2020} {title:Title} {phang} -{bf:(KIT) Living Income Tools} {hline 2} Tables and density (kernel smoothened) plots about the total household income with the goal of comparing to the benchmark value, optionally by groups. +{bf:(KIT) Living Income Tools} {hline 2} Tables, density (kernel smoothened) and bar plots about +the total household income with the goal of comparing to the benchmark value, optionally by groups. {marker syntax}{...} {title:Syntax} @@ -28,17 +29,24 @@ {synopt :{opth grouping_var:(varname)}} grouping variable {p_end} +{syntab: Labels} + +{synopt :{opt label_benchmark:(text)}} Text for benchmark name. Default "Living Income Benchmark" {p_end} + {syntab: Graph options} {synopt :{opt ytitle:(text)}} Text for y axis. Default "Proportion of households (%)" {p_end} {synopt :{opt spacing:(number)}} Value for spacing between the boxes of the combined graph of all groups. Defaults to 0.02 {p_end} +{synopt :{opt placement:(text)}} Placement of the boxes of the indicating the share of those below the benchmark. Defaults to {it:right}. {p_end} {synopt :{opt step_size:(integer)}} Value for step size in the x-axis. Defaults to a value calculated internally {p_end} {synopt :{opt colors:(text)}} String with colors for the graph. Default "ebblue%30 | blue%30 | green%30 | orange%30" {p_end} {syntab: Graph exporting} -{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_distribution_graph}} shows a distribution graph comparing to the benchmark {p_end} +{synopt :{cmd:show_detailed_graph}} shows detailed distribution graphs +(separated graphs per group if grouping variables is provided) +comparing to the benchmark, including 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} @@ -58,6 +66,9 @@ a detailed graph per group and a combined graph. {pstd} {browse "https://docs.wixstatic.com/ugd/0c5ab3_93560a9b816d40c3a28daaa686e972a5.pdf"} +{pstd} This function includes options to customize key elements of the graphs. +Please notice, however, that all graphs can be further edited using Stata's {help graph_editor} capabilities. + {title:Arguments} @@ -82,6 +93,9 @@ a detailed graph per group and a combined graph. {pmore} {opth grouping_var:(varname)} grouping variable. If specified, density charts will have one curve per group. {p_end} +{dlgtab: Labels} +{pmore} +{opth label_benchmark:(text)} Text for benchmark name. If not specified, {it:Living Income Benchmark} is shown. {p_end} {dlgtab: Graph options} @@ -92,7 +106,15 @@ a detailed graph per group and a combined graph. {opt spacing:(number)} Value for spacing between the boxes of the combined graph of all groups. Only relevant if grouping_var:(varname) is provided. Defaults to 0.02 {p_end} {pmore} -{opt step_size:(integer)} Value for step size in the x-axis. Bin size for the density calculation is set as half of this value. If ommitted, it is calculated internally. Because the internal calculation might not suit all ranges of values, the user can choose to override its value {p_end} +{opt placement:(text)} Placement of the boxes/text in the graphs. Defaults to {it:right}, i.e., the boxes are placed to the right of the benchmark line. +Typically, one might want to use {it:left} as an alternative, if the text gets cut-off to the right. +See {help compassdirstyle} for more valid options. {p_end} + +{pmore} +{opt step_size:(integer)} Value for step size in the x-axis. Bin size for the density calculation is set as half of this value. +If ommitted, it is calculated internally. +Because the internal calculation might not suit all ranges of values, +the user can choose to override its value {p_end} {pmore} {opt colors:(text)} Colors for the curves. Multiple colors need to be separated by a "|". Default "ebblue%30 | blue%30 | green%30 | orange%30". {p_end} @@ -103,17 +125,22 @@ a detailed graph per group and a combined graph. {dlgtab: Graph exporting} {pmore} -{cmd:show_graph} shows the main graph, all (groups) compared to the benchmark {p_end} +{cmd:show_distribution_graph} shows a distribution graph (with groups overlayed, if provided), +comparing to the benchmark {p_end} {pmore} -{cmd:show_detailed_graph} shows the detailed graphs, i.e. distribution, benchmark, mean and median, per group if groups as provided. {p_end} +{cmd:show_detailed_graph} shows detailed distribution graphs, i.e. distribution, benchmark, mean and median values +, as separated graphs per group if groups are provided. {p_end} {pmore} -{cmd:show_bar_graph} shows a bar graph with the share of those below the benchmark, per group if groups as provided. {p_end} +{cmd:show_bar_graph} shows a bar graph with the share of those below the benchmark, per group if groups are 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} +{opt save_graph_as:(text)} Main stub for the filename used for saving the graphs. Graphs are in png format (appended to the filename). +Distribution graphs have the word {it:distribution} appended, +detailed graphs have the word {it: detailed} appended, +and bar graphs have the word {it: bar} appended. +Finally, group graphs have the group label appended to the file name. {p_end} @@ -139,6 +166,22 @@ the bar graph has the word {it: bar} appended and group graphs have the group la {phang}{cmd:. kitli_compare2bm benchmark, hh_income(total_hh_income_2018) grouping_var(grouping) show_detailed_graph} ({stata "kitli_compare2bm benchmark, hh_income(total_hh_income_2018) grouping_var(grouping) show_detailed_graph":{it:click to run}}) {p_end} +{title:Saved results} + +{pstd} +{cmd:kitli_compare2bm} saves the following in {cmd:r()}, depending on the options provided: + +{synoptset 20 tabbed}{...} +{p2col 5 35 24 2: Scalars}{p_end} +{pmore} +{it: If groups are provided, the results names are appended with the group number} {p_end} + +{synopt:{cmd:r(N)}}number of observations{p_end} +{synopt:{cmd:r(share_below)}}share of those below the benchmark{p_end} + +{p2col 5 20 24 2: Macros}{p_end} +{synopt:{cmd:r(grouping_var)}}variable used for groupings{p_end} + {title:Citation} {phang} diff --git a/kitli_gap2bm.ado b/kitli_gap2bm.ado index b6c8611..df5247f 100644 --- a/kitli_gap2bm.ado +++ b/kitli_gap2bm.ado @@ -30,19 +30,20 @@ To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/ ----------------------------------------------------------------------------- Last Update: -3/07/2020 +21/07/2020 *****************************************************************************/ version 13 capture program drop kitli_gap2bm -program define kitli_gap2bm, sortpreserve +program define kitli_gap2bm, sortpreserve rclass syntax varname(numeric) [if] [in], /// hh_income(varname numeric) /// [main_income(varname numeric) /// food_value(varname numeric) /// metric(string) /// grouping_var(varname numeric) /// + label_benchmark(string) /// label_currency(string) /// label_time(string) /// label_hh_income(string) /// @@ -136,6 +137,10 @@ program define kitli_gap2bm, sortpreserve if _rc == 6 { local metric = "mean" } + capture confirm existence `label_benchmark' + if _rc == 6 { + local label_benchmark = "Living Income Benchmark" + } capture confirm existence `label_currency' if _rc == 6 { local label_currency = "USD" @@ -254,7 +259,7 @@ program define kitli_gap2bm, sortpreserve } * Elements for the tables: - local text_tbl = "Gap of the median income to the (median) Living Income Benchmark" + local text_tbl = "Gap of the median income to the (median) `label_benchmark'" * Elements for the graphs local this_title = "Median values" @@ -292,7 +297,7 @@ program define kitli_gap2bm, sortpreserve } * Elements for the tables: - local text_tbl = "Gap of the mean income to the (mean) Living Income Benchmark" + local text_tbl = "Gap of the mean income to the (mean) `label_benchmark'" * Elements for the graphs local this_title = "Mean values" @@ -323,7 +328,7 @@ program define kitli_gap2bm, sortpreserve * Elements for the tables: - local text_tbl = "FGT gap to the Living Income Benchmark" + local text_tbl = "FGT gap to the `label_benchmark'" * Elements for the graphs local this_title = "FGT index" @@ -380,12 +385,45 @@ program define kitli_gap2bm, sortpreserve ******************************************** - * display table with results + * display table with results (and store in r-class) + + local txt_spacing = 35 + + if "`metric'" != "FGT" { // mean of median + if "`main_income'" != "" { + local txt_spacing = max(`txt_spacing', strlen("`label_main_income':")) + local txt_spacing = max(`txt_spacing', strlen( "`label_other_than_main_income':")) + } + else { + local txt_spacing = max(`txt_spacing', strlen("`label_hh_income':")) + } + + if "`food_value'" != "" { + local txt_spacing = max(`txt_spacing', strlen("`label_food_value':")) + } + + local txt_spacing = max(`txt_spacing', strlen("Gap to the `label_benchmark':")) + } + else { //FGT + local txt_spacing = max(`txt_spacing', strlen("FGT index:")) + } + + return local metric = "`metric'" + + if "`metric'" != "FGT" { + if "`as_share'" == "as_share" { + return local calculation = "share" + } + else { + return local calculation = "level" + } + } display in b _newline display in b "`text_tbl'" if "`grouping_var'" !="" { // show per group + return local grouping_var = "`grouping_var'" qui: levelsof `grouping_var' if `touse', local(group_levels) @@ -395,48 +433,55 @@ program define kitli_gap2bm, sortpreserve local group_label: label (`grouping_var') `group' qui: sum `temp_gap2benchmark' if `grouping_var' == `group' & `touse' + return scalar N_`group' = `r(N)' display in b "" display in b "`group_label'" display in b "n = `r(N)'" display in b "" - display as text %35s "" as text "`this_ytitle'" + display as text %`txt_spacing's "" as text "`this_ytitle'" di as text "{hline 73}" if "`metric'" != "FGT" { // mean of median if "`main_income'" != "" { qui: sum `temp_mainincome' if `grouping_var' == `group' & `touse' - display as text %35s "`label_main_income':" /* + return scalar main_income_`group' = `r(mean)' + display as text %`txt_spacing's "`label_main_income':" /* */ as result /* */ %9.0f `r(mean)' "`show_pct'" qui: sum `temp_other_than_main' if `grouping_var' == `group' & `touse' - display as text %35s "`label_other_than_main_income':" /* + return scalar other_than_main_income_`group' = `r(mean)' + display as text %`txt_spacing's "`label_other_than_main_income':" /* */ as result /* */ %9.0f `r(mean)' "`show_pct'" } else { - qui: sum `temp_totalincome' if `grouping_var' == `group' & `touse' - display as text %35s "`label_hh_income':" /* + qui: sum `temp_totalincome' if `grouping_var' == `group' & `touse' + return scalar total_income_`group' = `r(mean)' + display as text %`txt_spacing's "`label_hh_income':" /* */ as result /* */ %9.0f `r(mean)' "`show_pct'" } if "`food_value'" != "" { qui: sum `temp_foodvalue' if `grouping_var' == `group' & `touse' - display as text %35s "`label_food_value':" /* + return scalar food_value_`group' = `r(mean)' + display as text %`txt_spacing's "`label_food_value':" /* */ as result /* */ %9.0f `r(mean)' "`show_pct'" } qui: sum `temp_gap2benchmark' if `grouping_var' == `group' & `touse' - display as text %35s "Gap to the Living Income Benchmark:" /* + return scalar gap_`group' = `r(mean)' + display as text %`txt_spacing's "Gap to the `label_benchmark':" /* */ as result /* */ %9.0f `r(mean)' "`show_pct'" } else { //FGT qui: sum `temp_gap2benchmark' if `grouping_var' == `group' & `touse' - display as text %35s "FGT index:" /* + return scalar FGT_`group' = `r(mean)' + display as text %`txt_spacing's "FGT index:" /* */ as result /* */ %9.0f `r(mean)' "%" @@ -444,10 +489,11 @@ program define kitli_gap2bm, sortpreserve di as text "{hline 73}" if "`as_share'" == "as_share" | "`metric'" == "FGT" { - display as text %35s "" as text "`benchmark_unit'" + display as text %`txt_spacing's "" as text "`benchmark_unit'" } qui: sum `temp_benchmark' if `grouping_var' == `group' & `touse' - display as text %35s "Living Income Benchmark" /* + return scalar benchmark_`group' = `r(mean)' + display as text %`txt_spacing's "`label_benchmark'" /* */ as result /* */ %9.0f `r(mean)' @@ -457,47 +503,54 @@ program define kitli_gap2bm, sortpreserve else { // no groups qui: sum `temp_gap2benchmark' if `touse' + return scalar N = `r(N)' display in b "" display in b "n = `r(N)'" display in b "" - display as text %35s "" as text "`this_ytitle'" + display as text %`txt_spacing's "" as text "`this_ytitle'" di as text "{hline 73}" if "`metric'" != "FGT" { // mean of median if "`main_income'" != "" { qui: sum `temp_mainincome' if `touse' - display as text %35s "`label_main_income':" /* + return scalar main_income = `r(mean)' + display as text %`txt_spacing's "`label_main_income':" /* */ as result /* */ %9.0f `r(mean)' "`show_pct'" qui: sum `temp_other_than_main' if `touse' - display as text %35s "`label_other_than_main_income':" /* + return scalar other_than_main_income = `r(mean)' + display as text %`txt_spacing's "`label_other_than_main_income':" /* */ as result /* */ %9.0f `r(mean)' "`show_pct'" } else { qui: sum `temp_totalincome' if `touse' - display as text %35s "`label_hh_income':" /* + return scalar total_income = `r(mean)' + display as text %`txt_spacing's "`label_hh_income':" /* */ as result /* */ %9.0f `r(mean)' "`show_pct'" } if "`food_value'" != "" { - qui: sum `temp_foodvalue' if `touse' - display as text %35s "`label_food_value':" /* + qui: sum `temp_foodvalue' if `touse' + return scalar food_value = `r(mean)' + display as text %`txt_spacing's "`label_food_value':" /* */ as result /* */ %9.0f `r(mean)' "`show_pct'" } qui: sum `temp_gap2benchmark' if `touse' - display as text %35s "Gap to the Living Income Benchmark:" /* + return scalar gap = `r(mean)' + display as text %`txt_spacing's "Gap to the `label_benchmark':" /* */ as result /* */ %9.0f `r(mean)' "`show_pct'" } else { //FGT qui: sum `temp_gap2benchmark' if `touse' - display as text %35s "FGT index:" /* + return scalar FGT = `r(mean)' + display as text %`txt_spacing's "FGT index:" /* */ as result /* */ %9.0f `r(mean)' "%" @@ -505,10 +558,11 @@ program define kitli_gap2bm, sortpreserve di as text "{hline 73}" if "`as_share'" == "as_share" | "`metric'" == "FGT" { - display as text %35s "" as text "`benchmark_unit'" + display as text %`txt_spacing's "" as text "`benchmark_unit'" } qui: sum `temp_benchmark' if `touse' - display as text %35s "Living Income Benchmark" /* + return scalar benchmark = `r(mean)' + display as text %`txt_spacing's "`label_benchmark'" /* */ as result /* */ %9.0f `r(mean)' } @@ -517,7 +571,7 @@ program define kitli_gap2bm, sortpreserve * Generate graphs if "`show_graph'" !="" { - ** preare notes for the graphs: + ** prepare notes for the graphs: if "`grouping_var'" !="" { local Note_full = `""Based on:""' @@ -541,7 +595,7 @@ program define kitli_gap2bm, sortpreserve if "`metric'" == "FGT" { graph bar (mean) `temp_gap2benchmark' if `touse' `this_over' /// - stack legend(label(1 "FGT index")) /// + stack legend(label(1 "FGT index") size(vsmall)) /// ytitle("`this_ytitle'") `this_ylabel' /// bar(1, color(`color_gap')) /// blabel(bar, format(%9.0f) position(center) ) /// @@ -553,7 +607,7 @@ program define kitli_gap2bm, sortpreserve else if "`main_income'" != "" { if "`food_value'" == "" { // no food graph bar (mean) `temp_mainincome' `temp_other_than_main' `temp_gap2benchmark' if `touse' `this_over' /// - stack legend(label(1 "`label_main_income'") label(2 "`label_other_than_main_income'") label(3 "Gap to the Living Income Benchmark")) /// + stack legend(label(1 "`label_main_income'") label(2 "`label_other_than_main_income'") label(3 "Gap to the `label_benchmark'") size(vsmall)) /// ytitle("`this_ytitle'") `this_ylabel' /// bar(1, color(`color_main_income')) /// bar(2, color(`color_other_than_main_income')) /// @@ -565,7 +619,7 @@ program define kitli_gap2bm, sortpreserve } else { // with food graph bar (mean) `temp_mainincome' `temp_other_than_main' `temp_foodvalue' `temp_gap2benchmark' if `touse' `this_over' /// - stack legend(label(1 "`label_main_income'") label(2 "`label_other_than_main_income'") label(3 "`label_food_value'") label(4 "Gap to the Living Income Benchmark") size(vsmall)) /// + stack legend(label(1 "`label_main_income'") label(2 "`label_other_than_main_income'") label(3 "`label_food_value'") label(4 "Gap to the `label_benchmark'") size(vsmall)) /// ytitle("`this_ytitle'") `this_ylabel' /// bar(1, color(`color_main_income')) /// bar(2, color(`color_other_than_main_income')) /// @@ -580,7 +634,7 @@ program define kitli_gap2bm, sortpreserve else { if "`food_value'" == "" { // no food graph bar (mean) `temp_totalincome' `temp_gap2benchmark' if `touse' `this_over' /// - stack legend(label(1 "`label_hh_income'") label(2 "Gap to the Living Income Benchmark")) /// + stack legend(label(1 "`label_hh_income'") label(2 "Gap to the `label_benchmark'") size(vsmall)) /// ytitle("`this_ytitle'") `this_ylabel' /// bar(1, color(`color_hh_income')) /// bar(2, color(`color_gap')) /// @@ -591,7 +645,7 @@ program define kitli_gap2bm, sortpreserve } else { // with food graph bar (mean) `temp_totalincome' `temp_foodvalue' `temp_gap2benchmark' if `touse' `this_over' /// - stack legend(label(1 "`label_hh_income'") label(2 "`label_food_value'") label(3 "Gap to the Living Income Benchmark") size(vsmall)) /// + stack legend(label(1 "`label_hh_income'") label(2 "`label_food_value'") label(3 "Gap to the `label_benchmark'") size(vsmall)) /// ytitle("`this_ytitle'") `this_ylabel' /// bar(1, color(`color_hh_income')) /// bar(2, color(`color_gap')) /// diff --git a/kitli_gap2bm.sthlp b/kitli_gap2bm.sthlp index a2ad1ee..b08e66f 100644 --- a/kitli_gap2bm.sthlp +++ b/kitli_gap2bm.sthlp @@ -1,6 +1,6 @@ {smcl} -{* *! version 1.1 03jul2020}{...} -{it: v1.1, 03jul2020} +{* *! version 1.2 21jul2020}{...} +{it: v1.2, 21jul2020} {title:Title} @@ -43,8 +43,9 @@ {synopt :{opth grouping_var:(varname)}} grouping variable {p_end} -{syntab: Graph labels} +{syntab: Labels} +{synopt :{opt label_benchmark:(text)}} Text for benchmark name. Default "Living Income Benchmark" {p_end} {synopt :{opt label_currency:(text)}} Text for currency name. Default "USD" {p_end} {synopt :{opt label_time:(text)}} Text for time period name. Default "year" {p_end} {synopt :{opt label_hh_income:(text)}} Text for total income Default "Total income". Used if {opth main_income:(varname)} is NOT provided {p_end} @@ -83,6 +84,9 @@ {pstd} It computes, optionally, the mean or median household income and breaks it down into main income, other income, gap to the living income benchmark. Optionally it includes the intrinsic value of food crops produced and consumed at home. Optionally, it computes the FGT index. +{pstd} This function includes options to customize key elements of the graphs. +Please notice, however, that all graphs can be further edited using Stata's {help graph_editor} capabilities. + {title:Arguments} @@ -150,7 +154,10 @@ above the benchmark line. {p_end} {opth grouping_var:(varname)} grouping variable. If specified, tables will be per group and bar charts will have one bar per group. {p_end} -{dlgtab: Graph labels} +{dlgtab: Labels} +{pmore} +{opth label_benchmark:(text)} Text for benchmark name. If not specified, {it:Living Income Benchmark} is shown. {p_end} + {pmore} {opth label_currency:(text)} Text for currency name. If not specified, {it:USD} is shown. {p_end} @@ -196,7 +203,7 @@ above the benchmark line. {p_end} {cmd:show_graph} shows graph comparing to the benchmark {p_end} {pmore} -{opt save_graph_as:(text)} main stub of filename to be saved. Graphs will be saved as png format. {p_end} +{opt save_graph_as:(text)} main stub of filename to be saved. Graphs will be saved as png format (appended to the filename). {p_end} @@ -249,6 +256,30 @@ above the benchmark line. {p_end} ({stata "kitli_gap2bm benchmark, hh_income (total_hh_income_2018) main_income(total_cocoa_income_2018) food_value(food_value) grouping_var(grouping) show_graph":{it:click to run}}) {p_end} +{title:Saved results} + +{pstd} +{cmd:kitli_gap2bm} saves the following in {cmd:r()}, depending on the options provided: + +{synoptset 20 tabbed}{...} +{p2col 5 35 24 2: Scalars}{p_end} +{pmore} +{it: If groups are provided, the results names are appended with the group number} {p_end} + +{synopt:{cmd:r(N)}}number of observations{p_end} +{synopt:{cmd:r(main_income)}} mean or median of the main income{p_end} +{synopt:{cmd:r(other_than_main_income)}} mean or median of the other than main income{p_end} +{synopt:{cmd:r(total_income)}} mean or median of the total income{p_end} +{synopt:{cmd:r(food_value)}} mean or median of the intrinsic value of food produced and consumed at home{p_end} +{synopt:{cmd:r(gap)}} mean or median of gap to the benchmark value{p_end} +{synopt:{cmd:r(FGT)}} FGT index{p_end} +{synopt:{cmd:r(benchmark)}} mean or median of the benchmark value{p_end} + + +{p2col 5 20 24 2: Macros}{p_end} +{synopt:{cmd:r(metric)}}metric calculated: mean, median of FGT{p_end} +{synopt:{cmd:r(calculation)}}level or share{p_end} +{synopt:{cmd:r(grouping_var)}}variable used for groupings{p_end} {title:Citation} diff --git a/stata.toc b/stata.toc index 22958b2..8ae1378 100644 --- a/stata.toc +++ b/stata.toc @@ -1,4 +1,4 @@ -v 1.1 +v 1.2 d Marcelo Tyszler, PhD, KIT Royal Tropical Institute d d 'KIT_LIVINGINCOME': LIVING INCOME CALCULATIONS AND OUTPUTS: stata ado-file produces tables and charts of the Gap to the Living Income Benchmark