Add utility functions that generate a change-in-aftertax-income-by-decile graph

[martinholmer]

This pull request, which is built on pull request #1605, adds two new functions to the utils.py file: dec_graph_data and dec_graph_plot. Working together, these two functions generate a horizontal bar chart showing the percent change in after-tax expanded income induced by a tax reform for each of twelve expanded-income groups: the lower nine deciles plus the bottom half of the top decile, the next four percentiles, and the top percentile. The generated graph looks similar to the New York Times graph shown in issue #1592 except that only the total reform effect is shown (that is, there is no detail for any of the reform's component provisions). In other words, I don't get any "bonus points".

Here is example that shows what the generated graph looks like. This example analyzes a revenue-neutral reform that broadens the OASDI FICA tax base and reduces the OASDI FICA tax rate beginning in 2020.

    reform = {
        2020: {
            '_SS_Earnings_c': [9e99],  # OASDI FICA tax on all earnings
            '_FICA_ss_trt': [0.107484]  # lower 0.124 rate to keep revenue unchanged
        }
    }

The functions can be used to generate a graph without labels on the axes (like in the New York Times) or with labels on the axes (which might be useful detail for a more technical audience). The no-axis-labels code and graph are shown first, then the other version after that.

No Axis Labels

    pol = Policy()
    rec = Records.cps_constructor(data=cps_subsample)
    calc1 = Calculator(policy=pol, records=rec)
    year = 2020
    reform = {
        year: {
            '_SS_Earnings_c': [9e99],  # OASDI FICA tax on all earnings
            '_FICA_ss_trt': [0.107484]  # lower 0.124 rate to keep revenue unchanged

        }
    }
    pol.implement_reform(reform)
    calc2 = Calculator(policy=pol, records=rec)
    calc1.advance_to_year(year)
    calc2.advance_to_year(year)
    gdata = dec_graph_data(calc1, calc2)
    gplot = dec_graph_plot(gdata, xlabel=' ', ylabel=' ')
    write_graph_file(gplot, 'example1.html', 'Example1 Plot')

With Axis Labels

    pol = Policy()
    rec = Records.cps_constructor(data=cps_subsample)
    calc1 = Calculator(policy=pol, records=rec)
    year = 2020
    reform = {
        year: {
            '_SS_Earnings_c': [9e99],  # OASDI FICA tax on all earnings
            '_FICA_ss_trt': [0.107484]  # lower 0.124 rate to keep revenue unchanged

        }
    }
    pol.implement_reform(reform)
    calc2 = Calculator(policy=pol, records=rec)
    calc1.advance_to_year(year)
    calc2.advance_to_year(year)
    gdata = dec_graph_data(calc1, calc2)
    gplot = dec_graph_plot(gdata, xlabel='', ylabel='')
    write_graph_file(gplot, 'example1.html', 'Example1 Plot')

Any comments or suggestions are welcome.

After an extended review period (and possible revisions to this graph), this graph will be added to the output generated by the --graphs option of the Tax-Calculator CLI, tc, in another pull request.

[codecov-io]

Codecov Report

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

@@          Coverage Diff           @@
##           master   #1606   +/-   ##
======================================
  Coverage     100%    100%           
======================================
  Files          37      37           
  Lines        2786    2852   +66     
======================================
+ Hits         2786    2852   +66

Impacted Files	Coverage Δ
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 a2cd056...e2d724c. Read the comment docs.

[MattHJensen]

This is fantastic. Thanks @martinholmer!

What do you think about calling it "income" instead of "expanded income" and then add an optional note(s) on the bottom that defines what "income" is? Could also have an optional source label that gives tax-calculator version. I don't see either of these possible enhancements as necessary for merging this PR, though.

[martinholmer]

As part of an extensive discussion in issue #1592, @MattHJensen made an excellent suggestion about how to improve the proposed graph:

Another approach would be to include the top 10% decile and then create some subtle visual separation between the bars for the 10 deciles and the bars for 90-95, 90-99, and top 1. They could be separated by a dotted line, say, or could be a different color, or both.

Pull request #1606 has been updated to change the graph along these lines. Here is the graph (without any axis labels) for the reform described here:

Any suggestions about how to further improve the graph are welcome.

@evtedeschi3 @feenberg @Amy-Xu @andersonfrailey @hdoupe @GoFroggyRun @codykallen @hayleefay

[martinholmer]

@MattHJensen asked:

What do you think about calling it "income" instead of "expanded income" and then add an optional note(s) on the bottom that defines what "income" is? Could also have an optional source label that gives tax-calculator version. I don't see either of these possible enhancements as necessary for merging this PR, though.

The default axis labels are meant for a technical audience, so I think it is appropriate to use the term "expanded income", which clarifies what income concept is being used. However, the proposed dec_graph_plot utility function allows users to specify their own x-axis label and their own y-axis label (including having no label), so users can easily generate graphs with axis labels customized to their audience.

I don't know how to use bokeh to generate "note(s) on the bottom" or an "optional source label".

[MattHJensen]

This looks great.