Cookbook of Tested Recipes for Python Programming with Tax-Calculator

This document tells you how to use Tax-Calculator, an open-source federal income and payroll tax microsimulation model, in Python programs that you can run on your own computer. It assumes that you are already familiar with the material covered in the introductory documentation (including the user guide) and that you are using the latest release of Tax-Calculator mentioned there. Some of the recipes in this cookbook also use the latest release of the Behavioral-Responses behresp package, which is documented here.

In order to write correct and effective Python programs you need to be familiar with the structure of the Tax-Calculator Python source code, an introduction to which is available in the code documentation. This Cookbook assumes you have read this code documentation.

Table of Contents

Preliminaries: Kitchen Setup

You need to setup your computer in certain ways in order to follow these recipes.

First, make sure you have the latest release of Tax-Calculator installed and in working order by following these instructions. Also, install the Behavioral-Responses package as described here. /p>

Second, install the recipes, ingredients, and expected results in this cookbook on your computer. There are several ways to do this. If you have cloned the Tax-Calculator repository (see the contributor guide), then the recipes, ingredients, and expected results, are already located in the Tax-Calculator/docs/cookbook directory. If you haven't cloned the Tax-Calculator repository, your best option, by far, is to download all the source code as a zip file by clicking on the green Clone or download button on this web page. Your browser will download a file named Tax-Calculator-master.zip, which you can unzip anywhere on your local disk drive. Then change directories so that you are in the Tax-Calculator-master/docs/cookbook directory in the unzipped directory tree.

Once in the Tax-Calculator[-master]/docs/cookbook directory, confirm that your cookbook installation is valid by executing the python test_recipes.py command and observing that all the recipes PASS. Regardless of which method you use, be sure to upgrade periodically because the packages, recipes, and expected results, will change over time.

Preliminaries: Recipe Techniques

As with any cookbook, the best approach is to follow a recipe exactly the first time and then, if needed, modify the recipe to get exactly the dish you want. Remember to copy a recipe file and give it a new file name before you start to modify the recipe.

The Calculator object is the central object in Tax-Calculator and it is created by passing at least two secondary objects (a Policy object and a Records object) to the Calculator class constructor. When modifying a recipe, following a few rules will minimize the chance of running into problems.

Fully specify Policy and Records objects before passing them to the Calculator class constructor.

After initializing a Calculator object, manipulate it using only Calculator class methods.

Following these two rules means avoiding the manipulation of a Calculator object's private internal objects. You should definitely avoid trying to change those internal Calculator objects. And if you find yourself wanting to read those internal objects, look for a way to do that using public Calculator methods. If no Calculator methods allow you to get out of the Calculator object the information you need, create a new issue asking for a Tax-Calculator enhancement.

The recipes in this cookbook are Python programs that can be executed from the command line like this:

    python recipe00.py > recipe00.out
    diff recipe00.out recipe00.res
  
Your kitchen setup and ability to follow a recipe and produce the same dish as we produce in our test kitchen would be validated if the above diff command yields no differences. Of course, you can substitute your favorite graphical diff program for diff to get an easier to read set of differences.

Some people like to use Tax-Calculator inside an interactive notebook. You should be able to load a recipe into an empty notebook and execute it there. If you want to work that way, the recipes may require some modification to show results interactively. But if you are a notebook user, you will know how to make a recipe work in a notebook.

After writing an HTML graph file to disk, you can view it in your favorite browser. The easiest way to do that varies by operating system.

Preliminaries: Recipe Ingredients

All the ingredients needed for the recipes are included in the Tax-Calculator/docs/cookbook directory. If you organize the recipes and ingredients in a different way than they are organized in our test kitchen, you will need to change the file path for each ingredient in each recipe.

Just like with recipe modification, copy and rename an ingredient file before you make modifications to it.

Preliminaries: Recipe Feedback

If you want to request a recipe that makes a new dish, create a new issue here providing details on what you want to make and why the existing recipes cannot be easily modified to make what you want.

Also, please report, in the same way, any problems you experience following an existing recipe.

Recipe 0: Static Analysis of a Simple Reform

This is the recipe you should follow first. Mastering this recipe is a prerequisite for all the other recipes in this cookbook.

Ingredients

Policy reform in the reformA.json file.

Instructions

Step-by-step instructions in the recipe00.py file.

Results

Expected text results from executing python recipe00.py > recipe00.out at the command prompt as shown above.

Expected graph (located in the same directory as recipe00.py and named recipe00.graph.html) from executing python recipe00.py > recipe00.out at the command prompt as shown above. To view the HTML graph file generated when you follow the recipe, open it in your favorite browser. For example, on a Mac, you would enter at the command prompt
open recipe00.graph.html
to start your default browser showing the graph.

Recipe 1: Directly Comparing Two Reforms

This is an advanced recipe that should be followed only after mastering the basic recipe. This recipe shows how to compare two reforms (instead of comparing a reform to current-law policy) and also shows how to use the reform files available on the Tax-Calculator website (instead of reform files on your computer's disk).

Ingredients

No ingredients required because we read reform files from the Tax-Calculator website.

Instructions

Step-by-step instructions in the recipe01.py file.

Results

Expected text results from executing python recipe01.py > recipe01.out at the command prompt as illustrated above.

Recipe 2: Estimating Behavioral Response to Reform

This is an advanced recipe that should be followed only after mastering the basic recipe. This recipe shows how to analyze the behavioral responses to a tax reform using the Behavioral-Responses behresp package.

Ingredients

Policy reform in the reformA.json file.

Instructions

Step-by-step instructions in the recipe02.py file.

Results

Expected text results from executing python recipe02.py > recipe02.out at the command prompt as illustrated above.

Recipe 3: Creating a Custom Table

This is an advanced recipe that should be followed only after mastering the basic recipe. This recipe shows how to prepare a custom table.

Ingredients

No ingredients required because we conduct analysis under current-law policy.

Instructions

Step-by-step instructions in the recipe03.py file.

Results

Expected text results from executing python recipe03.py > recipe03.out at the command prompt as illustrated above.

Recipe 4: Estimating Differential Reform Response

This is an advanced recipe that should be followed only after mastering the basic recipe. This recipe shows how to estimate the reform response in charitable giving when the response elasticities vary by earnings group. It employs the groupby technique used in the Creating a Custom Table recipe, so you might want to read that recipe first.

Ingredients

Policy reform in the reformA.json file. Note that this reform increases the personal exemption amount (from zero where it is under current-law policy) and decreases the standard deduction amounts (so they are approximately where they were before the TCJA reform that is now current-law policy).

Instructions

Step-by-step instructions in the recipe04.py file.

pandas-style approach in the recipe04_pandas.py file.

Results

Expected text results from executing python recipe04.py > recipe04.out at the command prompt as illustrated above.

Similar results from executing python recipe04_pandas.py > recipe04.out

Recipe 5: Redefining Expanded Income

This is an advanced recipe that should be followed only after mastering the basic recipe. This recipe is almost exactly the same as Directly Comparing Two Reforms, so you might want to read that recipe first.

This recipe introduces a powerful technique for customizing the operation of Tax-Calculator. This calculator-customization technique is used in this recipe to redefine expanded income in a way that allows the redefined income measure to be used seamlessly with all the other (table and graph) methods of the Calculator class. The basic idea behind the calculator-customization technique is to derive a customized Calculator class from the Tax-Calculator Calculator class. This is a standard object-oriented programming technique.

Ingredients

No ingredients required because we read reform files from the Tax-Calculator website.

Instructions

Step-by-step instructions in the recipe05.py file.

Results

Expected text results from executing python recipe05.py > recipe05.out at the command prompt as illustrated above.

Recipe 6: Analyzing a Non-Parametric Reform

This is an advanced recipe that should be followed only after mastering the basic recipe. This recipe shows how to customize the Calculator class so that it can analyze a tax reform that cannot be characterized using existing policy parameters (in this case a pseudo Cost-of-Living Refund reform). It uses, in a more extensive way, the object-oriented programming inheritance technique introduced in Redefining Expanded Income, so you might want to read that recipe first.

Ingredients

Policy reform in the reformC.json file eliminates the EITC beginning in 2020.

Instructions

Step-by-step instructions in the recipe06.py file.

Results

Expected text results from executing python recipe06.py > recipe06.out at the command prompt as illustrated above.