Update B-R documentation

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.

docs/index.html

@@ -13,26 +13,30 @@ <h1 id="top">Using Behavioral-Responses</h1>
 
 <p>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
+<a href="https://github.com/PSLmodels/Behavioral-Responses#behavioral-responses">
+documentation introduction</a>.  You always use Behavioral-Responses
+in conjunction with
 <a href="https://PSLmodels.github.io/Tax-Calculator/">
 Tax-Calculator</a>, 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
 <a href="https://PSLmodels.github.io/Tax-Calculator/cookbook.html">
-Tax-Calculator Cookbook</a>.  If you want to participate in the
+Tax-Calculator cookbook</a>.  If you want to participate in the
 development of Behavioral-Responses &mdash; by asking a question,
 reporting a bug, improving the documentation or making an enhancement
 to the Python source code &mdash; you should go to
 the <a href="https://github.com/PSLmodels/Behavioral-Responses">
 developer website</a>.</p>
 
 <p>Please cite the source of your analysis as <q>Behavioral-Responses
-release #.#.#, author's calculations.</q> 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.</p>
+release #.#.#, author's calculations.</q>  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.</p>
 
 
 <h2 id="doc">Document Contents</h2>
@@ -48,7 +52,9 @@ <h2 id="paramlogic">Response Parameters and Logic</h2>
 behavior.py</a> file, where the parameters are defined in the
 <kbd>PARAM_INFO</kbd> dictionary, and the logic of how those parameters
 are used along with Tax-Calculator results is defined in the
-<kbd>response</kbd> function.</p>
+higher-level <kbd>response</kbd> function.  The lower-level <kbd>
+quantity_response</kbd> function is self-contained and described in
+the functions's docstring.</p>
 
 <p>An interface to Behavioral-Responses for the
 <a href="https://www.ospc.org/taxbrain/">TaxBrain web application</a>
@@ -64,7 +70,7 @@ <h2 id="pyrecipe">Basic Python Recipe</h2>
 <p>A tested recipe for using the Behavioral-Responses parameters and
 <kbd>response</kbd> function is contained in recipe 2 of the
 <a href="https://PSLmodels.github.io/Tax-Calculator/cookbook.html">
-Tax-Calculator Cookbook</a> and in the <kbd>test_response_function</kbd> in the
+Tax-Calculator cookbook</a> and in the <kbd>test_response_function</kbd> in the
 <a href="https://github.com/PSLmodels/Behavioral-Responses/blob/master/behresp/tests/test_behavior.py">
 test_behavior.py</a> file.</p>
 
@@ -85,13 +91,13 @@ <h2 id="pyrecipe">Basic Python Recipe</h2>
 </pre>
 </p>
 
-<p>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 <kbd>quantity_response</kbd> function.  A recipe for
-doing this is contained in the
+<p>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 <kbd>quantity_response</kbd>
+function.  A recipe for doing this is contained in recipe 4 of the
 <a href="https://PSLmodels.github.io/Tax-Calculator/cookbook.html">
-Tax-Calculator Cookbook</a>.  That recipe simply estimates the
+Tax-Calculator cookbook</a>.  That recipe simply estimates the
 responses.  But the techniques used in the Behavioral-Responses
 <kbd>response</kbd> function can be used to apply the estimated
 responses to the post-reform Tax-Calculator object and recompute