README.md

PolicyEngine-TAXSIM

A TAXSIM emulator using the PolicyEngine US federal and state tax calculator.

Table of Contents

• Overview
• Installation
  • From Source
  • From PyPI
• Usage
• Input Variables
  • Demographics
  • Income
  • Output Types
  • Household Types
• Contributing
• License
• Support

Overview

This project provides an emulator for TAXSIM-35, utilizing PolicyEngine's US federal and state tax calculator. It processes tax calculations through a CSV input format compatible with TAXSIM-35 specifications.

Installation

From Source

1. Clone the repository:

   git clone https://github.com/PolicyEngine/policyengine-taxsim.git
   cd policyengine-taxsim

2. Create a virtual environment:

   # For Windows
   python -m venv venv
   venv\Scripts\activate
   
   # For macOS/Linux
   python3 -m venv venv
   source venv/bin/activate

3. Install the package:

   pip install -e .

4. To update the project codebase (for existing project)

   git pull origin main

5. To update dependencies used by the project (for existing project):

   pip install -e . --upgrade

From PyPI

pip install git+https://github.com/PolicyEngine/policyengine-taxsim.git

Usage

Run the simulation by providing your input CSV file:

python policyengine_taxsim/cli.py your_input_file.csv

The output will be generated as output.csv in the same directory.

Input Variables

The emulator accepts CSV files with the following variables:

Demographics

Variable	Description	Notes
taxsimid	Unique identifier
year	Tax year
state	State code
mstat	Marital status	Only supports: 1 (single), 2 (joint)
page	Primary taxpayer age
sage	Spouse age
depx	Number of dependents
age1	First dependent's age
age2	Second dependent's age
ageN	Nth dependent's age	Taxsim only allow upto 8 children dependent

Income

Variable	Description
pwages	Primary taxpayer wages
swages	Spouse wages

Output Types

Depending on the idtl input value it can generate output types as following:

idtl	Description
0	Standard output
2	Full output

Household Types

Supported household types
Single
Joint
Household with Dependent
Household with Dependent single parent

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License

Support

For issues and feature requests, please open an issue.