flowchart.mmd


graph TD

	A["Do you have a complex sample survey design object created with either svydesign() or svrepdesign() ?"]

	A --> |No| B["Rather than convey, consider the laeken or vardpoor R libraries."]

	A --> |Yes| C["Do you want to analyze poverty, inequality, or richness/affluence?"]


	C --> D["Poverty"]

	D --> DE["I would like to estimate some summary indicators."]

	D --> DF["I would like to estimate some useful graphs."]

	DF --> DG["survey::svycdf can be a useful tool to analyze 1st order poverty dominance."]

  DE --> DH["Main poverty measures"]
  DH --> DW["svyfgt( ... , g = 0) computes the headcount poverty rate,<br>a score unaffected by being<br>$1 or $100 below the poverty line"]
	DH --> DX["svyfgt( ... , g = 1) computes the<br>average normalized poverty gap,<br>which takes into account the distance to the poverty line:<br>people $100 below the poverty line have a<br>higher poverty score than those<br>$10 below the poverty line. <br>However, there is still an ethical problem:<br>distance to the poverty line is a linear function.<br>This means that if you take money<br>from the poorest and give it to<br>the less poor (without crossing<br>the poverty line),<br>the poverty measure is still the same"]
	DH --> DY["svyfgt( ... , g = 2) computes the<br>average squared normalized poverty gap,<br>where the above regressive transfer<br>will result in an increase of the<br>poverty measure. In other words,<br>gamma=2 takes 'inequality in poverty' into account"]
	DH --> DZ["svywatts() computes a measure comparable<br>to the average squared normalized poverty gap<br>with a time-to-exit-poverty interpretation:<br>under some (unrealistic, but useful) assumptions,<br>dividing the Watts measure by an income annual growth rate R<br>yields the average number of years<br>for leaving poverty status."]

  DY --> DA["svyfgtdec( ... , g = 2) decomposes the measure into incidence, intensity and inequality in poverty. Useful to analyze the differences across domains."]
	DZ --> DB["svywattsdec() decomposes the measure into incidence, intensity and inequality in poverty. Useful to analyze the differences across domains."]


  DE --> DK["Median-based poverty threshold"]
  DK --> DQ["svyarpt() computes the threshold of a low standard<br>of living in comparison to the general living standards<br>of those in your survey dataset<br>(called the at-risk-of-poverty threshold)"]


  DE --> DI["Laeken poverty indicators"]

  DI --> DM["'How many are there overall?'<br>svyarpr() computes the share of the population<br>living below the at-risk-of-poverty threshold"]
	DI --> DN["'How do the elderly compare to everyone else?'<br>svyrmir() computes the<br>ratio of median income of<br>people above vs below a certain age"]
	DI --> DO["'How big is the gap, in terms of dollars (or other currency)?'<br>svyrmpg() computes the relative difference<br>between the median income of people below<br>the at-risk-of-poverty threshold<br>and the threshold itself"]
	DI --> DP["'How much income does the median number of this at-risk-of-poverty group have?'<br>svypoormed() computes the median income among individuals<br>living below the at-risk-of-poverty threshold"]


	C --> E["Inequality"]

	E --> EA["I would like to estimate some useful graphs."]
  EA --> EAA["svylorenz() provides a straightforward graphic of how<br>your population of interest differs from perfect equality"]

  E --> EB["I would like to estimate some summary indicators."]
  EB --> EBA["Laeken inequality indicators"]
  EBA --> EBAA["svygpg() computes the relative difference<br>of income between men and women"]
	EBA --> EBAB["svyqsr() computes the ratio of income earned<br>by the top 20% against the income of the bottom 20%"]

  EB --> EBB["Main inequality measures"]

  EBB --> EBBA["Based on the Lorenz curve"]
  EBBA --> EBBAA["svygini() computes the Gini coefficient,<br>a commonly-used value to describe<br>economic inequality that weights outliers equally."]
  EBBA --> EBBAB["svyzenga() computes the Zenga measure,<br>a measure based on a transformation of the Lorenz curve."]

  EBB --> EBBB["Based on Entropy"]
	EBBB --> EBBBA["svygei( ... , epsilon = 0 ) computes the<br>Theil-L index, a measure sensitive to<br>differences among those with lower incomes"]
	EBBB --> EBBBB["svygei( ... , epsilon = 1 ) computes the<br>Theil-T index, a measure sensitive to<br>differences among those with higher incomes"]
	EBBB --> EBBBC["svyjdiv() computes the J-divergence measure<br>of inequality, a measure not<br>overly sensitive to either tail"]

	EBBBA --> EBBBAA["svygeidec( ... , epsilon = 0 ) decomposes the<br>Theil-L index into inequality within and between groups."]
	EBBBB --> EBBBBA["svygeidec( ... , epsilon = 1 ) decomposes the<br>Theil-T index into inequality within and between groups."]
	EBBBC --> EBBBCA["svyjdivdec() decomposes the<br>J-Divergence measure into inequality within and between groups."]

  EBB --> EBBC["Based on Social Welfare Functions"]
  EBBC --> EBBCA["svyatk() computes the Atkinson index, an inequality measure directly related to the marginal utility of money.<br>This calculation expresses the idea that more money provides more welfare, but at a diminishing rate.<br>So $100 makes less difference in someone's welfare as they move up the income distribution."]


	C --> F["Richness/Affluence"]
	F --> FA["Summary measures"]

	FA --> FAA["Related to Polarization.<br>The concave, polarization-sensitive richness measures<br> increase with a progressive transfer among the rich"]
	FAA --> FAAA["svyrich( ... , type_measure = 'Cha' ) is the Chakravarty richness measure.<br> As the g parameter goes to infinity, this measure tends towards the richness headcount ratio."]
	FAA --> FAAB["svyrich( ... , type_measure = 'FGTT1' ) is the concave (for g < 1) FGT-like richness measure.<br> As the g parameter goes to 0, this measures tends towards the richness headcount ratio."]

	FA --> FAB["Related to Inequality.<br>The convex, inequality-sensitive richness measures<br> decline after a<br>progressive transfer among the rich."]
	FAB --> FABA["svyrich( ... , type_measure = 'FGTT2' ) is the convex (for g > 1) FGT-like richness measure.<br>"]

	F --> FA2["Graphical Tools"]
	FA2 --> FA2A["survey::svycdf() can be used to visualize the fraction<br> of the population above (and below) a range of richness thresholds."]