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

Title

(KIT) Living Income Tools -- Tables and Bar charts of the Gap to the Living Income Benchmark.

Syntax

kitli_gap2bm
li_benchmark [if] [in], arguments

mandatory arguments

hh_income(varname) varname of total household income

optional arguments

Income composition

main_income(varname) varname of total income from main source, for example main crop sales

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

Metric

metric(mean) computes mean (default)

metric(median) computes medians

metric(FGT) computes the FGT index

Calculation

as_share computes share of the benchmark value instead of absolute (default). Applicable only for metric(mean) and metric(median)

Grouping

grouping_var(varname) grouping variable

Labels

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

label_currency(text) Text for currency name. Default "USD"

label_time(text) Text for time period name. Default "year"

label_hh_income(text) Text for total income Default "Total income". Used if main_income(varname) is NOT provided

label_main_income(text) Text for main income. Default "Income from main crop". Used if main_income(varname) is provided

label_other_than_main_income(text) Text for remaining income. Default "Other income". Used if main_income(varname) is provided

label_food_value(text) Text for value of food. Default "Value of crops consumed at home". Used if food_value(varname) is provided

Graph colors

color_hh_income(colorstyle) Color of total income. Default "blue%30"
(or "blue" if older than stata 15). Used if main_income(varname) is NOT provided

color_main_income(colorstyle) Color of main source of income. Default "blue%30"
(or "blue" if older than stata 15). Used if main_income(varname) is provided

color_other_than_main_income(colorstyle) Color of remaining income. Default "ebblue%30" (or "ebblue" if older than stata 15)
. Used if main_income(varname) is provided

color_food_value(colorstyle) Color of the intrinsic value of food consumed at home. Default "orange%30" (or
"orange" if older than stata 15). Used if food_value(varname) is provided

color_gap(colorstyle) Color of the gap to the living income benchmark. Default "red%30" (or "red"
if older than stata 15)

Graph exporting

show_graph shows graph comparing to the benchmark

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

Description

kitli_gap2bm produces tables and bar charts of the Gap to the Living Income Benchmark, optionally per group.

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

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.

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
but excluding intrinsic value of food produced at home.

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

Income composition

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
main_income(varname) is provided, observations
where main_income(varname) is missing will be excluded from the calculations.

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)

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

Metric

metric(mean) computes mean and compare means to the living income benchmark (default)

metric(median) computes medians and compare median values to the living income benchmark

metric(FGT) computes the FGT index.
The Foster–Greer–Thorbecke (FGT) indices focuses on those below a reference threshold, by assigning a gap value of 0 to
those above the line. It provides an indication of the depth of the poverty among the poor.
We adapt the original poverty gap metric by replacing the poverty line with the Living Income Benchmark.
It takes the mean of the income gap per household, as a share, assigning a gap of 0 to those
above the benchmark line.

Calculation

as_share computes shares of the benchmark value instead of absolute (default), i.e. all values shown are in percentage of the benchmark value and add up to 100%.

Grouping

grouping_var(varname) grouping variable. If specified, tables will be per group and bar charts will have one bar per group.

Labels

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

label_currency(text) Text for currency name. If not specified, USD is shown.

label_time(text) Text for time. If not specified, year is shown.

label_hh_income(text) Text for total household income. If not specified, Total income is shown. Only in case main_income is NOT provided

label_main_income(text) Text for main income. If not specified, Income from main crop is shown. Only in case main_income is provided

label_other_than_main_income(text) Text for remaining income. If not specified, Other income is shown. Only in case main_income is provided

label_food_value(text) Text for intrinsic value of food. If not specified, Value of crops consumed at home is shown. Only in case food_value is provided

Graph colors

For more information see colorstyle. Please notice that transparency in colors ("%30")
is only available from stata version 15 onwards. If stata version is older than 15
the default values will skip the transparency.

color_hh_income(colorstyle) Color of main source of income. Default "blue%30".

color_main_income(colorstyle) Color of main source of income. Default "blue%30".

color_other_than_main_income(colorstyle) Color of remaining income. Default "ebblue%30"

color_food_value(colorstyle) Color of the intrinsic value of food consumed at home. Default "orange%30". Only in case food_value is provided

color_gap(colorstyle) Color of the gap to the living income benchmark. Default "red%30"

Graph exporting

show_graph shows graph comparing to the benchmark

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

Examples

Setup

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

Tables by group, means

. kitli_gap2bm benchmark, hh_income (total_hh_income_2018) main_income(total_cocoa_income_2018) grouping_var(grouping)
(click to run)

Bar Chart by group, means

. kitli_gap2bm benchmark, hh_income (total_hh_income_2018) main_income(total_cocoa_income_2018) grouping_var(grouping) show_graph
(click to run)

Bar Chart by group, means, saving

. kitli_gap2bm benchmark, hh_income (total_hh_income_2018) main_income(total_cocoa_income_2018) grouping_var(grouping) show_graph save_graph_as(example_barchart)
(click to run)

Bar Chart by group, medians

. kitli_gap2bm benchmark, hh_income (total_hh_income_2018) main_income(total_cocoa_income_2018) grouping_var(grouping) show_graph metric(median)
(click to run)

Bar Chart by group, means as share

. kitli_gap2bm benchmark, hh_income (total_hh_income_2018) main_income(total_cocoa_income_2018) grouping_var(grouping) show_graph as_share
(click to run)

Bar Chart by group, FGT index

. kitli_gap2bm benchmark, hh_income (total_hh_income_2018) grouping_var(grouping) show_graph metric(FGT)
(click to run)

Bar Chart by group, means with food value

. kitli_gap2bm benchmark, hh_income (total_hh_income_2018) main_income(total_cocoa_income_2018) food_value(food_value) grouping_var(grouping) show_graph
(click to run)

Saved results

kitli_gap2bm 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(main_income) mean or median of the main income

r(other_than_main_income) mean or median of the other than main income

r(total_income) mean or median of the total income

r(food_value) mean or median of the intrinsic value of food produced and consumed at home

r(gap) mean or median of gap to the benchmark value

r(FGT) FGT index

r(benchmark) mean or median of the benchmark value

Macros

r(metric) metric calculated: mean, median of FGT

r(calculation) level or share

r(grouping_var) variable used for groupings

Citation

kitli_gap2bm 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/