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