Low level Interface to Taxsim with a SAS example
TAXSIM is a network service available via ssh, ftp or http. Notice that it is usually offered as a service, and not a program that is provided. You upload the data, and download the results. This is also the underlying interface used by taxsim on the web, or from Stata. A scriptable client is found on all Windows, OSX and Unix/Linux systems and in SAS, Python, R and many other languages.
Protocol choice
Remote access to taxsim is available via ftp, http, email and ssh. The choice depends on what your application software supports and what your firewall allows. Most modern applications will support some form of network access, or will allow shelling out to curl or ssh. Most firewalls will allow ssh. ssh is the fastest, most reliable overall best choice. You should try it first. If it doesn't work, the other interfaces work too.
Taxsim low-level basics
Taxsim reads a csv file from standard input with variables as
described at the Taxsim web page. Only
2 variables (mstat and law year) are required - the
rest default to zero. Here is a sample file "txpydata.raw" for
testing The correct fiitax returned to standard output is
16,700.04:
taxsimid,mstat,year,ltcg
1,2,1970,100000
Of course, you can have as many data lines as you like, up to
multiple millions. Taxsim will terminate at the first error, and
put an error message to standard output - which would be the last
few lines of the csv file. Common errors would be non-decimal
characters including missing value codes or value labels or
non-zero spousal income on a non-joint return. The error message
will render the csv file unusable as a csv file but readable with
any text editor.
ssh
Our taxsim35.nber.org server has the taxsim35 calculator serving as the shell for users taxsim35 and taxsimtest with null passwords so anyone can use taxsim. Instead of loading a shell to execute arbitrary commands, the server loads the tax calculator. Many applications will allow the user to `shell out' to the OS and issue an ssh command with standard input and output redirected to files on the local computer. You could run a taxsim job from the terminal with:ssh taxsimtest@taxsim35.nber.org < txpydata.raw > results.raw
but there will be some prompts to click through. If taxsim is be scripted, there are ssh options to suppress the prompts:
ftp
Anyone can log onto taxsimftp.nber.org with the username 'taxsim' and password '02138'. Then upload the csv file to directory /tmp under any arbitrary name. Once the file is completely uploaded, you can download the calculated results by tacking '.txm35' or '.txmtest' onto the name used in the upload. We take advantage of the netbsd ftp daemon's automatic inline conversion feature to do the calculation during the download from our server. Old input files are deleted once a day on ftp, they are never saved with the other protocols. ftp is available on all Linux, OSX and Windows systems, but many firewalls block the Windows implementation. GUI file transfer programs won't work, since the results file won't exist until it is requested.
Example with ftp:
If you email taxsim@nber.org with an attachment named "txpydata.raw", and that attachment is a plain ASCII .csv file as described above you should get a return email with a results.raw file of the calculated results as an attachment.
Emailed files are currently limited to 1 megabyte but write to me (feenberg@nber.org) for an exception if you need to process larger files. This is an experimental interface as of March 2021, so if you don't get a response within 5 minutes or so, please contact me.
http
http using curl: http is almost never firewalled but it is possible that a proxy or cache could interfere. One user reports that taxsim35 fails for http submissions if they are much larger than 2,000 records. These problems would be a feature of the client enviroment- there are no limitations imposed at the server.
That's it. Aside from filewalls, you only need to create and upload the file described on the Taxsim web page. Then capture the results file that flows to standard output. But please follow the instructions at http://taxsim.nber.org/taxsim35 carefully. If there are errors in the file, such as non-decimal characters or missing value codes, then the calculation will stop, and the last few lines of the returned .csv file will contain the error message.
Additional Controls
If the default marginal tax rate calculation or level of detail is not to your liking, it is possible to change either with additiona variables. AThese values of mtr affect the marginal tax calculation are:
- 11 - Wages
- 70 - Long term capital gains
- 85 - Primary wage earner
- 86 - Secondary wage earner
These values of idtl affect the output level:
- 0 - standard
- 2 - full
- 5 - with text description
For example descriptive output with several different marginal tax rates:
A SAS application using ftp
Because SAS has a built-in ftp client, you can "call" taxsim from within a SAS program.
/* Demonstrate SAS Taxsim with a one record dataset. */
data txpydata;
input taxsimid mstat year ltcg;
datalines;
1 2 1970 100000
;
run;
filename txpydata ftp "userid" host='taxsimftp.nber.org'
user='taxsim' pass='02138' cd='tmp';
filename results ftp "userid.txm35" host='taxsimftp.nber.org'
user='taxsim' pass='02138' cd='tmp' lrecl=1024;
proc export outfile=txpydata dbms=csv replace;
run;
proc import datafile=results out=results dbms=csv;
run;
proc print; run;
An R application with ftp
The example below uses the RCurl library. Here we create a dataframe, convert it to csv, send it to NBER, retrieve the csv results file, and convert back to a new dataframe. Note that "userid" in the example code could be your userid, to avoid conflicts with other users of taxsim. I would like to thank Christian Jackson for the example.feenberg@nber.org
617-863-0343
last update 17 June 2024 by drf