Load built-in reform file from within taxcalc package

[MaxGhenis]

Does taxcalc have a way to load built-in reform files (e.g. TCJA) directly? So far I've downloaded the file locally, then loaded it using calc_x.read_json_param_objects, e.g. as in [5] of the training notebook.

[martinholmer]

@MaxGhenis asked:

Does taxcalc have a way to load built-in reform files (e.g. TCJA) directly? So far I've downloaded the file locally, then loaded it using calc_x.read_json_param_objects, e.g. as in [5] of the training notebook.

Thanks for your interest in Tax-Calculator.

The short answer to your question is no.

If you want to work locally you have several options all of which involve downloading the JSON reform file to your computer:

• Use it with the source code as described in the notebook you cited in your question. Unless you have access to the proprietary puf.csv input file (IRS sells it rather than making it available publicly), then you would have to use the cps.csv file included in the source code distribution.
• Use it with the tc command-line interface to Tax-Calculator as described in this documentation using either the built-in cps.csv or individual filing units of your own specification as described in the documentation
• Upload the JSON reform file to TaxBrain where it will be analyzed using the proprietary puf.csv input file as described in the documentation.

We're working to fix the other problems you identified. Thanks for the bug reports.

[MattHJensen]

I am giving this an enhancement label. The merits of the enhancement should still be considered.

[martinholmer]

@andersonfrailey and @hdoupe, Can you explain exactly what users have been asking for? How are they using Tax-Calculator? They must not have the source code because all the JSON reform files are included with the source code.

[andersonfrailey]

@martinholmer what they want is a way to work only with the taxcalc package to access the JSON files. Basically for something like this:

from taxcalc.reforms import TCJA_Senate
.
.
.
policy.implement_reform(TCJA_Senate)

[MattHJensen]

tcCLI users would want a similar feature.

[martinholmer]

@MattHJensen , Have any CLI users actually asked for this feature?

[MattHJensen]

Have any CLI users actually asked for this feature?

Not that I know of. @andersonfrailey, have any of the users who have asked you been using the CLI as opposed to the python API?

[andersonfrailey]

No. Everyone I've talked to is using the API.

[martinholmer]

@MattHJensen said about issue #1644:

The merits of the [user requested] enhancement should still be considered.

Yes, I agree we should weigh the benefits for users against the costs for users and developers. I'll discuss the benefits and costs below, but you'll see that in my mind the net benefit of this enhancement is a large negative (that is, benefits are small while costs are large). So, I'm not in favor of pursuing this enhancement.

This issue was raised by @MaxGhenis, who on November 9th asked this question:

Does taxcalc have a way to load built-in reform files (e.g. TCJA) directly? So far I've downloaded the file locally, then loaded it using [static Calculator method] read_json_param_objects.

Benefits
Only one as far as I can see.

1. Users would be able to save 10-20 seconds once for each JSON reform file they are interested in by eliminating the need to copy it from the Tax-Calculator repository and paste it into a file on their local computer.

Costs
Creating an ability similar to the one @andersonfrailey suggested in this issue would require putting all the JSON reform files in the taxcalc package and developing a new methods of specifying those built-in reforms when making an implement_reform call.

1. The development costs of making these changes are quite large as far as I can see.

2. The ability to make quickly available new JSON reform files (that use existing policy parameters) would be lost because new ones would become available only with a new taxcalc release.

3. When users make their own JSON reform files they will not be included in the taxcalc package, and therefore, they will be forced to use the current read_json_param_objects method, which is confusing because there would be two different ways of specifying reforms.

4. Users of of the command-line tool tc are definitely not interested in such an enhancement because they are already working with local files at the command prompt and probably using their favorite graphical diff tool to compare two JSON reform files (to highlight the differences between two reforms).

In summary, it's been almost seven weeks since this issue was raised. During that period many users have been using tc and doing Python programming with the taxcalc package. I don't think having to copy and paste a JSON reform file from the Tax-Calculator repo to the user's local computer has been much of a barrier to using Tax-Calculator.

What do other developers think? Are there other benefits I don't see that would significantly change the benefit-cost balance?

[MaxGhenis]

When I suggested this, I had thought that taxcalc already included all the reform files somewhere hidden. Since it sounds like this is not the case, I agree that a function to load reforms within the package wouldn't make as much sense, especially given @martinholmer's [Cost item] 2 (making reforms quickly available).

Could an alternative be a function that loads reform files by pulling them down from Github itself? Or is there a way to do this today?

I also agree the time-saving benefits are minor. I'd consider the benefits more around reproducibility (it's more clear what reform was used by the analyst and that it wasn't modified) and "cloud-orientation" (it just seems a bit cleaner to avoid reliance on local files, especially as cloud notebooks become more popular).

[feenberg]

On Tue, 19 Dec 2017, Max Ghenis wrote: When I suggested this, I had thought that taxcalc already included all the reform files somewhere hidden. Since it sounds like this is not the case, I agree that a function to load reforms within the package wouldn't make as much sense, especially given @martinholmer's [Cost item] 2 (making reforms quickly available). Could an alternative be a function that loads reform files by pulling them down from Github itself? Or is there a way to do this today?

This isn't my strength, but doesn't Python have rather easy ways to fetch a file via http? Perhaps called Lib/urllib/request.py? dan

[MaxGhenis]

doesn't Python have rather easy ways to fetch a file via http?

Yes, but Calculator.read_json_param_objects takes as arguments strings that point to files in the working directory. Passing URLs directly doesn't work, though looking through the code it looks like passing a json object directly may work?

However, I haven't been able to load the JSON file (see this notebook):

url = 'https://raw.githubusercontent.com/open-source-economics/Tax-Calculator/master/taxcalc/reforms/TCJA_Reconciliation.json'
requests.get(url).json()

produces this error:

ValueError: No JSON object could be decoded

I wonder if this might relate to the comments, so will try with a file without comments soon.

[MaxGhenis]

Removing the comments worked:

url = 'https://raw.githubusercontent.com/MaxGhenis/Tax-Calculator/master/taxcalc/reforms/TCJA_Reconciliation_no_comments.json'
print requests.get(url).json()

This makes sense per https://stackoverflow.com/a/4183018/1840471:

comments of the form //… or /…/ are not allowed in JSON.

NB: taxcalc's _read_json_policy_reform_text strips out comments.

read_json_param_objects takes a text file as another possible input, so using a non-JSON URL reader did the trick:

import urllib2

REFORM_PATH = 'https://raw.githubusercontent.com/open-source-economics/Tax-Calculator/master/taxcalc/reforms/'
url = REFORM_PATH + 'TCJA_Reconciliation.json'

reform_text = urllib2.urlopen(url).read()

reform = Calculator.read_json_param_objects(reform_text, 'JCT_Behavior.json')

This addresses my issue, so feel free to close. Or if there's interest, it could be useful to check if the strings are URLs, and if so to apply the above reader. I could give this a shot.

[martinholmer]

@MaxGhenis said:

This addresses my issue, so feel free to close.

I'm going to accept your invitation to close #1644 because the conversation is being continued in #1777.