Merge pull request #119 from noman404/noman404/issue118

Updated readme

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:
 
-<img width="641" alt="Screenshot 2024-07-10 at 6 29 17 PM" src="https://github.com/sgerson2/policyengine-taxsim/assets/113052102/db0ee3e4-9a54-42e7-a4fc-e46f07ab83f8">
+```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).

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"])