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 simulation model, in Python scripts that you can run on your own computer. Note that these recipes require Tax-Calculator release 1.0.0 or higher running on Python 3.6 or Python 3.7. For other ways of using Tax-Calculator, see the user guide, which this Cookbook assumes you have read.

In order to write correct and effective Python scripts 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.

Cookbook Contents

Preliminaries

Kitchen Setup on how to setup your computer to follow these recipes

Recipe Techniques on rules to follow when modifying the recipes in this cookbook

Recipe Ingredients on how get the ingredients required for these recipes in your kitchen

Recipe Feedback on how request a new recipe be added to this cookbook or
report problems encountered when following an existing recipe

Basic Recipe

Static Analysis of a Simple Reform

Advanced Recipes

(1) Directly Comparing Two Reforms

(2) Estimating Behavioral Response to Tax Reform

(3) Creating a Custom Table

(4) Estimating Reform Response by Earnings Group

Preliminaries: Kitchen Setup

You need to setup your computer in certain ways in order to follow these recipes. First, follow these instructions on installing Anaconda and a taxcalc package on your computer. And second, install the recipes and ingredients 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 are located in the Tax-Calculator/docs/cookbook directory. If you haven't cloned the repository, you have a couple of choices. You can download the source code as a zip file by clicking on the green Clone or download button on this page. This choice has the advantage of replicating the directory structure and file names that we use in our test kitchen. To comfirm your unzipped installation is valid, execute python test_recipes.py in the Tax-Calculator/docs/cookbook directory to make sure all the recipes PASS. Or you can copy and paste the recipes and ingredients, as needed, to your local computer. If you make this second choice, you may need to edit file paths in the recipes depending on how you've organized and named the copied-and-pasted files.

Back to Cookbook Contents

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 the 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 three secondary objects (a Policy object, a Records object, and a Consumption 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, Records, and Consumption 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 scripts 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.

Back to Cookbook Contents

Preliminaries: Recipe Ingredients

All the ingredients needed for the recipes are included in the Tax-Calculator/docs/cookbook/ingredients 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.

Back to Cookbook Contents

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.

Back to Cookbook Contents

Basic Recipe: 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 ingredients/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.

Back to Cookbook Contents

Advanced 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.

Back to Cookbook Contents

Advanced Recipe: (2) Estimating Behavioral Response to Tax 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. Before following this recipe, be sure to install the behresp package on your compter by executing this at the command prompt: conda install -c PSLmodels behresp

Ingredients

Policy reform in the ingredients/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.

Back to Cookbook Contents

Advanced 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.

Back to Cookbook Contents

Advanced Recipe: (4) Estimating Reform Response by Earnings Group

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 ingredients/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.

Results

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

Back to Cookbook Contents