Add CLI --behavior option

[martinholmer]

The Tax-Calculator Python API has long been able to conduct tax analysis assuming behavioral responses to a reform, as illustrated in the Recipe 2 documentation.

This PR adds that ability to the Tax-Calculator CLI.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (48928ef) to head (3028693).
⚠️ Report is 29 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff            @@
##            master     #2981   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           13        13           
  Lines         2641      2712   +71     
=========================================
+ Hits          2641      2712   +71     

Flag	Coverage Δ
unittests	100.00% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
taxcalc/__init__.py	100.00% <100.00%> (ø)
taxcalc/calculator.py	100.00% <100.00%> (ø)
taxcalc/taxcalcio.py	100.00% <100.00%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[jdebacker]

One note on this: The Tax-Brain package already has a CLI that allows one to run the Tax-Calculator model with behavioral responses.

[jdebacker]

I've reviewed the files and confirmed all local tests pass.

My only comments on this PR are:

• I would stick with the language of "static analysis" since, that's what Tax-Calculator is doing, even with behavioral response (without behavior, sometimes this is called the "truly static" estimate or the mechanical effects of a tax policy change).
• I would like to hear from @MattHJensen on this since he suggested these changes, but had in the past supported keeping Tax-Calculator a streamlined model with just the tax logic, while other packages supported the creation of tax data (e.g. the TaxData or TMD projects), modeling of behavioral responses (e.g. the Behavioral Responses package, or dynamic analysis (e.g., OG-USA. The idea was then that the Tax-Brain package would serve as the "integrator" app, pulling together data, tax logic, models of behavioral responses, and macroeconomic effects and making them all accessible in a single interface (with a Python API and a CLI -- and in the past a web application). Tax-Brain currently has a CLI with a behavior option (the addition in this PR). While the Tax-Brain CLI may not produce the same output as the Tax-Calculator CLI, it may be useful to document how the CLI addition in this PR differs from what is done in Tax-Brain and why effort is spent updating the CLI in Tax-Calculator rather than the CLI in Tax-Brain. @MattHJensen may be best positioned to comment on this given his direction in these projects.

[martinholmer]

@jdebacker said in the discussion of PR #2981:

Tax-Brain currently has a CLI with a behavior option ... . While the Tax-Brain CLI may not produce the same output as the Tax-Calculator CLI, it may be useful to document how the CLI addition in this PR differs from what is done in Tax-Brain and why effort is spent updating the CLI in Tax-Calculator rather than the CLI in Tax-Brain.

There are several reasons why the Tax-Calculator CLI is being enhanced so that behavioral responses can be assumed. @MattHJensen can provide you with the user interface reason, but I can mention a couple of other reasons here.

Tax-Brain CLI does not work

After installing Tax-Brain, I get the help message OK, but then get these errors:

(taxcalc-dev) behavioral_responses_tests> taxbrain --help     
usage: taxbrain [-h] [--data DATA] [--reform REFORM] [--behavior BEHAVIOR] [--assump ASSUMP] [--baseline BASELINE]
                [--outdir OUTDIR] [--name NAME] [--report] [--author AUTHOR]
                startyear endyear

This is the command line interface for the taxbrain package.

positional arguments:
  startyear            startyear is the first year of the analysis you want to run.
  endyear              endyear is the last year of the analysis you want to run.

options:
  -h, --help           show this help message and exit
  --data DATA          The file path to a micro-dataset that is formatted for use in Tax-Calculator.
  --reform REFORM      --reform should be a path to a JSON file.
  --behavior BEHAVIOR  --behavior should be a path to a JSON file containing behavioral assumptions.
  --assump ASSUMP      --assump should be a path to a JSON file containing user specified economic assumptions.
  --baseline BASELINE  --baseline should be a path to a JSON file containing a policy that will be used as the baseline
                       of the analysis
  --outdir OUTDIR      outdir is the name of the output directory. Not including --outdir will result in files being
                       written to the current directory.
  --name NAME          Name of the analysis. This will be used to name the directory where all output files will be
                       written.
  --report             including --report will trigger the creation of a PDF report summarizing the effects of the tax
                       policy being modeled.
  --author AUTHOR      If you are creating a report, this the name that will be listed as the author

(taxcalc-dev) behavioral_responses_tests> taxbrain 2035 2035 --data cps.csv --reform ref.json --behavior br1.json 
Traceback (most recent call last):
  File "/opt/anaconda3/envs/taxcalc-dev/bin/taxbrain", line 7, in <module>
    sys.exit(cli_main())
             ~~~~~~~~^^
  File "/opt/anaconda3/envs/taxcalc-dev/lib/python3.13/site-packages/taxbrain/cli.py", line 227, in cli_main
    args.usecps,
    ^^^^^^^^^^^
AttributeError: 'Namespace' object has no attribute 'usecps'

Then I tried to use the TMD input data.

(taxcalc-dev) behavioral_responses_tests> ls -l  ~/Tax-Calculator/tmd*                                      
-rw-r--r--@ 1 mrh  staff     12611 Feb 11  2025 /Users/mrh/Tax-Calculator/tmd_growfactors.csv
-rw-r--r--@ 1 mrh  staff  52609134 Feb 11  2025 /Users/mrh/Tax-Calculator/tmd_weights.csv.gz
-rw-r--r--  1 mrh  staff  60903481 Feb 11  2025 /Users/mrh/Tax-Calculator/tmd.csv

(taxcalc-dev) behavioral_responses_tests> taxbrain 2035 2035 --data ~/Tax-Calculator/tmd.csv --reform ref.json --behavior br1.json
Traceback (most recent call last):
  File "/opt/anaconda3/envs/taxcalc-dev/bin/taxbrain", line 7, in <module>
    sys.exit(cli_main())
             ~~~~~~~~^^
  File "/opt/anaconda3/envs/taxcalc-dev/lib/python3.13/site-packages/taxbrain/cli.py", line 227, in cli_main
    args.usecps,
    ^^^^^^^^^^^
AttributeError: 'Namespace' object has no attribute 'usecps'

Tax-Brain cannot use TMD input data

According to Tax-Brain pull request 206, Tax-Brain cannot handle the new TMD input data.

Conclusion

So, it looks as if Tax-Brain would need some work to be able to do what the Tax-Calculator CLI does after this PR is merged. Centralizing the CLI capabilities in one model makes it easier to develop a new type of model interface.

[MattHJensen]

This lgtm and I think adding behavior to taxcalc cli is an expedient step at the moment. Thanks Martin and Jason!