From 27596c64ce03fc51cbbf8db0182726ba94c9ed0b Mon Sep 17 00:00:00 2001 From: Martin Holmer Date: Sat, 9 Feb 2019 15:18:22 -0500 Subject: [PATCH] Update B-R documentation --- README.md | 45 +++++++++++++++++++++++++++------------------ docs/index.html | 36 +++++++++++++++++++++--------------- 2 files changed, 48 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 694b47d..365926d 100644 --- a/README.md +++ b/README.md @@ -4,26 +4,35 @@ [![Codecov](https://codecov.io/gh/PSLmodels/Behavioral-Responses/branch/master/graph/badge.svg)](https://codecov.io/gh/PSLmodels/Behavioral-Responses) -Developing Behavioral-Responses -=============================== +Behavioral-Responses +==================== -This document tells you how to begin contributing to -Behavioral-Responses by reporting a bug, improving the documentation, -or making an enhancement to the Python source code. If you only want -to **use** Behavioral-Responses, you should begin by reading the [user -documentation](https://PSLmodels.github.io/Behavioral-Responses/) -that describes how to write Python scripts that use -Behavioral-Responses on your own computer. +This document tells you how to begin using or contributing to +Behavioral-Responses. Begin by reading the [Tax-Calculator user +guide](https://PSLmodels.github.io/Tax-Calculator/) and then the +[Behavioral-Responses user +guide](https://PSLmodels.github.io/Behavioral-Responses/) that +describes how to write Python scripts that use Behavioral-Responses +together with Tax-Calculator on your own computer. What is Behavioral-Responses? ----------------------------- -Behavioral-Responses, which is part of the Policy Simulation Library (PSL) -collection of USA tax models, estimates partial-equilibrium behavioral -responses to changes in the US federal individual income and payroll -tax system as simulated by -[Tax-Calculator](https://github.com/PSLmodels/Tax-Calculator) +Behavioral-Responses, which is part of the Policy Simulation Library +(PSL) collection of USA tax models, estimates partial-equilibrium +behavioral responses to changes in the US federal individual income +and payroll tax system as simulated by +[Tax-Calculator](https://github.com/PSLmodels/Tax-Calculator). It +provides two ways of doing this: (1) the `response` function, which +contains higher-level logic that supports the TaxBrain "Partial +Equilibrium Simulation" capability and requires specification of only +the elasticities, and (2) the `quantity_response` function, which +contains lower-level logic that requires specification of the quantity +whose response is to be estimated, requires specification of the +marginal tax rates and elasticities to be used in the response +calculation, and allows the response estimation to be conducted by +subgroup with different elasticities for each subgroup. Disclaimer @@ -49,11 +58,11 @@ If you want to **request an enhancement**, create a new issue providing details on what you think should be added to Behavioral-Responses. If you want to **propose code changes**, follow the directions in the -[Tax-Calculator Contributor -Guide](https://taxcalc.readthedocs.io/en/latest/contributor_guide.html) +[Tax-Calculator contributor +guide](https://github.com/PSLmodels/Tax-Calculator/blob/master/CONTRIBUTING.md#tax-calculator-contributor-guide) on how to fork and clone the Behavioral-Responses git repository. Before developing any code changes be sure to read completely the -Tax-Calculator Contributor Guide and then read about the +Tax-Calculator contributor guide and then read about the [Tax-Calculator pull-request workflow](https://github.com/PSLmodels/Tax-Calculator/blob/master/WORKFLOW.md#tax-calculator-pull-request-workflow). When reading both documents, be sure to mentally substitute @@ -73,6 +82,6 @@ release #.#.#, author's calculations." If you wish to link to Behavioral-Responses, https://PSLmodels.github.io/Behavioral-Responses/ is preferred. Additionally, we strongly recommend that you describe the -elasticity assumptions used, and provide a link to the materials +elasticity parameters used, and provide a link to the materials required to replicate your analysis or, at least, note that those materials are available upon request. diff --git a/docs/index.html b/docs/index.html index b34a0bc..466dcd2 100644 --- a/docs/index.html +++ b/docs/index.html @@ -13,14 +13,17 @@

Using Behavioral-Responses

This document tells you how to use Behavioral-Responses, an open-source model in the Policy Simulation Library (PSL) collection of -USA tax models. You always use Behavioral-Responses in conjunction with +USA tax models. It assumes that you have already read the + +documentation introduction. You always use Behavioral-Responses +in conjunction with Tax-Calculator, the static-analysis model in the PSL collection of USA tax models, by writing and executing a Python script. For an introduction to writing Python scripts using Tax-Calculator, read the tested recipes in our -Tax-Calculator Cookbook. If you want to participate in the +Tax-Calculator cookbook. If you want to participate in the development of Behavioral-Responses — by asking a question, reporting a bug, improving the documentation or making an enhancement to the Python source code — you should go to @@ -28,11 +31,12 @@

Using Behavioral-Responses

developer website.

Please cite the source of your analysis as Behavioral-Responses -release #.#.#, author's calculations. If you wish to link to -Behavioral-Responses, this page is preferred. Additionally, we strongly -recommend that you describe the input data used, and provide a link to -the materials required to replicate your analysis or, at least, note -that those materials are available upon request.

+release #.#.#, author's calculations. If you wish to link to +Behavioral-Responses, this page is preferred. Additionally, we +strongly recommend that you describe the elasticity parameters used, +and provide a link to the materials required to replicate your +analysis or, at least, note that those materials are available upon +request.

Document Contents

@@ -48,7 +52,9 @@

Response Parameters and Logic

behavior.py file, where the parameters are defined in the PARAM_INFO dictionary, and the logic of how those parameters are used along with Tax-Calculator results is defined in the -response function.

+higher-level response function. The lower-level +quantity_response function is self-contained and described in +the functions's docstring.

An interface to Behavioral-Responses for the TaxBrain web application @@ -64,7 +70,7 @@

Basic Python Recipe

A tested recipe for using the Behavioral-Responses parameters and response function is contained in recipe 2 of the -Tax-Calculator Cookbook and in the test_response_function in the +Tax-Calculator cookbook and in the test_response_function in the test_behavior.py file.

@@ -85,13 +91,13 @@

Basic Python Recipe

-

The Behavioral-Responses logic assumes that the parameters apply to -all filing units. If you want to estimate responses where the value -of the parameters vary across (say, earnings) groups, you can use the -Tax-Calculator quantity_response function. A recipe for -doing this is contained in the +

The Behavioral-Responses logic assumes that the elasticity +parameters apply to all filing units. If you want to estimate +responses where the value of the elasticity parameters vary across +(say, earnings) groups, you can use the quantity_response +function. A recipe for doing this is contained in recipe 4 of the -Tax-Calculator Cookbook. That recipe simply estimates the +Tax-Calculator cookbook. That recipe simply estimates the responses. But the techniques used in the Behavioral-Responses response function can be used to apply the estimated responses to the post-reform Tax-Calculator object and recompute