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: ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null taxsim35@taxsimssh.nber.org <txpydata.raw <results.raw SSH is available in Windows 10 since autumn of 2019. If you run an earlier Windows, try installing openssh or use ftp. If a firewall blocks the standard ssh port (22) you can specify port 443 with the -p option to ssh. They respond in exactly the same way.

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:

ftp taxsim@taxsimftp.nber.org passwd:02138 cd tmp put txpydata get txpydata.txm35 quit Curl doesn't work with the conversion feature we are using on our tnftpd server, nor will any GUI ftp client. Stick with a traditional interactive ftp client. Windows has had the same ancient ftp client since forever, and it does work with taxsimftp.

email

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.

curl -F txpydata.raw=@txpydata.raw "https://taxsim.nber.org/taxsim35/redirect.cgi" You can specify an observation in the command line: curl -d "mstat=2&year=1970&ltcg=100000&idtl=5" http://taxsim.nber.org/taxsimtest/redirect.cgi but it is necessary to explicitly specify the idtl value to get a non-error response. Obviously the overhead in this method is high for us, so please don't use it for large files. It is fine to attach taxsim to your interactive program. Curl is in the default install of OSX, Linux and Windows 10 (since autumn of 2019).

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. A

These 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:

taxsimid,mstat,year,ltcg,mtr,idtl 1,2,1970,100000,11,5 1,2,1970,100000,70,5 1,2,1970,100000,85,5 1,2,1970,100000,86,5

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. sample_data <- data.frame(taxsimid = 1, mstat = 2, year = 1970, ltcg = 100000, idtl = 2) library(RCurl) write.csv(sample_data, "./txpydata.csv", row.names = F, na="") ftpUpload("./txpydata.csv", "ftp://taxsim:02138@taxsimftp.nber.org/tmp/userid") results <- getURL("ftp://taxsimftp.nber.org/tmp/userid.txm35", userpwd = "taxsim:02138") taxsim_data <- read.csv(text = results) Daniel Feenberg
feenberg@nber.org
617-863-0343
last update 17 June 2024 by drf