diff --git a/README.md b/README.md index 380e753..9077bf9 100644 --- a/README.md +++ b/README.md @@ -1,57 +1,127 @@ -# Policyengine-taxsim -TAXSIM emulator using the PolicyEngine US federal and state tax calculator +# PolicyEngine-TAXSIM + +A TAXSIM emulator using the PolicyEngine US federal and state tax calculator. + +## Table of Contents +- [Overview](#overview) +- [Installation](#installation) + - [From Source](#from-source) + - [From PyPI](#from-pypi) +- [Usage](#usage) +- [Input Variables](#input-variables) + - [Demographics](#demographics) + - [Income](#income) + - [Output Types](#output-types) + - [Household Types](#household-types) +- [Contributing](#contributing) +- [License](#license) +- [Support](#support) -## How to use the emulator ## -The emulator takes a .csv file in the form of a csv. This is the same form of input that Taxsim-35 takes. +## Overview -**Open your terminal in the parent directory** +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. -1. To install this package +## Installation -`pip install -e .` +### From Source -2. to execute the simulation, run +1. Clone the repository: + ```bash + git clone https://github.com/PolicyEngine/policyengine-taxsim.git + cd policyengine-taxsim + ``` +2. Create a virtual environment: + ```bash + # For Windows + python -m venv venv + venv\Scripts\activate -`python policyengine_taxsim/cli.py resources/taxsim35/taxsim_input.csv ` + # For macOS/Linux + python3 -m venv venv + source venv/bin/activate + ``` -Output will be generated as `output.csv` in the same directory +3. Install the package: + ```bash + pip install -e . + ``` +4. To update the project codebase (for existing project) + ```bash + git pull origin main + ``` +5. To update dependencies used by the project (for existing project): + ```bash + pip install -e . --upgrade + ``` -**For directly installing from pip** +### From PyPI -You can install through to execute directly +```bash +pip install git+https://github.com/PolicyEngine/policyengine-taxsim.git +``` -`pip install git+https://github.com/PolicyEngine/policyengine-taxsim.git` +## Usage -### Example ## -input file: +Run the simulation by providing your input CSV file: -Screenshot 2024-07-10 at 6 29 17 PM +```bash +python policyengine_taxsim/cli.py your_input_file.csv +``` +The output will be generated as `output.csv` in the same directory. -## List of working input variables ## +## Input Variables -### Demographics: ### -1. taxsimid -2. year -3. state -4. mstat (only 1 (single) and 2 (joint) filing options work) -5. page (age of primary taxpayer) -6. sage (age of spouse) -7. depx (number of dependents) -8. age1 (age of first dependent) -9. age2 (age of second dependent) -10. age3 (age of third dependent) +The emulator accepts CSV files with the following variables: -### Income: ### -1. pwages (wage of primary taxpayer) -2. swages (wage of spouse) -3. psemp (self-employment income of primary taxpayer) -4. ssemp (self-employment income of spouse) -5. dividends (dividend income) -6. intrec (taxable interest received) -7. stcg (short-term capital gains) -8. ltcg (long-term capital gains) -9. pui (primary taxpayer unemployment compensation received) -10. sui (spouse unemployment compensation received) -11. proptax (real estate taxes paid) +### 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](https://github.com/PolicyEngine/policyengine-taxsim?tab=License-1-ov-file#) + +## Support + +For issues and feature requests, please [open an issue](https://github.com/PolicyEngine/policyengine-taxsim/issues). \ No newline at end of file diff --git a/policyengine_taxsim/core/input_mapper.py b/policyengine_taxsim/core/input_mapper.py index ebf4d16..0391f10 100644 --- a/policyengine_taxsim/core/input_mapper.py +++ b/policyengine_taxsim/core/input_mapper.py @@ -78,13 +78,33 @@ def form_household_situation(year, state, taxsim_vars): return household_situation -def check_if_exists_or_set_defaults(taxsim_vars): - taxsim_vars["state"] = int(taxsim_vars.get("state", - 44) or 44) # set TX (texas) as default is no state field has passed or passed as 0 +def set_taxsim_defaults(taxsim_vars: dict) -> dict: + """ + Set default values for TAXSIM variables if they don't exist or are falsy. + + Args: + taxsim_vars (dict): Dictionary containing TAXSIM input variables - taxsim_vars["depx"] = int(taxsim_vars.get("depx", 0) or 0) + Returns: + dict: Updated dictionary with default values set where needed + + Default values: + - state: 44 (Texas) + - depx: 0 (Number of dependents) + - mstat: 1 (Marital status) + - taxsimid: 0 (TAXSIM ID) + - idtl: 0 (output flag) + """ + DEFAULTS = { + "state": 44, # Texas + "depx": 0, # Number of dependents + "mstat": 1, # Marital status + "taxsimid": 0, # TAXSIM ID + "idtl": 0 # output flag + } - taxsim_vars["mstat"] = int(taxsim_vars.get("mstat", 1) or 1) + for key, default_value in DEFAULTS.items(): + taxsim_vars[key] = int(taxsim_vars.get(key, default_value) or default_value) return taxsim_vars @@ -102,7 +122,7 @@ def generate_household(taxsim_vars): year = str(int(taxsim_vars["year"])) # Ensure year is an integer string - taxsim_vars = check_if_exists_or_set_defaults(taxsim_vars) + taxsim_vars = set_taxsim_defaults(taxsim_vars) state = get_state_code(taxsim_vars["state"])