Allow population (rather than filing-unit) quantiles in tables and graphs

[martinholmer]

This pull request resolves issue #2310 by adding an optional pop_quantiles argument to all the Tax-Calculator table and graph methods that allow using quantiles for distributional analysis. As @MaxGhenis pointed out in issue #2310, both CBO and TPC use quantiles that contain equal numbers of people (not equal numbers of filing units). And, if you read the cited CBO document, you will see that both CBO and TPC also adjust the incomes of filing units by the square root of the number of people in the filing unit before they sort filing units by income. Setting the new optional pop_quantiles argument to True also does this unit-size adjustment of incomes.

The new optional pop_quantiles argument always has a default value of False, so that backward compatibility is maintained. But when doing Python programming, you have the option of setting it to True.

Implementing this seemingly simple enhancement request required considerable changes in low-level logic. Most, if not all, users will not be affected by the low-level changes: a few column names in the distributional tables have been changed, and the Calculator distribution_table_dataframe method has been integrated into the Calculator distribution_tables method making it easier to generate distribution tables. If you are using the low-level create_*_tables utility functions (rather than the high-level Calculator.*_tables methods, then you should review your application's operation when upgrading to the Tax-Calculator release that contains this pull request. Also, in the course of making these changes, a (never reported) bug in the difference table was found and corrected. Previously, the values of tax_cut and tax_inc were understated by a large factor in difference tables; now they are scaled correctly to the number of filing units (or people) expressed in millions.

A number of new tests have been added to check the new table logic and all seems well. But if you notice any unexpected changes in the contents of distribution or difference tables, please raise an issue.

[codecov]

Codecov Report

Merging #2322 into master will not change coverage.
The diff coverage is 100%.

@@          Coverage Diff           @@
##           master   #2322   +/-   ##
======================================
  Coverage     100%    100%           
======================================
  Files          12      12           
  Lines        2784    2703   -81     
======================================
- Hits         2784    2703   -81

Impacted Files	Coverage Δ
taxcalc/utilsprvt.py	100% <ø> (ø)	⬆️
taxcalc/taxcalcio.py	100% <100%> (ø)	⬆️
taxcalc/calculator.py	100% <100%> (ø)	⬆️
taxcalc/utils.py	100% <100%> (ø)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 18d8867...b0c3002. Read the comment docs.