diff --git a/README.md b/README.md index 4f100c9..65a154a 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 21/7/2020] +[Last update 24/7/2020] `kit_livingincome` provides stata ado-files to produce tables and charts of the Gap to the Living Income Benchmark. @@ -85,13 +85,13 @@ or help kitli_compare2bm ``` -And take notice of the version and date at the top. The latest version is _v1.2, 21jul2020_ +And take notice of the version and date at the top. The latest version is _v1.3, 24jul2020_ ## Citation Please cite the package as follows: -> Tyszler, et al. (2019). Living Income Calculations Toolbox. KIT ROYAL TROPICAL +> Tyszler, et al. (2020). Living Income Calculations Toolbox. KIT ROYAL TROPICAL INSTITUTE and COSA. Available at: https://github.com/mtyszler/KIT_LivingIncome/ ## License diff --git a/kit_livingincome.pkg b/kit_livingincome.pkg index 8795366..da2ab00 100644 --- a/kit_livingincome.pkg +++ b/kit_livingincome.pkg @@ -1,4 +1,4 @@ -v 1.2 +v 1.3 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: 20200721 +d Distribution-Date: 20200724 d F kitli_gap2bm.ado F kitli_gap2bm.sthlp diff --git a/kit_livingincome.zip b/kit_livingincome.zip index a717ca4..69bcb66 100644 Binary files a/kit_livingincome.zip and b/kit_livingincome.zip differ diff --git a/kitli_compare2bm.ado b/kitli_compare2bm.ado index 4be1bb4..9bdc052 100644 --- a/kitli_compare2bm.ado +++ b/kitli_compare2bm.ado @@ -29,7 +29,7 @@ To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/ ----------------------------------------------------------------------------- Last Update: -21/07/2020 +24/07/2020 *****************************************************************************/ @@ -39,7 +39,9 @@ program define kitli_compare2bm, sortpreserve rclass syntax varname(numeric) [if] [in], /// hh_income(varname numeric) /// [grouping_var(varname numeric) /// + food_value(varname numeric) /// label_benchmark(string) /// + label_food_value(string) /// ytitle(string) /// spacing(real 0.02) /// placement(string) /// @@ -57,6 +59,10 @@ program define kitli_compare2bm, sortpreserve rclass ** Prepare observations which will be used marksample touse, novarlist qui: replace `touse' = 0 if `varlist' == . + qui: replace `touse' = 0 if `hh_income' == . + if "`food_value'" !="" { + qui: replace `touse' = 0 if `food_value' == . + } ** color can only be provided if graph is requested: @@ -70,6 +76,11 @@ program define kitli_compare2bm, sortpreserve rclass 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." } + * food value matching matching elements + if "`label_food_value'" !="" & "`food_value'" == "" { + display as error "WARNING: {it:label_food_value} will be ignored if {it:food_value} is not provided." + } + ** load defaults in case optional arguments are skipped: capture confirm existence `label_benchmark' @@ -77,6 +88,11 @@ program define kitli_compare2bm, sortpreserve rclass local label_benchmark = "Living Income Benchmark" } + capture confirm existence `label_food_value' + if _rc == 6 { + local label_food_value = "(including the value of food)" + } + capture confirm existence `colors' if _rc == 6 { local colors = "ebblue%30 | blue%30 | green%30 | orange%30" @@ -111,12 +127,17 @@ program define kitli_compare2bm, sortpreserve rclass local li_benchmark = "`varlist'" * key components - tempvar temp_bm_not_achieved + tempvar temp_bm_not_achieved temp_hh_income + qui: gen `temp_hh_income' = `hh_income' if `touse' + if "`food_value'" !="" { + qui: replace `temp_hh_income' = `temp_hh_income' + `food_value' if `touse' + } + if "`grouping_var'" !="" { - qui: gen `temp_bm_not_achieved' = `hh_income' < `li_benchmark' if `touse' & `grouping_var' !=. & `hh_income' !=. & `li_benchmark'!=. + qui: gen `temp_bm_not_achieved' = `temp_hh_income' < `li_benchmark' if `touse' & `grouping_var' !=. & `temp_hh_income' !=. & `li_benchmark'!=. } else { - qui: gen `temp_bm_not_achieved' = `hh_income' < `li_benchmark' if `touse' & `hh_income' !=. & `li_benchmark'!=. + qui: gen `temp_bm_not_achieved' = `temp_hh_income' < `li_benchmark' if `touse' & `temp_hh_income' !=. & `li_benchmark'!=. } * for kernels @@ -126,10 +147,10 @@ program define kitli_compare2bm, sortpreserve rclass ******************************************** * Identify groups: if "`grouping_var'" !="" { - qui: sum `hh_income' if `touse' & `grouping_var' !=. + qui: sum `temp_hh_income' if `touse' & `grouping_var' !=. } else { - qui: sum `hh_income' if `touse' + qui: sum `temp_hh_income' if `touse' } if `r(N)' == 0 { @@ -143,6 +164,9 @@ program define kitli_compare2bm, sortpreserve rclass local labels_cmd = `"label( 1 "All") "' local hh_income_label: variable label `hh_income' + if "`food_value'" !="" { + local hh_income_label = `" "`hh_income_label'" "`label_food_value'" "' + } * Append group information: if "`grouping_var'" !="" { @@ -150,7 +174,7 @@ program define kitli_compare2bm, sortpreserve rclass local cmd_order = "order (1 " foreach group in `group_levels' { - qui: sum `hh_income' if `grouping_var' == `group' & `touse' + qui: sum `temp_hh_income' if `grouping_var' == `group' & `touse' local group_label: label (`grouping_var') `group' @@ -237,7 +261,7 @@ program define kitli_compare2bm, sortpreserve rclass 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' + kdensity `temp_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 @@ -266,7 +290,7 @@ program define kitli_compare2bm, sortpreserve rclass capture drop temp_x temp_y 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' + kdensity `temp_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 @@ -274,7 +298,7 @@ program define kitli_compare2bm, sortpreserve rclass } } else { - qui: kdensity `hh_income' if `touse' , gen(`temp_x' `temp_y') nograph kernel(gaus) `extras' + qui: kdensity `temp_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 @@ -316,7 +340,7 @@ program define kitli_compare2bm, sortpreserve rclass local counter = 1 foreach group in `group_levels' { local group_label: label (`grouping_var') `group' - qui: sum `hh_income' if `grouping_var' == `group' & `touse', det + qui: sum `temp_hh_income' if `grouping_var' == `group' & `touse', det local Note = "N = `r(N)'" local Note = "`Note', bin size = `w_2'" local this_mean = `r(mean)' @@ -343,7 +367,7 @@ program define kitli_compare2bm, sortpreserve rclass 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'") /// + xtitle(`hh_income_label') /// text(`h' `li_benchmark_`counter'' "`share_li_`counter'' below the benchmark", place(`placement')) /// name("detailed_`counter'") @@ -356,7 +380,7 @@ program define kitli_compare2bm, sortpreserve rclass local counter = `counter'+1 } - qui: sum `hh_income' if `touse' & `grouping_var' !=. , det + qui: sum `temp_hh_income' if `touse' & `grouping_var' !=. , det local Note = "N = `r(N)'" local Note = "`Note', bin size = `w_2'" local this_mean = `r(mean)' @@ -383,7 +407,7 @@ program define kitli_compare2bm, sortpreserve rclass 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'") /// + xtitle(`hh_income_label') /// text(`h' `li_benchmark_`counter'' "`share_li_`counter'' below the benchmark", place(`placement')) /// name("detailed_all_groups") @@ -395,7 +419,7 @@ program define kitli_compare2bm, sortpreserve rclass else { local counter = 1 - qui: sum `hh_income' if `touse', det + qui: sum `temp_hh_income' if `touse', det local Note = "N = `r(N)'" local Note = "`Note', bin size = `w_2'" local this_mean = `r(mean)' @@ -422,7 +446,7 @@ program define kitli_compare2bm, sortpreserve rclass 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'") /// + xtitle(`hh_income_label') /// text(`h' `li_benchmark_`counter'' "`share_li_`counter'' below the benchmark", place(`placement')) /// name("detailed") @@ -508,7 +532,7 @@ program define kitli_compare2bm, sortpreserve rclass capture graph drop "all_combined" line `temp_y' `temp_x', /// - ytitle("`ytitle'") `ticks_x' `ticks_y' xtitle("`hh_income_label'") /// + ytitle("`ytitle'") `ticks_x' `ticks_y' xtitle(`hh_income_label') /// xlabel(, labsize(small)) note(`Note_full') graphregion(color(white)) /// legend(`labels_cmd') /// `group_graph' /// @@ -536,7 +560,7 @@ program define kitli_compare2bm, sortpreserve rclass if "`grouping_var'" !="" { foreach group in `group_levels' { - qui: sum `hh_income' if `grouping_var' == `group' & `touse' + qui: sum `temp_hh_income' if `grouping_var' == `group' & `touse' local group_label: label (`grouping_var') `group' local Note_full= `"`Note_full' "N (`group_label') = `r(N)'""' } @@ -544,20 +568,26 @@ program define kitli_compare2bm, sortpreserve rclass } else { local this_over = ", " - qui: sum `hh_income' if `touse' + qui: sum `temp_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 + local this_title = "Share of observations below the `label_benchmark'" + if "`food_value'" !="" { + local this_title = `" "`this_title'" "`label_food_value'" "' + } + + graph bar (mean) `temp_bm_not_achieved_pct' if `touse' `this_over' /// 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 `label_benchmark'") /// + title(`this_title', size(medium)) /// note(`Note_full') @@ -575,6 +605,9 @@ program define kitli_compare2bm, sortpreserve rclass display in b _newline display in b "Share of observations below the `label_benchmark'" + if "`food_value'" !="" { + display in b "`label_food_value'" + } if "`grouping_var'" !="" { // show per group, than total return local grouping_var = "`grouping_var'" diff --git a/kitli_compare2bm.sthlp b/kitli_compare2bm.sthlp index 46298cf..6d3e160 100644 --- a/kitli_compare2bm.sthlp +++ b/kitli_compare2bm.sthlp @@ -1,6 +1,6 @@ {smcl} -{* *! version 1.2 21jul2020}{...} -{it: v1.2, 21jul2020} +{* *! version 1.3 24jul2020}{...} +{it: v1.3, 24jul2020} {title:Title} @@ -25,6 +25,10 @@ the total household income with the goal of comparing to the benchmark value, op {synopthdr:optional arguments} {synoptline} +{syntab: Income composition} + +{synopt :{opth food_value:(varname)}} {varname} of value attributable to food produced and consumed at home {p_end} + {syntab: Grouping} {synopt :{opth grouping_var:(varname)}} grouping variable {p_end} @@ -32,6 +36,8 @@ the total household income with the goal of comparing to the benchmark value, op {syntab: Labels} {synopt :{opt label_benchmark:(text)}} Text for benchmark name. Default "Living Income Benchmark" {p_end} +{synopt :{opt label_food_value:(text)}} Text for value of food. Default "(including the value of food)" added to the label of {opth hh_income:(varname)}. +Used if {opth food_value:(varname)} is provided {p_end} {syntab: Graph options} @@ -57,7 +63,8 @@ comparing to the benchmark, including mean and median values {p_end} {pstd} {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, +total household income with the goal of comparing to the benchmark value. Optionally it includes the intrinsic value of food crops produced and consumed at home. +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: @@ -88,6 +95,18 @@ Please notice, however, that all graphs can be further edited using Stata's {hel {pmore}{it:{cmd:li_benchmark} and {opth hh_income:(varname)} need to be in the same currency and unit (e.g., USD per household).} {p_end} +{dlgtab:Income composition} +{pmore} + +{pmore} +{opth food_value:(varname)} {varname} of the value of food produced and consumed at home. If provided, it is added to the total income. +The calculations are done only for complete observations, i.e., if {opth food_value:(varname)} is provided, +observations where +{opth food_value:(varname)} is missing will be excluded from the calculations. +If provided, it will be added to the {opth hh_income:(varname)} + +{pmore}{it: {opth food_value:(varname)} needs to be in the same currency and unit as {it:{cmd:li_benchmark}} (e.g., USD per household).} +{p_end} {dlgtab:Grouping} {pmore} @@ -97,6 +116,10 @@ Please notice, however, that all graphs can be further edited using Stata's {hel {pmore} {opth label_benchmark:(text)} Text for benchmark name. If not specified, {it:Living Income Benchmark} is shown. {p_end} +{pmore} +{opth label_food_value:(text)} Text for intrinsic value of food. If not specified, {it:(including the value of food)} is added to the label of {opth hh_income:(varname)}. +Only in case {it:food_value} is provided. {p_end} + {dlgtab: Graph options} {pmore} @@ -151,21 +174,46 @@ Finally, group graphs have the group label appended to the file name. {p_end} {phang}{cmd:. use https://raw.githubusercontent.com/mtyszler/KIT_LivingIncome/master/kitli_exampledata.dta} ({stata "use https://raw.githubusercontent.com/mtyszler/KIT_LivingIncome/master/kitli_exampledata.dta":{it:click to run}}) {p_end} -{phang}Comparison plots for all +{phang}Distribution plots for all -{phang}{cmd:. kitli_compare2bm benchmark, hh_income(total_hh_income_2018) show_graph } -({stata "kitli_compare2bm benchmark, hh_income(total_hh_income_2018) show_graph":{it:click to run}}) {p_end} +{phang}{cmd:. kitli_compare2bm benchmark, hh_income(total_hh_income_2018) show_distribution_graph } +({stata "kitli_compare2bm benchmark, hh_income(total_hh_income_2018) show_distribution_graph":{it:click to run}}) {p_end} -{phang}Comparison plots for all, saving +{phang}Distribution plots for all, saving -{phang}{cmd:. kitli_compare2bm benchmark, hh_income(total_hh_income_2018) show_graph save_graph_as(example_density)} -({stata "kitli_compare2bm benchmark, hh_income(total_hh_income_2018) show_graph save_graph_as(example_density)":{it:click to run}}) {p_end} +{phang}{cmd:. kitli_compare2bm benchmark, hh_income(total_hh_income_2018) show_distribution_graph save_graph_as(example_density)} +({stata "kitli_compare2bm benchmark, hh_income(total_hh_income_2018) show_distribution_graph save_graph_as(example_density)":{it:click to run}}) {p_end} -{phang}Comparison plots, by group +{phang}Distribution plots by groups + +{phang}{cmd:. kitli_compare2bm benchmark, hh_income(total_hh_income_2018) show_distribution_graph grouping_var(grouping) } +({stata "kitli_compare2bm benchmark, hh_income(total_hh_income_2018) show_distribution_graph grouping_var(grouping) ":{it:click to run}}) {p_end} + +{phang}Distribution plots by groups, with food value + +{phang}{cmd:. kitli_compare2bm benchmark, hh_income(total_hh_income_2018) food_value(food_value) show_distribution_graph grouping_var(grouping) } +({stata "kitli_compare2bm benchmark, hh_income(total_hh_income_2018) food_value(food_value) show_distribution_graph grouping_var(grouping) ":{it:click to run}}) {p_end} + +{phang}Detailed distribution plots, by group {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} +{phang}Detailed distribution plots, by group, with food value + +{phang}{cmd:. kitli_compare2bm benchmark, hh_income(total_hh_income_2018) food_value(food_value) grouping_var(grouping) show_detailed_graph} +({stata "kitli_compare2bm benchmark, hh_income(total_hh_income_2018) food_value(food_value) grouping_var(grouping) show_detailed_graph":{it:click to run}}) {p_end} + +{phang}Bar graph by groups + +{phang}{cmd:. kitli_compare2bm benchmark, hh_income(total_hh_income_2018) show_bar_graph grouping_var(grouping) } +({stata "kitli_compare2bm benchmark, hh_income(total_hh_income_2018) show_bar_graph grouping_var(grouping) ":{it:click to run}}) {p_end} + +{phang}Bar graph by groups, with food value + +{phang}{cmd:. kitli_compare2bm benchmark, hh_income(total_hh_income_2018) food_value(food_value) show_bar_graph grouping_var(grouping) } +({stata "kitli_compare2bm benchmark, hh_income(total_hh_income_2018) food_value(food_value) show_bar_graph grouping_var(grouping) ":{it:click to run}}) {p_end} + {title:Saved results} {pstd} diff --git a/kitli_gap2bm.ado b/kitli_gap2bm.ado index df5247f..b1eef09 100644 --- a/kitli_gap2bm.ado +++ b/kitli_gap2bm.ado @@ -30,7 +30,7 @@ To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/ ----------------------------------------------------------------------------- Last Update: -21/07/2020 +24/07/2020 *****************************************************************************/ diff --git a/kitli_gap2bm.sthlp b/kitli_gap2bm.sthlp index b08e66f..e03c767 100644 --- a/kitli_gap2bm.sthlp +++ b/kitli_gap2bm.sthlp @@ -1,6 +1,6 @@ {smcl} -{* *! version 1.2 21jul2020}{...} -{it: v1.2, 21jul2020} +{* *! version 1.3 24jul2020}{...} +{it: v1.3, 24jul2020} {title:Title} @@ -82,7 +82,9 @@ {pstd} {browse "https://docs.wixstatic.com/ugd/0c5ab3_93560a9b816d40c3a28daaa686e972a5.pdf"} -{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} 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. @@ -111,12 +113,14 @@ but excluding intrinsic value of food produced at home. {pmore} {pmore} -{opth main_income:(varname)} {varname} of total income from main source, for example main crop sales. If provided, the outputs assume there is one main income source. The calculations are done only for complete observations, i.e., if +{opth main_income:(varname)} {varname} of total income from main source, for example main crop sales. If provided, the outputs assume there is one main income source. + The calculations are done only for complete observations, i.e., if {opth main_income:(varname)} is provided, observations where {opth main_income:(varname)} is missing will be excluded from the calculations. {pmore} -{opth food_value:(varname)} {varname} of the value of food produced and consumed at home. If provided, it is added to the total income. The calculations are done only for complete observations, i.e., if {opth food_value:(varname)} is provided, +{opth food_value:(varname)} {varname} of the value of food produced and consumed at home. If provided, it is added to the total income. +The calculations are done only for complete observations, i.e., if {opth food_value:(varname)} is provided, observations where {opth food_value:(varname)} is missing will be excluded from the calculations. If provided, it will be added to the {opth hh_income:(varname)} diff --git a/stata.toc b/stata.toc index 8ae1378..42280b0 100644 --- a/stata.toc +++ b/stata.toc @@ -1,4 +1,4 @@ -v 1.2 +v 1.3 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