-
Notifications
You must be signed in to change notification settings - Fork 2
/
README.Rmd
139 lines (103 loc) · 5.71 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
message = FALSE,
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
options(scipen = 999)
```
<!-- badges: start -->
<!-- badges: end -->
## Calculate Federal and State Income Taxes
`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](http://taxsim.nber.org/taxsim35/)
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.*
## Installation
You can install `usincometaxes` from CRAN:
```{r eval = FALSE}
install.packages('usincometaxes')
```
## Quick example
`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.
```{r quickExample}
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
)
```
```{r}
kable(family_taxes)
```
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.
```{r joinData}
family_income %>%
left_join(family_taxes, by = 'taxsimid') %>%
kable()
```
## Output
`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](http://taxsim.nber.org/taxsim35/).
Therefore, please consult either the [Description of Output Columns vignette](https://www.shaneorr.io/r/usincometaxes/articles/taxsim-output.html) or [TAXSIM 35 documentation](http://taxsim.nber.org/taxsim35/) for more output information.
```{r}
family_taxes_full_output <- taxsim_calculate_taxes(
.data = family_income,
marginal_tax_rates = 'Wages',
return_all_information = TRUE
)
kable(family_taxes_full_output)
```
## Input
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](https://www.shaneorr.io/r/usincometaxes/articles/taxsim-input.html) vignette.
These are the same column names found in the [TAXSIM 35](http://taxsim.nber.org/taxsim35/) 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:
1. `usincometaxes` allows users to specify the state with either the two letter abbreviation or [state SOI code](https://taxsim.nber.org/statesoi.html).
`usincometaxes` will convert the abbreviation to an SOI code for TAXSIM 35.
2. 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.
## Marginal tax rates
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'.
## Giving credit
The NBER's [TAXSIM 35](http://taxsim.nber.org/taxsim35/) 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](https://github.com/tmm1/taxsim.js). These files also power his tax calculator web app at [taxsim.app](https://taxsim.app).