MicroDataFrame.squared_poverty_gap (microdataframe.py line 812) sums (threshold - income) ** 2 over people in poverty and returns that total. Its docstring says the result is "also known as the poverty severity index". It is not: the FGT severity index is the mean of the squared normalised gap, (1/N) Σ ((z - y) / z)^2, dimensionless and in [0, 1]. What the method returns is in currency squared.
poverty_gap and deep_poverty_gap are likewise unnormalised currency totals, not FGT(1). Only poverty_rate is an FGT index.
The test suite has no test of poverty_rate, deep_poverty_rate, poverty_gap, deep_poverty_gap or squared_poverty_gap (grep poverty microdf/tests/ finds only poverty_count).
Fix:
- Docstrings: state exactly what each returns (weighted headcount rate; weighted aggregate gap in currency units; weighted aggregate squared gap in currency squared) and drop "poverty severity index".
- Either add normalised FGT(1) and FGT(2) as
poverty_gap_index / poverty_severity_index, or state in the docs that they are out of scope.
- Tests for all five methods with hand-computed expected values on a three-row frame with non-uniform weights, including a row exactly at the threshold and a zero-weight row.
MicroDataFrame.squared_poverty_gap(microdataframe.py line 812) sums(threshold - income) ** 2over people in poverty and returns that total. Its docstring says the result is "also known as the poverty severity index". It is not: the FGT severity index is the mean of the squared normalised gap,(1/N) Σ ((z - y) / z)^2, dimensionless and in [0, 1]. What the method returns is in currency squared.poverty_gapanddeep_poverty_gapare likewise unnormalised currency totals, not FGT(1). Onlypoverty_rateis an FGT index.The test suite has no test of
poverty_rate,deep_poverty_rate,poverty_gap,deep_poverty_gaporsquared_poverty_gap(grep poverty microdf/tests/finds onlypoverty_count).Fix:
poverty_gap_index/poverty_severity_index, or state in the docs that they are out of scope.