Add CLI --behavior option

Makefile

@@ -24,6 +24,8 @@ help:
 	@echo "             pycodestyle (nee pep8) and pylint tools"
 	@echo "idtest     : generate report for and cleanup after executing"
 	@echo "             taxcalc/cli/input_data_tests/tests.sh"
+	@echo "brtest     : generate report for and cleanup after executing"
+	@echo "             taxcalc/cli/behavioral_responses_tests/tests.sh"
 	@echo "coverage   : generate test coverage report"
 	@echo "git-sync   : synchronize local, origin, and upstream Git repos"
 	@echo "git-pr N=n : create local pr-n branch containing upstream PR"
@@ -51,13 +53,13 @@ endef
 .PHONY=pytest
 pytest: clean
 	@$(pytest-setup)
-	@cd taxcalc ; pytest -n4 --disable-warnings --durations=0 --durations-min=2 -m "not requires_puf and not requires_tmd"
+	@cd taxcalc ; pytest -n4 --disable-warnings --durations=0 --durations-min=4 -m "not requires_puf and not requires_tmd"
 	@$(pytest-cleanup)
 
 .PHONY=pytest
 pytest-all: clean
 	@$(pytest-setup)
-	@cd taxcalc ; pytest -n4 --disable-warnings --durations=0 --durations-min=2 -m ""
+	@cd taxcalc ; pytest -n4 --disable-warnings --durations=0 --durations-min=4 -m ""
 	@$(pytest-cleanup)
 
 define tctest-cleanup
@@ -96,6 +98,11 @@ idtest: package
 	@echo "Executing taxcalc/cli/input_data_tests"
 	@cd taxcalc/cli/input_data_tests ; ./tests.sh
 
+.PHONY=brtest
+brtest: package
+	@echo "Executing taxcalc/cli/behavioral_responses_tests"
+	@cd taxcalc/cli/behavioral_responses_tests ; ./tests.sh
+
 define coverage-cleanup
 rm -f .coverage htmlcov/*
 endef

README.md

@@ -8,8 +8,8 @@
 Tax-Calculator
 ==============
 
-Tax-Calculator is an open-source microsimulation model for static
-analysis of USA federal income and payroll taxes.
+Tax-Calculator is an open-source microsimulation model for analysis of
+USA federal income and payroll taxes.
 
 We are seeking contributors and maintainers.  If you are interested in
 joining the project as a contributor or maintainer, open a new

docs/_toc.yml

@@ -14,6 +14,7 @@ parts:
     - file: guide/input_vars
     - file: guide/output_vars
     - file: guide/assumption_params
+    - file: guide/behavior_params
   - file: recipes/index
     sections:
     - file: recipes/recipe00
@@ -24,7 +25,6 @@ parts:
     - file: recipes/recipe04_pandas
     - file: recipes/recipe05
     - file: recipes/recipe06
-  - file: usage/tcja_after_2025
 - caption: About
   chapters:
   - file: about/history

docs/contributing/RELEASING.md

@@ -7,29 +7,18 @@ In the top-level Tax-Calculator directory, do the following:
 
 ```
 --> run `git switch master`  [to get on master branch]
-
 --> run `./gitsync`  [to ensure master is up-to-date with GitHub version]
-
 --> run `make clean`  [to remove any local taxcalc package]
-
 --> run `git checkout -b X-Y-Z`  [to create X-Y-Z (e.g., `4-4-1`) branch]
-
 --> on branch X-Y-Z, edit docs/about/releases.md to finalize X.Y.Z info
-
 --> specify release X.Y.Z in setup.py, taxcalc/__init__.py, docs/index.md
-
---> run `python update_pcl.py`  [to update policy_current_law.json if needed]
-
+--> run `python update_pcl.py`  [to update policy_current_law.json]
 --> run `make cstest`  [to confirm project coding style is being followed]
-
 --> run `make pytest-all`  [to confirm all pytest test are passing]
-
 --> run `make idtest`  [to check CLI results for CPS, PUF, TMD input data]
-
---> run `make tctest-jit`  [to make sure JIT decorators are not hiding bugs]
-
+--> run `make brtest`  [to check CLI results for behavioral responses]
+--> run `make tctest-jit`  [to ensure JIT decorators are not hiding bugs]
 --> commit X-Y-Z branch and push to origin
-
 --> open new GitHub pull request using your X-Y-Z branch
 ```
 

docs/guide/behavior_params.md

@@ -0,0 +1,16 @@
+Behavior parameters
+===================
+
+Note that logic that uses assumed behavior parameters to compute
+changes in input variables caused by a tax reform in a
+partial-equilibrium setting is not part of Tax-Calculator.  The
+[`response`
+function](https://github.com/PSLmodels/Behavioral-Responses/blob/232abc1e6b9f0a2b2f224ad887af3c19019d28d3/behresp/behavior.py#L13-L50)
+in the PSLmodels Behavioral-Responses `behresp` package contains that
+logic.
+
+By default Tax-Calculator assumes no behavioral responses to a tax
+reform, which is the same as saying the behavior parameters (or
+elasticities) are assumed to be zero by default.  The elasticities can
+be set to non-zero values in a JSON file that is formatted like
+[this](https://github.com/PSLmodels/Tax-Calculator/blob/master/taxcalc/behavior/behavior_response_template.json)).

docs/guide/cli.md

@@ -59,7 +59,7 @@ page](https://github.com/PSLmodels/Tax-Calculator/blob/master/taxcalc/reforms/RE
 ## Specify analysis assumptions
 
 This part explains how to specify economic assumption files used in
-static tax analysis. This is an advanced topic, so if you want to
+tax analysis. This is an advanced topic, so if you want to
 start out using the default assumptions (which are documented in [this
 section](https://taxcalc.pslmodels.org/guide/policy_params.html#policy-parameters))
 of the guide), you can skip this part now and come back to read it
@@ -77,6 +77,12 @@ For examples of assumption files and the general rules for writing
 JSON assumption files, go to [this
 page](https://github.com/PSLmodels/Tax-Calculator/blob/master/taxcalc/assumptions/README.md#economic-assumption-files).
 
+## Specify behavioral responses
+
+For a JSON file template that can be used to specify you own values of
+each response elasticity, go to [this
+page](https://github.com/PSLmodels/Tax-Calculator/blob/master/taxcalc/behavior/README.md).
+
 ## Specify filing units
 
 The `taxcalc` package containing `tc` does not include an
@@ -226,13 +232,13 @@ on an old Mac with a slow Intel CPU chip.
 ```
 % tc cps.csv 2020 --dumpdb
 Read input data for 2014; input data were extrapolated to 2020
-Write dump output to sqlite3 database file cps-20-#-#-#.db
-Execution time is 33.2 seconds
+Write dump output to sqlite3 database file cps-20-#-#-#-#.db
+Execution time is 9.6 seconds
 ```
 
 The dump database contains 2020 income tax liabilities for each filing
 unit under both baseline and reform policy regimes.  The name of the
-dump database file is `cps-20-#-#-#.db`.  Because we did not use the
+dump database file is `cps-20-#-#-#-#.db`.  Because we did not use the
 `--dumpvars` option, a minimal set of baseline/reform variables are
 included in the dump database.  
 
@@ -254,7 +260,7 @@ Anaconda Python distribution.  Full `sqlite3` documentation is
 Here is a quick way to see the structure of the dump database:
 
 ```
-% echo ".schema" | sqlite3 cps-20-#-#-#.db
+% echo ".schema" | sqlite3 cps-20-#-#-#-#.db
 CREATE TABLE IF NOT EXISTS "base" (
 "RECID" INTEGER,
   "s006" REAL,
@@ -312,21 +318,20 @@ should replace `cat` with `type`):
 ```
 % tc cps.csv 2024 --reform ref3.json --params --tables --graphs
 Read input data for 2014; input data were extrapolated to 2024
-Write baseline policy parameter values to file cps-24-#-ref3-#-params.bas
-Write reform policy parameter values to file cps-24-#-ref3-#-params.ref
-Write tabular output to file cps-24-#-ref3-#-tables.text
-Write graphical output to file cps-24-#-ref3-#-pch.html
-Write graphical output to file cps-24-#-ref3-#-atr.html
-Write graphical output to file cps-24-#-ref3-#-mtr.html
-Execution time is 37.3 seconds
-
-% diff cps-24-#-ref3-#-params.bas cps-24-#-ref3-#-params.ref
+Write baseline policy parameter values to file cps-24-#-ref3-#-#-params.bas
+Write reform policy parameter values to file cps-24-#-ref3-#-#-params.ref
+Write tabular output to file cps-24-#-ref3-#-#-tables.text
+Write graphical output to file cps-24-#-ref3-#-#-pch.html
+Write graphical output to file cps-24-#-ref3-#-#-atr.html
+Write graphical output to file cps-24-#-ref3-#-#-mtr.html
+
+% diff cps-24-#-ref3-#-#-params.bas cps-24-#-ref3-#-#-params.ref
 34c34
 < II_em 0.0
 ---
 > II_em 9059.7
 
-% cat cps-24-#-ref3-#-tables.text
+% cat cps-24-#-ref3-#-#-tables.text
 Weighted Tax Reform Totals by Baseline Expanded-Income Decile
     Returns    ExpInc    IncTax    PayTax     LSTax    AllTax
        (#m)      ($b)      ($b)      ($b)      ($b)      ($b)
@@ -360,15 +365,15 @@ Weighted Tax Differences by Baseline Expanded-Income Decile
 
 The graphs in the three `.html` files can be viewed in your browser.
 
-The `cps-24-#-ref3-#-pch.html` file looks something like this:
+The `cps-24-#-ref3-#-#-pch.html` file looks something like this:
 
 ![pch graph](../_static/pch.png)
 
-The `cps-24-#-ref3-#-atr.html` file looks something like this:
+The `cps-24-#-ref3-#-#-atr.html` file looks something like this:
 
 ![atr graph](../_static/atr.png)
 
-The `cps-24-#-ref3-#-mtr.html` file looks something like this:
+The `cps-24-#-ref3-#-#-mtr.html` file looks something like this:
 
 ![mtr graph](../_static/mtr.png)
 
@@ -411,10 +416,10 @@ exploratory data analysis.
 ```
 % tc cps.csv 2024 --reform ref3.json --dumpdb
 Read input data for 2014; input data were extrapolated to 2024
-Write dump output to sqlite3 database file cps-24-#-ref3-#.db
+Write dump output to sqlite3 database file cps-24-#-ref3-#-#.db
 Execution time is 35.6 seconds
 
-% sqlite3 cps-24-#-ref3-#.db
+% sqlite3 cps-24-#-ref3-#-#.db
 SQLite version 3.39.5 2022-10-14 20:58:05
 Enter ".help" for usage hints.
 sqlite> YOUR FIRST SQL COMMAND GOES HERE
@@ -485,11 +490,11 @@ FROM base JOIN baseline AS b USING(RECID) JOIN reform AS r USING(RECID);
 .headers on
 ```
 
-Using this `tab.sql` script to tabulate the `cps-24-#-ref3-#.db`
+Using this `tab.sql` script to tabulate the `cps-24-#-ref3-#-#.db`
 database produces these results in about 1.3 seconds:
 
 ```
-% sqlite3 cps-24-#-ref3-#.db < tab.sql
+% sqlite3 cps-24-#-ref3-#-#.db < tab.sql
 *** unweighted and weighted tax unit counts:
 raw_count  wgh_count
 ---------  ---------
@@ -533,26 +538,25 @@ Tax-Calculator 4.6.2 on Python 3.12
 
 % tc ../tmd.csv 2026 --numyears 10 --reform ext.json --tables
 Read input data for 2021; input data were extrapolated to 2026
-Write tabular output to file tmd-26-#-ext-#-tables.text
+Write tabular output to file tmd-26-#-ext-#-#-tables.text
 Advance input data and policy to 2027
-Write tabular output to file tmd-27-#-ext-#-tables.text
+Write tabular output to file tmd-27-#-ext-#-#-tables.text
 Advance input data and policy to 2028
-Write tabular output to file tmd-28-#-ext-#-tables.text
+Write tabular output to file tmd-28-#-ext-#-#-tables.text
 Advance input data and policy to 2029
-Write tabular output to file tmd-29-#-ext-#-tables.text
+Write tabular output to file tmd-29-#-ext-#-#-tables.text
 Advance input data and policy to 2030
-Write tabular output to file tmd-30-#-ext-#-tables.text
+Write tabular output to file tmd-30-#-ext-#-#-tables.text
 Advance input data and policy to 2031
-Write tabular output to file tmd-31-#-ext-#-tables.text
+Write tabular output to file tmd-31-#-ext-#-#-tables.text
 Advance input data and policy to 2032
-Write tabular output to file tmd-32-#-ext-#-tables.text
+Write tabular output to file tmd-32-#-ext-#-#-tables.text
 Advance input data and policy to 2033
-Write tabular output to file tmd-33-#-ext-#-tables.text
+Write tabular output to file tmd-33-#-ext-#-#-tables.text
 Advance input data and policy to 2034
-Write tabular output to file tmd-34-#-ext-#-tables.text
+Write tabular output to file tmd-34-#-ext-#-#-tables.text
 Advance input data and policy to 2035
-Write tabular output to file tmd-35-#-ext-#-tables.text
-Execution time is 55.6 seconds
+Write tabular output to file tmd-35-#-ext-#-#-tables.text
 ```
 
 [PR
@@ -567,34 +571,34 @@ fourth column, we can look at the ten-year results quickly:
 
 ```
 % tail -1 tmd-??-*tables.text
-==> tmd-26-#-ext-#-tables.text <==
+==> tmd-26-#-ext-#-#-tables.text <==
  A   192.41   20828.3    -284.0       0.0       0.0    -284.0
 
-==> tmd-27-#-ext-#-tables.text <==
+==> tmd-27-#-ext-#-#-tables.text <==
  A   193.77   21613.4    -291.7       0.0       0.0    -291.7
 
-==> tmd-28-#-ext-#-tables.text <==
+==> tmd-28-#-ext-#-#-tables.text <==
  A   194.72   22404.7    -299.5       0.0       0.0    -299.5
 
-==> tmd-29-#-ext-#-tables.text <==
+==> tmd-29-#-ext-#-#-tables.text <==
  A   195.66   23243.3    -291.8       0.0       0.0    -291.8
 
-==> tmd-30-#-ext-#-tables.text <==
+==> tmd-30-#-ext-#-#-tables.text <==
  A   196.58   24115.1    -299.8       0.0       0.0    -299.8
 
-==> tmd-31-#-ext-#-tables.text <==
+==> tmd-31-#-ext-#-#-tables.text <==
  A   197.48   25020.0    -307.8       0.0       0.0    -307.8
 
-==> tmd-32-#-ext-#-tables.text <==
+==> tmd-32-#-ext-#-#-tables.text <==
  A   198.35   25952.7    -315.7       0.0       0.0    -315.7
 
-==> tmd-33-#-ext-#-tables.text <==
+==> tmd-33-#-ext-#-#-tables.text <==
  A   199.21   26905.4    -323.6       0.0       0.0    -323.6
 
-==> tmd-34-#-ext-#-tables.text <==
+==> tmd-34-#-ext-#-#-tables.text <==
  A   200.03   27878.9    -331.6       0.0       0.0    -331.6
 
-==> tmd-35-#-ext-#-tables.text <==
+==> tmd-35-#-ext-#-#-tables.text <==
  A   200.83   28883.0    -339.6       0.0       0.0    -339.6
 ```
 
@@ -606,7 +610,3 @@ could be called `gawk` or `gawk.exe` on your computer, as follows:
 % tail -1 tmd-??-*tables.text | awk '$1~/A/{n++;c+=$4}END{print n,c}'
 10 -3085.1
 ```
-
-More examples of analyzing different versions of the TCJA after 2025
-are available in this
-[document](https://taxcalc.pslmodels.org/usage/tcja_after_2025.html).

docs/guide/templates/assumption_params_template.md

@@ -1,6 +1,6 @@
 Assumption parameters
 =====================
 
-This section contains documentation of several sets of parameters that characterize responses to a tax reform. Consumption parameters are used to compute marginal tax rates and to compute the consumption value of in-kind benefits. Growdiff parameters are used to specify baseline differences and/or reform responses in the annual rate of growth in economic variables. (Note that behavior parameters used to compute changes in input variables caused by a tax reform in a partial-equilibrium setting are not part of Tax-Calculator, but can be used via the Behavioral-Response `behresp` package in a Python program.)
+This section contains documentation of several sets of parameters that characterize responses to a tax reform. Consumption parameters are used to compute marginal tax rates and to compute the consumption value of in-kind benefits. Growdiff parameters are used to specify baseline differences and/or reform responses in the annual rate of growth in economic variables.
 
 The assumption parameters control advanced features of Tax-Calculator, so understanding the source code that uses them is essential. Default values of many assumption parameters are zero and are projected into the future at that value, which implies no response to the reform. The benefit value consumption parameters have a default value of one, which implies the consumption value of the in-kind benefits is equal to the government cost of providing the benefits.

docs/index.md

@@ -3,7 +3,7 @@ Tax-Calculator
 
 ## What is Tax-Calculator?
 
-Tax-Calculator is an open-source microsimulation model for static analysis of
+Tax-Calculator is an open-source microsimulation model for analysis of
 USA federal income and payroll taxes.
 You can install it with [PyPI](https://pypi.org/project/taxcalc/) via:
 ```
@@ -17,17 +17,13 @@ conda install conda-forge::taxcalc
 
 When using sample data that represent the USA population,
 Tax-Calculator can estimate the aggregate revenue and distributional
-effects of tax reforms under static analysis assumptions.  Read
+effects of tax reforms.  Read
 {doc}`usage/data` for information about the three different prepared
 sample data sets that Tax-Calculator knows how to handle.
 
 Tax-Calculator can also process custom-created data on one or more filing
 units permitting analysis of how tax reforms affect certain people.
 
-Tax-Calculator interacts with other models in the
-[Policy Simulation Library](https://www.pslmodels.org/) to conduct non-static
-analysis.
-
 Tax-Calculator is transparent because its Python source code and embedded
 documentation are publicly available at the
 [Tax-Calculator GitHub repository](https://github.com/PSLmodels/Tax-Calculator).

docs/usage/data.md

@@ -89,9 +89,9 @@ this command for tabular output under 2024 current-law policy:
 ```
 (taxcalc-dev) myruns> TMD_AREA=nm tc tmd.csv 2024 --exact --tables
 Read input data for 2021; input data were extrapolated to 2024
-Write tabular output to file tmd_nm-24-#-#-#.tables
+Write tabular output to file tmd_nm-24-#-#-#-#.tables
 Execution time is 8.2 seconds
-(taxcalc-dev) myruns> awk '$1~/Ret/||$1~/A/' tmd_nm-24-#-#-#.tables | head -2
+(taxcalc-dev) myruns> awk '$1~/Ret/||$1~/A/' tmd_nm-24-#-#-#-#.tables | head -2
     Returns    ExpInc    IncTax    PayTax     LSTax    AllTax
  A     1.17      87.0       7.2       6.9       0.0      14.1
 ```
@@ -102,9 +102,9 @@ files and execute this command:
 ```
 (taxcalc-dev) myruns> TMD_AREA=nm01 tc tmd.csv 2024 --exact --tables
 Read input data for 2021; input data were extrapolated to 2024
-Write tabular output to file tmd_nm01-24-#-#-#.tables
+Write tabular output to file tmd_nm01-24-#-#-#-#.tables
 Execution time is 8.3 seconds
-(taxcalc-dev) myruns> awk '$1~/Ret/||$1~/A/' tmd_nm01-24-#-#-#.tables | head -2
+(taxcalc-dev) myruns> awk '$1~/Ret/||$1~/A/' tmd_nm01-24-#-#-#-#.tables | head -2
     Returns    ExpInc    IncTax    PayTax     LSTax    AllTax
  A     0.40      31.9       2.8       2.5       0.0       5.3
 ```