{smcl}
{* 19 July 2020}{...}
{hline}
help for {it:{hi:taxsim35}} or {it:{hi:taxsimlocal35}}                                         
{hline}

{title:NBER TAXSIM model for federal and state income taxes}

{title:Description}

{p 8 18 2}
{cmdab:taxsim35}[,{cmdab:f:ull} 
{cmdab:s:econdary}|{cmdab:w:ages}|{cmdab:i:nterest}|{cmdab:l:ong} 
{cmdab:d:ebug} {cmdab:r:eplace}]

{p 4 4 2}calculates federal and state income tax liability from 35 input 
variables.  These variables are defined in your current workspace 
before calling taxsim.  The program returns values for various tax return 
concepts, taxes, credits, and marginal tax rates as new named variables in 
a taxsim_out.dta or merged into your current workspace. 

{p 4 4 2}The tax calculator itself is the same FORTRAN program that the 
NBER has been updating annually since 1974, but with a simplified input 
file (no income averaging or rental loss limit, etc). This interface 
merely packages up your data and sends it via the Internet to NBER for the 
actual calculations, which are returned and merged into your current 
dataset. No tax calculations are done on your computer, although there is 
limited range checking of your data.

{title:Input Variables:}

{p 4 4 2}The names and definitions of the 35 input and 45 output variables
are given on the Taxsim web page - 
{browse "http://www.nber.org/taxsim/taxsim35"} . Please study that page - 
it contains vital information.

{p 4 4 2}Not all variables are required. Only {cmd:year} and {cmd:mstat}
are necessary. Unspecified dollar amounts default to zero, taxpayer ages 
default to 50 and all dependent ages to 12 if not otherwise 
specified. {cmd:taxsimid} is optional, and if {cmd:replace} is specified 
the file must be in sort order by {cmd:taxsimid,state,year}. 
{cmd:taxsimid} will be added to your file if not present.

{title:Options}

{p 4 4 2}{cmd:full:} Return many intermediate calculations (taxable 
income, regular tax, individual credits, etc. All the returned variables 
have labels defined in taxsim35.ado - use "describe" to get the full list 
or browse the web page below.

{p 4 4 2}{cmd:secondary:}  Calculate marginal tax rates with respect to
the secondary wage earner. The default is with respect to the primary wage
earner.

{p 4 4 2}{cmd:wages:} Calculate marginal tax rates with respect to a
weighted average of the primary and secondary wage earner.

{p 4 4 2}{cmd:interest:}  Calculate marginal tax rates with respect to
interest income.

{p 4 4 2}{cmd:long:}  Calculate marginal tax rates with respect to
long term gains.

{p 4 4 2}{cmd:replace:} Merge the taxsim output file into the workspace, 
possibly overwriting existing variables. Otherwise output is saved to 
taxsim_out.dta in the current directory. You can run taxsim multiple times 
with the replace option set and the results will not change unless you 
change the input data or procedure options.


{title:Notes:}

It is now the default to write 2 intermediate files to the current 
directory. <cmd:./txpydata.csv} is a csv file of data transmitted to the 
tax calculator and {cmd:./results.raw} contains the resulting 
calculations. Useful error messages may be in the last lines of 
{cmd:./results.csv.

{p 4 4 2}Dollar amounts are rounded to the nearest penny before
transmission to the calculator, and calculated amounts are similarly
treated.

{p 4 4 2}Extreme marginal tax rates due to notches should be filtered
out by the user. 

{p 4 4 2}One user in the midwest reports that 46 million records take 
several hours to run, so clearly large files can be processed. The server 
does not impose a maximum file size but firewalls at the user end of the 
transaction have been known to time out on long http and ftp submissions. 
If this happens, try ssh.
  
{p 4 4 2}-taxsim35.ado- writes the defined variables to a temporary 
ASCII file in the stata temporary directory and uploads that to our 
server via the ssh protocol with a powershell or curl command. The 
returned plaintext (stored in the same directory) provides the 
calculated results. Both files are in .csv format with variable 
names on the first line. You can define an alternate temporary 
directory with a global macro {cmd:tmpdir} and an alternate 
directory for the .dta output with global macro {cms:resdir} which 
otherwise writes to the current directory.. 

{p 4 4 2}The default transfer protocol (ssh) is available in Windows 10 
systems since autumn of 2018.  You may need to add it on the Apps>Apps and 
Features>Manage Optional Features. menu.

{p 4 4 2}The {cmd:ftp} and {cmd:http} options are available to substitute 
those protocols but in tests failed for files over 5,000 records. This 
seems to be a problem with timeouts on the client. {cmd:ftp} will work 
with Windows 10 but you must check the box "File Transfer Program" on the 
"systemsandsecurity>windowsdefenderfirewall>allowedapps>changesettings" 
menu to get past the Windows firewall. Your institution may also have a 
firewall.

{p 4 4 2}

{title:Example:}
{p 4 8 2}{cmd:. input state year mstat ltcg}

{p 4 8 2}{cmd:. 0 1970 2 100000}

{p 4 8 2}{cmd:. end}

{p 4 8 2}{cmd:. taxsim35, full interest replace}{p_end}

{p 4 4 2} The example posits a married taxpayer with $100,000 of long term 
capital gains, and returns the marginal tax rate with respect to interest 
income, among other values. The correct result for fiitax is 16,700.04.

{title:Support:}

{p 4 4 2}Dan Feenberg would like to speak with anyone using this program - 
give him a call after you have done some experimenting, but before 
investing a lot of time and certainly before submitting for publication. 
If you encounter bugs please prepare a test case with no more than 3 
observations and run with the following settings:


{p 4 8 2}{cmd:. log using foo,text}

{p 4 4 2}and also with trace on:

{p 4 8 2}{cmd:. set trace on}
   
{p 4 8 2}{cmd:. taxsim35,debug}

{p 4 4 2}Send the files txpydata.csv,results.csv, and msg.txt files 
from the current directory with your message. If there is no 
results.csv file, that probably means that communication was 
blocked.

{p 4 4 2}Be sure to provide Stata test runs with the smallest possible 
dataset that demonstrates the problem (preferably one record) and attach 
the log and results files. But always follow the instructions below.

{p 4 4 2}If any tax calculation surprises you, please enter the taxpayer 
data in the web form mentioned below. A detailed explanation of the 
calculation will be returned, which may remind you of a code feature or 
interaction you were unaware of. If you still think the calculation is 
wrong, follow the instructions given there for sending bug reports. We are 
very responsive to these communications - they do result in improvements 
to the calculator, generally within a day or two. But please send us a 
single record demonstrating the error, not a large file. Most users 
anticipate we need to be encouraged to respond by the possibility that the 
error is common and submit large files to demonstrate that. This is not 
true and we will respond with a request that the file be cut down.

{p 4 4 2}See {browse "http://www.nber.org/taxsim/taxsim35/"} the TAXSIM 
web site for additional information about the tax caculator. Although that 
is the interface for the Web version of taxsim, there is much valuable 
information there about the operation of the program and the calculation 
of marginal rates which may surprise you. The same fortran code is used 
for http, ftp, Stata, SAS and (maybe soon) R interfaces.

{p 4 4 2}A general description of the calculator itself is given in 
{browse "http://www.nber.org/taxsim/feenberg-coutts.pdf"}.

{col 5}Daniel Feenberg      
{col 5}feenberg@nber.org                    
{col 5}617-863-0343

{p 4 13 2}
Online:  help for {help taxsim35}
{p_end}

{p 4 13 2}
Web: {browse "http://www.nber.org/taxsim/taxsim35"}
{p_end}

