Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
433 lines (334 sloc) 15.5 KB
<!DOCTYPE html>
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<link href="docs.css" rel="stylesheet">
<title>T-C Python Cookbook</title>
</head>
<body>
<h1>Cookbook of Tested Recipes for Python Programming with Tax-Calculator</h1>
<p>
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
<a href="https://pslmodels.github.io/Tax-Calculator/"
target="_blank">introductory documentation</a> (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
<kbd>behresp</kbd> package, which is documented
<a href="https://pslmodels.github.io/Behavioral-Responses/"
target="_blank">here</a>.
</p>
<p>
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
<a href="https://PSLmodels.github.io/Tax-Calculator/tc_overview.html"
target="_blank">code documentation</a>. This Cookbook assumes
you have read this code documentation.
</p>
<h3>Table of Contents</h3>
<ul style="list-style-type:none;">
<li><b>Preliminaries</b></li>
<ol style="list-style-type:none;">
<li><a href="#prelim-setup">Kitchen Setup</a></li>
<li><a href="#prelim-techniques">Recipe Techniques</a></li>
<li><a href="#prelim-ingredients">Recipe Ingredients</a></li>
<li><a href="#prelim-feedback">Recipe Feedback</a></li>
</ol>
<li><b>Recipes</b></li>
<ol style="list-style-type:none;">
<li><a href="#recipe00">0. Static Analysis of a Simple Reform</a></li>
<li><a href="#recipe01">1. Directly Comparing Two Reforms</a></li>
<li><a href="#recipe02">2. Estimating Behavioral Response to Reform</a></li>
<li><a href="#recipe03">3. Creating a Custom Table</a></li>
<li><a href="#recipe04">4. Estimating Differential Reform Response</a></li>
<li><a href="#recipe05">5. Redefining Expanded Income</a></li>
<li><a href="#recipe06">6. Analyzing a Non-Parametric Reform</a></li>
</ol>
</ul>
<h3 id="prelim-setup">Preliminaries: Kitchen Setup</h3>
<p>
You need to setup your computer in certain ways in order to follow
these recipes.
</p>
<p>
<b>First</b>, make sure you have the latest release of
Tax-Calculator installed and in working order by following
<a href="https://PSLmodels.github.io/Tax-Calculator/uguide.html#cli-install-test"
target="_blank">these instructions</a>.
Also, install the Behavioral-Responses package as described
<a href="https://PSLmodels.github.io/Behavioral-Responses/"
target="_blank">here</a>.
/p>
<p>
<b>Second</b>, 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
<a href="https://github.com/PSLmodels/Tax-Calculator/blob/master/CONTRIBUTING.md#tax-calculator-contributor-guide"
target="_blank">contributor guide</a>), then the recipes,
ingredients, and expected results, are already located in
the <kbd>Tax-Calculator/docs/cookbook</kbd> 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 <q>Clone or download</q> button on
<a href="https://github.com/PSLmodels/Tax-Calculator"
target="_blank">this web page</a>. Your browser will download a
file named <kbd>Tax-Calculator-master.zip</kbd>, which you can
unzip anywhere on your local disk drive. Then change directories
so that you are in the <kbd>Tax-Calculator-master/docs/cookbook</kbd>
directory in the unzipped directory tree.
</p>
<p>
Once in the <kbd>Tax-Calculator[-master]/docs/cookbook</kbd>
directory, confirm that your cookbook installation is valid by
executing the <kbd>python test_recipes.py</kbd> command and
observing that all the recipes <kbd>PASS</kbd>. Regardless of which
method you use, be sure to upgrade periodically because the
packages, recipes, and expected results, will change over time.
</p>
<h3 id="prelim-techniques">Preliminaries: Recipe Techniques</h3>
<p>
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 <q>dish</q> you want. Remember to copy a recipe file and
give it a new file name before you start to modify the recipe.
</p>
<p>
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.
</p>
<p>
Fully specify Policy and Records objects before passing them to the
Calculator class constructor.
</p>
<p>
After initializing a Calculator object, manipulate it using only
Calculator class methods.
</p>
<p>
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,
<a href="https://github.com/PSLmodels/Tax-Calculator/issues"
target="_blank">create a new issue</a> asking for a
Tax-Calculator enhancement.
</p>
<p id="execution">
The recipes in this cookbook are Python programs that can be
executed from the command line like this:
<pre>
python recipe00.py > recipe00.out
diff recipe00.out recipe00.res
</pre>
Your kitchen setup and ability to follow a recipe and produce the same
<q>dish</q> as we produce in our test kitchen would be validated if
the above <kbd>diff</kbd> command yields no differences. Of course,
you can substitute your favorite graphical diff program
for <kbd>diff</kbd> to get an easier to read set of differences.
</p>
<p>
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.
</p>
<p>
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.
</p>
<h3 id="prelim-ingredients">Preliminaries: Recipe Ingredients</h3>
<p>
All the ingredients needed for the recipes are included in
the <kbd>Tax-Calculator/docs/cookbook</kbd> 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.
</p>
<p>
Just like with recipe modification, copy and rename an ingredient
file before you make modifications to it.
</p>
<h3 id="prelim-feedback">Preliminaries: Recipe Feedback</h3>
<p>
If you want to request a recipe that makes a new <q>dish</q>,
create a new issue
<a href="https://github.com/PSLmodels/Tax-Calculator/issues">here</a>
providing details on what you want to make and why the existing recipes
cannot be easily modified to make what you want.
</p>
<p>
Also, please report, in the same way, any problems you experience
following an existing recipe.
</p>
<h3 id="recipe00">Recipe 0: Static Analysis of a Simple Reform</h3>
<p>
This is the recipe you should follow first. Mastering this recipe
is a prerequisite for all the other recipes in this cookbook.
</p>
<p><b>Ingredients</b></p>
<p><a href="reformA_json.html" target="_blank">Policy reform</a> in
the <kbd>reformA.json</kbd> file.</p>
<p><b>Instructions</b></p>
<p><a href="recipe00_py.html" target="_blank">Step-by-step
instructions</a> in the <kbd>recipe00.py</kbd> file.</p>
<p><b>Results</b></p>
<p><a href="recipe00_res.html" target="_blank">Expected text
results</a> from executing <kbd>python recipe00.py > recipe00.out</kbd> at
the command prompt as shown <a href="#execution">above</a>.</p>
<p><a href="recipe00_graph.html" target="_blank">Expected graph</a> (located
in the same directory as <kbd>recipe00.py</kbd> and named
<kbd>recipe00.graph.html</kbd>) from executing
<kbd>python recipe00.py > recipe00.out</kbd> at the command prompt as
shown <a href="#execution">above</a>. 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<br />
<kbd>open recipe00.graph.html</kbd><br />
to start your default browser showing the graph.
</p>
<h3 id="recipe01">Recipe 1: Directly Comparing Two Reforms</h3>
<p>
This is an advanced recipe that should be followed only after
mastering the <a href="#recipe00">basic recipe</a>. 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).
</p>
<p><b>Ingredients</b></p>
<p>No ingredients required because we read reform files from the
Tax-Calculator website.</p>
<p><b>Instructions</b></p>
<p><a href="recipe01_py.html" target="_blank">Step-by-step
instructions</a> in the <kbd>recipe01.py</kbd> file.</p>
<p><b>Results</b></p>
<p><a href="recipe01_res.html" target="_blank">Expected text
results</a> from executing <kbd>python recipe01.py > recipe01.out</kbd> at
the command prompt as illustrated <a href="#execution">above</a>.</p>
<h3 id="recipe02">Recipe 2: Estimating Behavioral Response to Reform</h3>
<p>
This is an advanced recipe that should be followed only after
mastering the <a href="#recipe00">basic recipe</a>. This recipe
shows how to analyze the behavioral responses to a tax reform using
the Behavioral-Responses <kbd>behresp</kbd> package.</p>
<p><b>Ingredients</b></p>
<p><a href="reformA_json.html" target="_blank">Policy reform</a> in
the <kbd>reformA.json</kbd> file.</p>
<p><b>Instructions</b></p>
<p><a href="recipe02_py.html" target="_blank">Step-by-step
instructions</a> in the <kbd>recipe02.py</kbd> file.</p>
<p><b>Results</b></p>
<p><a href="recipe02_res.html" target="_blank">Expected text
results</a> from executing <kbd>python recipe02.py > recipe02.out</kbd> at
the command prompt as illustrated <a href="#execution">above</a>.</p>
<h3 id="recipe03">Recipe 3: Creating a Custom Table</h3>
<p>
This is an advanced recipe that should be followed only after
mastering the <a href="#recipe00">basic recipe</a>. This recipe
shows how to prepare a custom table.
</p>
<p><b>Ingredients</b></p>
<p>No ingredients required because we conduct analysis under
current-law policy.</p>
<p><b>Instructions</b></p>
<p><a href="recipe03_py.html" target="_blank">Step-by-step
instructions</a> in the <kbd>recipe03.py</kbd> file.</p>
<p><b>Results</b></p>
<p><a href="recipe03_res.html" target="_blank">Expected text
results</a> from executing <kbd>python recipe03.py > recipe03.out</kbd> at
the command prompt as illustrated <a href="#execution">above</a>.</p>
<h3 id="recipe04">Recipe 4: Estimating Differential Reform Response</h3>
<p>
This is an advanced recipe that should be followed only after
mastering the <a href="#recipe00">basic recipe</a>. 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
<a href="#recipe03">Creating a Custom Table</a> recipe, so you might
want to read that recipe first.
</p>
<p><b>Ingredients</b></p>
<p><a href="reformB_json.html" target="_blank">Policy reform</a> in
the <kbd>reformA.json</kbd> 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).</p>
<p><b>Instructions</b></p>
<p><a href="recipe04_py.html" target="_blank">Step-by-step
instructions</a> in the <kbd>recipe04.py</kbd> file.</p>
<p><b>Results</b></p>
<p><a href="recipe04_res.html" target="_blank">Expected text
results</a> from executing <kbd>python recipe04.py > recipe04.out</kbd> at
the command prompt as illustrated <a href="#execution">above</a>.</p>
<h3 id="recipe05">Recipe 5: Redefining Expanded Income</h3>
<p>
This is an advanced recipe that should be followed only after
mastering the <a href="#recipe00">basic recipe</a>. This recipe is
almost exactly the same as
<a href="#recipe01">Directly Comparing Two Reforms</a>, so you might
want to read that recipe first.
</p>
<p>
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
<a href="https://pslmodels.github.io/Tax-Calculator/tc_overview.html"
target="_blank">object-oriented programming</a> technique.
</p>
<p><b>Ingredients</b></p>
<p>No ingredients required because we read reform files from the
Tax-Calculator website.</p>
<p><b>Instructions</b></p>
<p><a href="recipe05_py.html" target="_blank">Step-by-step
instructions</a> in the <kbd>recipe05.py</kbd> file.</p>
<p><b>Results</b></p>
<p><a href="recipe05_res.html" target="_blank">Expected text
results</a> from executing <kbd>python recipe05.py > recipe05.out</kbd> at
the command prompt as illustrated <a href="#execution">above</a>.</p>
<h3 id="recipe06">Recipe 6: Analyzing a Non-Parametric Reform</h3>
<p>
This is an advanced recipe that should be followed only after
mastering the <a href="#recipe00">basic recipe</a>. 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
<a href="#recipe05">Redefining Expanded Income</a>, so you might
want to read that recipe first.
</p>
<p><b>Ingredients</b></p>
<p><a href="reformC_json.html" target="_blank">Policy reform</a> in the
<kbd>reformC.json</kbd> file eliminates the EITC beginning in 2020.</p>
<p><b>Instructions</b></p>
<p><a href="recipe06_py.html" target="_blank">Step-by-step
instructions</a> in the <kbd>recipe06.py</kbd> file.</p>
<p><b>Results</b></p>
<p><a href="recipe06_res.html" target="_blank">Expected text
results</a> from executing <kbd>python recipe06.py > recipe06.out</kbd> at
the command prompt as illustrated <a href="#execution">above</a>.</p>
<button onclick="topFunction()" id="topbutton" title="Go to top">Top</button>
<script src="docs.js"></script>
<br /><br />
</body>
</html>
You can’t perform that action at this time.