*! version 1.4 07aug2020
v1.4, 07aug2020

Title

(KIT) Living Income Tools -- Tables, density (kernel smoothened) and bar plots about
the total household income with the goal of comparing to the benchmark value, optionally by groups.

Syntax

kitli_compare2bm
li_benchmark [if] [in], arguments

mandatory arguments

hh_income(varname) varname of total household income

optional arguments

Income composition

food_value(varname) varname of value attributable to food produced and consumed at home

Grouping

grouping_var(varname) grouping variable

Labels

label_benchmark(text) Text for benchmark name. Default "Living Income Benchmark"

label_food_value(text) Text for value of food. Default "(including the value of food)" added to the label of hh_income(varname).
Used if food_value(varname) is provided

Graph options

ytitle(text) Text for y axis. Default "Proportion of households (%)"

spacing(number) Value for spacing between the boxes of the combined graph of all groups. Defaults to 0.02

placement(text) Placement of the boxes of the indicating the share of those below the benchmark. Defaults to right.

step_size(integer) Value for step size in the x-axis. Defaults to a value calculated internally

colors(text) String with colors for the graph. Default "ebblue%30 | blue%30 | green%30 | orange%30"
if stata 15 or newer and "ebblue | blue | green | orange" otherwise

Graph exporting

show_distribution_graph shows a distribution graph comparing to the benchmark

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

show_bar_graph shows a bar graph of the share below the benchmark

save_graph_as(text) main stub of filename to be saved. Graphs will be saved as png format

Description

kitli_compare2bm produces tables, bar charts and density (kernel smoothened) plots as fractions about the distribution of
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.

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

This function includes options to customize key elements of the graphs.
Please notice, however, that all graphs can be further edited using Stata's graph_editor capabilities.

Arguments

Main

li_benchmark varname which containts the living income benchmark value per observation.

Mandatory

hh_income(varname) varname of total household income, including the main income source.

li_benchmark and hh_income(varname) need to be in the same currency and unit (e.g., USD per household).

Income composition

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 food_value(varname) is provided,
observations where
food_value(varname) is missing will be excluded from the calculations.
If provided, it will be added to the hh_income(varname)

food_value(varname) needs to be in the same currency and unit as li_benchmark (e.g., USD per household).

Grouping

grouping_var(varname) grouping variable. If specified, density charts will have one curve per group.

Labels

label_benchmark(text) Text for benchmark name. If not specified, Living Income Benchmark is shown.

label_food_value(text) Text for intrinsic value of food. If not specified, (including the value of food) is added to the label of hh_income(varname).
Only in case food_value is provided.

Graph options

ytitle(text) Text for y axis. If not specified, Proportion of households(%) is shown.

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

placement(text) Placement of the boxes/text in the graphs. Defaults to right, i.e., the boxes are placed to the right of the benchmark line.
Typically, one might want to use left as an alternative, if the text gets cut-off to the right.
See compassdirstyle for more valid options.

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

colors(text) Colors for the curves. Multiple colors need to be separated by a "|".
Default "ebblue%30 | blue%30 | green%30 | orange%30" if stata 15 or newer and
"ebblue | blue | green | orange" otherwise. Please notice that
transparency in colors ("%30") is only
available from stata version 15 onwards.

For more information see colorstyle

Graph exporting

show_distribution_graph shows a distribution graph (with groups overlayed, if provided),
comparing to the benchmark

show_detailed_graph shows detailed distribution graphs, i.e. distribution, benchmark, mean and median values
, as separated graphs per group if groups are provided.

show_bar_graph shows a bar graph with the share of those below the benchmark, per group if groups are provided.

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 distribution appended,
detailed graphs have the word detailed appended,
and bar graphs have the word bar appended.
Finally, group graphs have the group label appended to the file name.

Examples

Setup

. use https://raw.githubusercontent.com/mtyszler/KIT_LivingIncome/master/kitli_exampledata.dta
(click to run)

Distribution plots for all

. kitli_compare2bm benchmark, hh_income(total_hh_income_2018) show_distribution_graph
(click to run)

Distribution plots for all, saving

. kitli_compare2bm benchmark, hh_income(total_hh_income_2018) show_distribution_graph save_graph_as(example_density)
(click to run)

Distribution plots by groups

. kitli_compare2bm benchmark, hh_income(total_hh_income_2018) show_distribution_graph grouping_var(grouping)
(click to run)

Distribution plots by groups, with food value

. kitli_compare2bm benchmark, hh_income(total_hh_income_2018) food_value(food_value) show_distribution_graph grouping_var(grouping)
(click to run)

Detailed distribution plots, by group

. kitli_compare2bm benchmark, hh_income(total_hh_income_2018) grouping_var(grouping) show_detailed_graph
(click to run)

Detailed distribution plots, by group, with food value

. kitli_compare2bm benchmark, hh_income(total_hh_income_2018) food_value(food_value) grouping_var(grouping) show_detailed_graph
(click to run)

Bar graph by groups

. kitli_compare2bm benchmark, hh_income(total_hh_income_2018) show_bar_graph grouping_var(grouping)
(click to run)

Bar graph by groups, with food value

. kitli_compare2bm benchmark, hh_income(total_hh_income_2018) food_value(food_value) show_bar_graph grouping_var(grouping)
(click to run)

Saved results

kitli_compare2bm saves the following in r(), depending on the options provided:

Scalars

If groups are provided, the results names are appended with the group number

r(N) number of observations

r(share_below) share of those below the benchmark

Macros

r(grouping_var) variable used for groupings

Citation

kitli_compare2bm is not an official Stata command. It is a free contribution to the research community, like a paper.
Please cite it as such:

Tyszler, et al. (2020). Living Income Calculations Toolbox. KIT ROYAL TROPICAL
INSTITUTE and COSA. Available at: https://github.com/mtyszler/KIT_LivingIncome/

If you have requests or suggestions, please do so at our repository: https://github.com/mtyszler/KIT_LivingIncome/

Authors

Marcelo Tyszler (Package maintainer). KIT Royal Tropical Institute, Netherlands. m.tyszler@kit.nl

Carlos de los Rios. COSA. cd@thecosa.org

References

Github repository: https://github.com/mtyszler/KIT_LivingIncome/