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 assume that you have installed the taxcalc package for Tax-Calculator release 2.0.0 or higher and the behresp package for Behavioral-Responses release 0.7.0 or higher, and that you are 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. Also, install the behresp package by executing this command: conda install -c PSLmodels behresp. If you already have these pacakges installed do conda update -c PSLmodels taxcalc and conda update -c PSLmodels behresp to ensure you have the most recent releases.
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 repository, your best option, by far, is to
download all the Tax-Calculator 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
directory in the unzipped directory tree.
Once in that 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.
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 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 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 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 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.