README.md
In usincometaxes: Calculate Federal and State Income Taxes in the United States

usincometaxes is an R package that calculates federal and state income taxes in the United States. It relies on the National Bureau of Economic Research’s (NBER) TAXSIM 35 tax simulator for calculations. The package takes care of the behind-the-scenes work of getting the data in the proper format, converting it to the proper file type for uploading to the NBER server, uploading the data, downloading the results, and placing the results into a tidy data frame.

NOTE: This package is not associated with the NBER. It is a private creation that uses their wonderful tax calculator.

You can install usincometaxes from CRAN:

install.packages('usincometaxes')

usincometaxes helps users estimate household income taxes from data sets containing financial and household data. This allows users to estimate income taxes from surveys with financial information, as the United States Census Public Use Micro Data (PUMS).

The short example below uses taxsim_calculate_taxes() to calculate income taxes.

library(dplyr)
library(knitr)
library(usincometaxes)

family_income <- data.frame(
  taxsimid = c(1, 2),
  state = c('North Carolina', 'NY'),
  year = c(2015, 2020),
  mstat = c('married, jointly', 'single'),
  pwages = c(50000, 100000), # primary wages
  page = c(26, 36) # primary age
)

family_taxes <- taxsim_calculate_taxes(
  .data = family_income,
  marginal_tax_rates = 'Wages',
  return_all_information = FALSE
)

kable(family_taxes)

| taxsimid | fiitax | siitax | fica | frate | srate | ficar | tfica | |---------:|--------:|--------:|------:|------:|------:|------:|------:| | 1 | 3487.5 | 2012.50 | 7650 | 15 | 5.75 | 15.3 | 3825 | | 2 | 15103.5 | 5377.86 | 15300 | 24 | 6.41 | 15.3 | 7650 |

Users can use the taxsimid column to join the tax data with the original data set. Every taxsimid in the input data is represented in the output tax data.

family_income %>%
  left_join(family_taxes, by = 'taxsimid') %>%
  kable()

| taxsimid | state | year | mstat | pwages | page | fiitax | siitax | fica | frate | srate | ficar | tfica | |---------:|:---------------|-----:|:-----------------|-------:|-----:|--------:|--------:|------:|------:|------:|------:|------:| | 1 | North Carolina | 2015 | married, jointly | 50000 | 26 | 3487.5 | 2012.50 | 7650 | 15 | 5.75 | 15.3 | 3825 | | 2 | NY | 2020 | single | 100000 | 36 | 15103.5 | 5377.86 | 15300 | 24 | 6.41 | 15.3 | 7650 |

taxsim_calculate_taxes() returns a data frame where each row corresponds to a row in .data and each column is a piece of tax information. The output and .data can be linked by the taxsimid column.

The amount of output (tax information) received is controlled by the return_all_information parameter to taxsim_calculate_taxes(). Setting return_all_information to FALSE returns minimal information such as federal and state tax liabilities and FICA taxes. When return_all_information is TRUE 44 different tax items are returned.

usoncometax’s output contains the same information and column names as TAXSIM 35. Therefore, please consult either the Description of Output Columns vignette or TAXSIM 35 documentation for more output information.

family_taxes_full_output <- taxsim_calculate_taxes(
  .data = family_income,
  marginal_tax_rates = 'Wages',
  return_all_information = TRUE
)

kable(family_taxes_full_output)

| taxsimid | fiitax | siitax | fica | frate | srate | ficar | tfica | v10_federal_agi | v11_ui_agi | v12_soc_sec_agi | v13_zero_bracket_amount | v14_personal_exemptions | v15_exemption_phaseout | v16_deduction_phaseout | v17_itemized_deductions | v18_federal_taxable_income | v19_tax_on_taxable_income | v20_exemption_surtax | v21_general_tax_credit | v22_child_tax_credit_adjusted | v23_child_tax_credit_refundable | v24_child_care_credit | v25_eitc | v26_amt_income | v27_amt_liability | v28_fed_income_tax_before_credit | v29_fica | v30_state_household_income | v31_state_rent_expense | v32_state_agi | v33_state_exemption_amount | v34_state_std_deduction_amount | v35_state_itemized_deduction | v36_state_taxable_income | v37_state_property_tax_credit | v38_state_child_care_credit | v39_state_eitc | v40_state_total_credits | v41_state_bracket_rate | v42_self_emp_income | v43_medicare_tax_unearned_income | v44_medicare_tax_earned_income | v45_cares_recovery_rebate | |---------:|--------:|--------:|------:|------:|------:|------:|------:|----------------:|-----------:|----------------:|------------------------:|------------------------:|-----------------------:|-----------------------:|------------------------:|---------------------------:|--------------------------:|---------------------:|-----------------------:|------------------------------:|--------------------------------:|----------------------:|---------:|---------------:|------------------:|---------------------------------:|---------:|---------------------------:|-----------------------:|--------------:|---------------------------:|-------------------------------:|-----------------------------:|-------------------------:|------------------------------:|----------------------------:|---------------:|------------------------:|-----------------------:|--------------------:|---------------------------------:|-------------------------------:|--------------------------:| | 1 | 3487.5 | 2012.50 | 7650 | 15 | 5.75 | 15.3 | 3825 | 50000 | 0 | 0 | 12600 | 8000 | 0 | 0 | 0 | 29400 | 3487.5 | 0 | 0 | 0 | 0 | 0 | 0 | 50000 | 0 | 3487.5 | 7650 | 50000.01 | 0 | 50000.01 | 0 | 15000 | 0 | 35000.01 | 0 | 0 | 0 | 0 | 0.00 | 50000 | 0 | 0 | 0 | | 2 | 15103.5 | 5377.86 | 15300 | 24 | 6.41 | 15.3 | 7650 | 100000 | 0 | 0 | 12400 | 0 | 0 | 0 | 0 | 87600 | 15103.5 | 0 | 0 | 0 | 0 | 0 | 0 | 100000 | 0 | 15103.5 | 15300 | 100001.01 | 0 | 100000.01 | 0 | 8000 | 0 | 92000.01 | 0 | 0 | 0 | 0 | 6.41 | 100000 | 0 | 0 | 0 |

Taxes are calculated with taxsim_calculate_taxes() using the financial and household characteristics found in the data frame represented by the .data parameter. Each column is a different piece of information and each row contains a tax payer unit.

All columns must have the column names and data types listed in the Description of Input Columns vignette. These are the same column names found in the TAXSIM 35 documentation. Therefore, you can consult the package documentation or TAXSIM 35 documentation for more information on input columns. There are two differences between usincometaxes and TAXSIM 35:

usincometaxes allows users to specify the state with either the two letter abbreviation or state SOI code. usincometaxes will convert the abbreviation to an SOI code for TAXSIM 35.
For filing status, mstat, users can either use the TAXSIM 35 integer found in TAXSIM 35’s documentation or one of the following descriptions:
- “single” or 1 for single;
- “married, jointly” or 2 for married, filing jointly;
- “married, separately” or 6 for married, filing separately;
- “dependent child” or 8 for dependent, usually a child with income; or
- “head of household” or 1 for head of household filing status.

The input data frame, .data, can contain columns beyond those listed in the vignette. The additional columns will be ignored.

By default, marginal tax rates are calculated using wages. The default can be changed with the marginal_tax_rates parameter to taxsim_calculate_taxes(). Possible options are: ‘Wages’ (default), ‘Long Term Capital Gains’, ‘Primary Wage Earner’, or ‘Secondary Wage Earner’.

The NBER’s TAXSIM 35 tax simulator does all tax calculations. This package simply lets users interact with the tax simulator through R. Therefore, users should cite the TAXSIM 35 tax simulator when they use this package in their work:

Feenberg, Daniel Richard, and Elizabeth Coutts, An Introduction to the TAXSIM Model, Journal of Policy Analysis and Management vol 12 no 1, Winter 1993, pages 189-194.

Aman Gupta Karmani created the WebAssembly / JavaScript files. These files also power his tax calculator web app at taxsim.app.