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

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. 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 Tax-Calculator-master/docs/cookbook 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.

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