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.
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
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
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
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.resYour kitchen setup and ability to follow a recipe and produce the same
dishas 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.
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.
If you want to request a recipe that makes a new
create a new issue
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.
This is the recipe you should follow first. Mastering this recipe is a prerequisite for all the other recipes in this cookbook.
Policy reform in the ingredients/reformA.json file.
Step-by-step instructions in the recipe00.py file.
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
to start your default browser showing the graph.
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).
No ingredients required because we read reform files from the Tax-Calculator website.
Step-by-step instructions in the recipe01.py file.
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
Policy reform in the ingredients/reformA.json file.
Step-by-step instructions in the recipe02.py file.
This is an advanced recipe that should be followed only after mastering the basic recipe. This recipe shows how to prepare a custom table.
No ingredients required because we conduct analysis under current-law policy.
Step-by-step instructions in the recipe03.py file.
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.
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).
Step-by-step instructions in the recipe04.py file.