### Setup Policy Engine (One-Time)

Source: https://github.com/policyengine/policyengine-taxsim/blob/main/r-package/policyenginetaxsim/README.md

Run this function once after installation to set up the Policy Engine. This process may take 5-10 minutes.

```r
library(policyenginetaxsim)
setup_policyengine()
```

--------------------------------

### Setup PolicyEngine Dashboard Development Server

Source: https://github.com/policyengine/policyengine-taxsim/blob/main/README.md

Install dependencies and start the development server for the PolicyEngine React-based dashboard. Access the dashboard at http://localhost:3000.

```bash
cd dashboard
npm install
npm start
```

--------------------------------

### Install from GitHub

Source: https://github.com/policyengine/policyengine-taxsim/blob/main/README.md

Installs the policyengine-taxsim package directly from its GitHub repository using uv.

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

--------------------------------

### Clone Repository and Install from Source

Source: https://github.com/policyengine/policyengine-taxsim/blob/main/README.md

Clones the policyengine-taxsim repository and installs it locally using a virtual environment and uv. Ensure you have git and uv installed.

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

# Create a virtual environment and install:
uv venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
uv pip install -e .
```

--------------------------------

### Install and Run Comparison Analysis

Source: https://github.com/policyengine/policyengine-taxsim/blob/main/README.md

Installs the policyengine-taxsim package using uv and runs a comparison analysis on sample data. Requires uv for installation.

```bash
# Install (requires uv: https://docs.astral.sh/uv/getting-started/installation/)
uv pip install git+https://github.com/PolicyEngine/policyengine-taxsim.git

# Run a comparison analysis on sample data
policyengine-taxsim compare your_data.csv --sample 1000 --year 2021
```

--------------------------------

### Example PolicyEngine Calculation with Options

Source: https://github.com/policyengine/policyengine-taxsim/blob/main/README.md

An example of running PolicyEngine calculations with specified output file, log generation, and a sample size.

```bash
policyengine-taxsim policyengine input.csv --output results.csv --logs --sample 1000
```

--------------------------------

### Example TAXSIM Calculation with Output

Source: https://github.com/policyengine/policyengine-taxsim/blob/main/README.md

An example of running TAXSIM calculations and directing the output to a specific CSV file.

```bash
policyengine-taxsim taxsim input.csv --output taxsim_results.csv
```

--------------------------------

### Check Policy Engine Setup Status

Source: https://github.com/policyengine/policyengine-taxsim/blob/main/r-package/policyenginetaxsim/README.md

Verify if the Policy Engine setup is complete. This is useful for troubleshooting.

```r
# Check if setup is complete
check_policyengine_setup()
```

--------------------------------

### Install policyenginetaxsim Package

Source: https://github.com/policyengine/policyengine-taxsim/blob/main/r-package/policyenginetaxsim/README.md

Install the package from GitHub using devtools. Ensure R 4.0+ is installed.

```r
install.packages("devtools")
devtools::install_github("PolicyEngine/policyengine-taxsim",
                          subdir = "r-package/policyenginetaxsim")
```

--------------------------------

### Install PolicyEngine TAXSIM R Package

Source: https://github.com/policyengine/policyengine-taxsim/blob/main/r-package/README.md

Install the package from GitHub or a local clone using devtools.

```r
devtools::install_github("PolicyEngine/policyengine-taxsim", subdir = "r-package/policyenginetaxsim")
```

```r
devtools::install("r-package/policyenginetaxsim")
```

--------------------------------

### Install PolicyEngine TAXSIM Emulator

Source: https://github.com/policyengine/policyengine-taxsim/blob/main/dashboard/social-posts.md

Install the policyengine-taxsim package using pip. This command is used across various platforms and environments.

```bash
pip install policyengine-taxsim
```

--------------------------------

### Run Tests with Pytest

Source: https://github.com/policyengine/policyengine-taxsim/blob/main/CLAUDE.md

Execute all tests in the project using the pytest command. Ensure pytest is installed in your environment.

```bash
pytest tests/
```

--------------------------------

### Update Project Dependencies

Source: https://github.com/policyengine/policyengine-taxsim/blob/main/README.md

Updates the dependencies for an existing local installation of policyengine-taxsim. Run this command within the project directory after pulling changes.

```bash
uv pip install -e . --upgrade
```

--------------------------------

### Get Detailed Tax Calculation Output

Source: https://github.com/policyengine/policyengine-taxsim/blob/main/r-package/policyenginetaxsim/README.md

Retrieve over 30 detailed variables from the tax calculation, including AGI, deductions, and credits, by setting return_all_information to TRUE.

```r
results <- policyengine_calculate_taxes(my_data, return_all_information = TRUE)
# Returns 30+ variables: AGI, deductions, credits, etc.
```

--------------------------------

### Build PolicyEngine Dashboard for Production

Source: https://github.com/policyengine/policyengine-taxsim/blob/main/README.md

Create a production-ready build of the PolicyEngine dashboard. This command optimizes the application for deployment.

```bash
npm run build
```

--------------------------------

### Run TAXSIM-35 Replacement (stdin/stdout)

Source: https://context7.com/policyengine/policyengine-taxsim/llms.txt

Use this command as a direct replacement for the TAXSIM-35 binary, reading from stdin and writing to stdout. Optional flags like --sample can be used for larger datasets.

```bash
# Prepare a minimal TAXSIM input CSV
cat > input.csv << 'EOF'
taxsimid,year,state,mstat,pwages,swages,depx,page,sage,idtl
1,2023,44,1,75000,0,0,35,0,0
2,2023,6,2,120000,45000,2,42,40,2
3,2022,36,1,0,0,0,67,0,0
EOF

# Run as a drop-in TAXSIM replacement (stdin → stdout)
policyengine-taxsim < input.csv > output.csv

# With optional flags
policyengine-taxsim --sample 1000 --logs < large_input.csv > output.csv

# Expected output.csv columns (idtl=0): taxsimid, year, state, fiitax, siitax, fica
# Expected output.csv columns (idtl=2): above + v10..v40, qbid, niit, frate, srate
```

--------------------------------

### Run PolicyEngine Calculations

Source: https://github.com/policyengine/policyengine-taxsim/blob/main/README.md

Calculates taxes using PolicyEngine for a given input file. Specify output file, logging, SALT tax handling, and sampling options as needed.

```bash
policyengine-taxsim policyengine your_input_file.csv
```

--------------------------------

### Compare PolicyEngine and TAXSIM

Source: https://github.com/policyengine/policyengine-taxsim/blob/main/README.md

Run a basic comparison between PolicyEngine and TAXSIM using a CSV input file. This command initiates a side-by-side analysis of tax calculations.

```bash
policyengine-taxsim compare your_input_file.csv
```

--------------------------------

### PolicyEngine-TAXSIM Comparison with Options

Source: https://github.com/policyengine/policyengine-taxsim/blob/main/README.md

Perform a comparison with specific options, such as sampling records and enabling detailed logging for PolicyEngine. This allows for more focused analysis and debugging.

```bash
policyengine-taxsim compare cps_households.csv --sample 1000
```

```bash
policyengine-taxsim compare input.csv --year 2023 --logs --sample 5000
```

--------------------------------

### Compare PolicyEngine and TAXSIM Results

Source: https://context7.com/policyengine/policyengine-taxsim/llms.txt

Runs both PolicyEngine and TAXSIM on the same input data, generating a consolidated CSV with match/mismatch flags. Includes options for year-specific comparisons, logging, and disabling SALT deductions.

```bash
# Basic comparison
policyengine-taxsim compare cps_households.csv --sample 1000

# Year-specific with logging
policyengine-taxsim compare input.csv \
  --year 2023 \
  --sample 5000 \
  --output-dir ./comparison_output \
  --logs \
  --disable-salt

# Console output:
# Comparing 1000 records present in both datasets
# Comparison Results (TAXSIM vs PolicyEngine):
# Total Records: 1000
# Federal Tax Matches: 947 (94.70%)
# State Tax Matches:   891 (89.10%)

# Output file: comparison_output/comparison_results_2023.csv
# Columns: [all input vars] + source, federal_match, state_match, overall_match,
#          fiitax, siitax, fica, v10..v40 (from both TAXSIM and PolicyEngine rows)
```

--------------------------------

### Run PolicyEngine Calculation (file-based)

Source: https://context7.com/policyengine/policyengine-taxsim/llms.txt

Processes a TAXSIM input file using PolicyEngine's engine and writes results to a specified output file. Supports logging and SALT deduction overrides.

```bash
# Basic usage
policyengine-taxsim policyengine input.csv --output results.csv

# With all options
policyengine-taxsim policyengine input.csv \
  --output results.csv \
  --sample 2000 \
  --logs \
  --disable-salt \
  --assume-w2-wages

# --logs generates one YAML file per record (e.g. taxsim_record_1_2023.yaml):
# - name: taxsim_record_1_2023.yaml
#   absolute_error_margin: 2
#   period: 2023
#   input:
#     people:
#       person1: {age: 35, employment_income: 75000, ...}
#     households:
#       household: {state_fips: 48}
#   output:
#     tx_income_tax: 0.0
```

--------------------------------

### export_household(taxsim_input, policyengine_situation, logs, disable_salt)

Source: https://context7.com/policyengine/policyengine-taxsim/llms.txt

Runs a PolicyEngine simulation on a pre-built situation and converts the results to a TAXSIM-formatted output dictionary. When `idtl=5`, it returns a text description.

```APIDOC
## Python API: `export_household(taxsim_input, policyengine_situation, logs, disable_salt)`

Runs a PolicyEngine simulation on a pre-built situation and converts the results to a TAXSIM-formatted output dictionary (or text description when `idtl=5`).

```python
from policyengine_taxsim import generate_household, export_household

taxsim_input = {
    "taxsimid": 42,
    "year": 2023,
    "state": 36,      # New York
    "mstat": 2,       # Married filing jointly
    "page": 45,
    "sage": 43,
    "pwages": 150000,
    "swages": 60000,
    "depx": 2,
    "age1": 14,
    "age2": 10,
    "mortgage": 18000,
    "proptax": 8000,
    "idtl": 2,        # Full output
}

situation = generate_household(taxsim_input)
result = export_household(
    taxsim_input=taxsim_input,
    policyengine_situation=situation,
    logs=False,
    disable_salt=False
)

# result is a dict with TAXSIM output variables:
# {
#   "taxsimid": 42, "year": 2023, "state": 36,
#   "fiitax": 35821.0,   # Federal income tax
#   "siitax": 12540.0,   # NY state income tax
#   "fica": 16074.0,     # FICA taxes
#   "v10": 198500.0,     # Federal AGI
#   "v18": 162950.0,     # Federal taxable income
#   "v22": 2000.0,       # Child tax credit
#   "v32": 185000.0,     # State AGI
#   "frate": 24.0,       # Federal marginal rate (%)
#   "srate": 6.85,       # State marginal rate (%)
#   ...
# }
print(f"Federal tax: ${result['fiitax']:,.2f}")
print(f"State tax:   ${result['siitax']:,.2f}")
print(f"Federal MTR: {result.get('frate', 'N/A')}%)"
```
```

--------------------------------

### Create Changelog Fragment

Source: https://github.com/policyengine/policyengine-taxsim/blob/main/CLAUDE.md

Add a fragment file to the changelog.d/ directory to describe a change. The file name determines the type of change and its semver bump.

```bash
echo "Description of change." > changelog.d/<branch-name>.<type>.md
```

--------------------------------

### Generate and Copy Comparison Data for Dashboard

Source: https://github.com/policyengine/policyengine-taxsim/blob/main/README.md

Generate new comparison data using policyengine-taxsim and then copy the results to the dashboard's public data directory. Restart the dashboard to load the updated data.

```bash
policyengine-taxsim compare your_data.csv --year 2024
cp comparison_output/comparison_results_2024.csv dashboard/public/data/2024/
```

--------------------------------

### Run Native TAXSIM-35 Binary

Source: https://context7.com/policyengine/policyengine-taxsim/llms.txt

Executes the native TAXSIM-35 binary, writing results in the standard TAXSIM output format. Allows specifying a custom path to the TAXSIM binary and sampling.

```bash
# Run with local TAXSIM binary (auto-detected)
policyengine-taxsim taxsim input.csv --output taxsim_results.csv

# Run with a custom TAXSIM binary path
policyengine-taxsim taxsim input.csv \
  --output taxsim_results.csv \
  --taxsim-path /usr/local/bin/taxsim35 \
  --sample 500

# Output: taxsim_results.csv with TAXSIM-35 standard columns
# taxsimid, year, state, fiitax, siitax, fica, [v10-v40 if idtl=2]
```

--------------------------------

### Reinstall Policy Engine with Force Option

Source: https://github.com/policyengine/policyengine-taxsim/blob/main/r-package/policyenginetaxsim/README.md

Reinstall the Policy Engine, forcing the process even if it appears to be already set up. Use this if encountering issues.

```r
# Reinstall if something went wrong
setup_policyengine(force = TRUE)
```

--------------------------------

### Export PolicyEngine Simulation Results to TAXSIM Format

Source: https://context7.com/policyengine/policyengine-taxsim/llms.txt

Runs a PolicyEngine simulation on a pre-built situation and converts the results to a TAXSIM-formatted output dictionary. Set `idtl=5` for a text description instead of a dictionary.

```python
from policyengine_taxsim import generate_household, export_household

taxsim_input = {
    "taxsimid": 42,
    "year": 2023,
    "state": 36,      # New York
    "mstat": 2,       # Married filing jointly
    "page": 45,
    "sage": 43,
    "pwages": 150000,
    "swages": 60000,
    "depx": 2,
    "age1": 14,
    "age2": 10,
    "mortgage": 18000,
    "proptax": 8000,
    "idtl": 2,        # Full output
}

situation = generate_household(taxsim_input)
result = export_household(
    taxsim_input=taxsim_input,
    policyengine_situation=situation,
    logs=False,
    disable_salt=False
)

# result is a dict with TAXSIM output variables:
# {
#   "taxsimid": 42, "year": 2023, "state": 36,
#   "fiitax": 35821.0,   # Federal income tax
#   "siitax": 12540.0,   # NY state income tax
#   "fica": 16074.0,     # FICA taxes
#   "v10": 198500.0,     # Federal AGI
#   "v18": 162950.0,     # Federal taxable income
#   "v22": 2000.0,       # Child tax credit
#   "v32": 185000.0,     # State AGI
#   "frate": 24.0,       # Federal marginal rate (%)
#   "srate": 6.85,       # State marginal rate (%)
#   ...
# }
print(f"Federal tax: ${result['fiitax']:,.2f}")
print(f"State tax:   ${result['siitax']:,.2f}")
print(f"Federal MTR: {result.get('frate', 'N/A')}%")
```

--------------------------------

### Initialize result list

Source: https://github.com/policyengine/policyengine-taxsim/blob/main/run-project.ipynb

Initializes an empty list to store the output from the subprocess.

```python
result = []
```

--------------------------------

### REST API: POST /run

Source: https://context7.com/policyengine/policyengine-taxsim/llms.txt

Synchronous endpoint: accepts a TAXSIM CSV string, runs the simulation, and returns the output CSV. Deployed via Modal or run locally with uvicorn.

```APIDOC
## REST API: `POST /run`

Synchronous endpoint: accepts a TAXSIM CSV string, runs the simulation, and returns the output CSV. Deployed via Modal or run locally with uvicorn.

```bash
# Local server
uvicorn policyengine_taxsim.api:local_app --port 8440

# POST /run — synchronous, returns full CSV in JSON body
curl -s -X POST http://localhost:8440/run \
  -H "Content-Type: application/json" \
  -d '{ 
    "csv": "taxsimid,year,state,mstat,pwages,depx,page,sage,idtl\n1,2023,44,1,75000,0,35,0,0\n2,2023,6,2,120000,0,42,40,2",
    "disable_salt": false,
    "assume_w2_wages": false,
    "idtl": null
  }'

# Response:
# { 
#   "csv": "taxsimid,year,state,fiitax,siitax,fica\n1,2023,44,8206.0,0.0,5738.0\n2,2023,6,...",
#   "rows_processed": 2
# }

# With warnings for unrecognized columns:
# { 
#   "csv": "...",
#   "rows_processed": 2,
#   "warnings": ["Unrecognized column(s): my_custom_col. These will be ignored."]
# }
```
```

--------------------------------

### POST /run/email

Source: https://context7.com/policyengine/policyengine-taxsim/llms.txt

Validates the CSV, runs the simulation, and emails the results as an attachment. Optionally subscribes the user to the PolicyEngine mailing list.

```APIDOC
## POST /run/email

### Description
Validates the CSV, runs the simulation, and emails the results as an attachment. Optionally subscribes the user to the PolicyEngine mailing list.

### Method
POST

### Endpoint
/run/email

### Parameters
#### Request Body
- **csv** (string) - Required - The CSV data for the simulation.
- **email** (string) - Required - The email address to send the results to.
- **filename** (string) - Optional - The desired filename for the results attachment.
- **disable_salt** (boolean) - Optional - Whether to disable salt.
- **assume_w2_wages** (boolean) - Optional - Whether to assume W2 wages.
- **idtl** (integer) - Optional - Value for idtl.
- **subscribe** (boolean) - Optional - Whether to subscribe the user to the mailing list.

### Request Example
```json
{
  "csv": "taxsimid,year,state,mstat,pwages,depx,page,sage,idtl\n1,2023,44,1,75000,0,35,0,0",
  "email": "researcher@university.edu",
  "filename": "my_cohort_2023.csv",
  "disable_salt": false,
  "assume_w2_wages": false,
  "idtl": 0,
  "subscribe": true
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.
- **csv** (string) - Optional - The processed CSV data (synchronous response).
- **rows_processed** (integer) - Optional - The number of rows processed (synchronous response).

#### Response Example
```json
{ "message": "Results will be emailed to researcher@university.edu when processing completes." }
```

#### Error Response (400)
- **detail** (string) - Error message describing the issue.

#### Error Example
```json
{ "detail": "Missing required column(s): year." }
```
```

--------------------------------

### Sample Data for Testing

Source: https://context7.com/policyengine/policyengine-taxsim/llms.txt

Extracts a reproducible random sample from a large dataset for quick testing purposes. Allows specifying the sample size and custom output paths.

```bash
# Sample 1000 records from a large CPS file
policyengine-taxsim sample-data cps_households.csv --sample 1000

# Auto-generated output: cps_households_sample_1000.csv

# Specify custom output path
policyengine-taxsim sample-data cps_households.csv \
  --sample 500 \
  --output sampled_500.csv

# Output: 500 randomly selected rows (random_state=42 for reproducibility)
```

--------------------------------

### Run TAXSIM Calculations

Source: https://github.com/policyengine/policyengine-taxsim/blob/main/README.md

Executes native TAXSIM-35 calculations for a given input file. Options include specifying the output file, sampling, and a custom path to the TAXSIM executable.

```bash
policyengine-taxsim taxsim your_input_file.csv
```

--------------------------------

### Sample Data for PolicyEngine-TAXSIM Comparison

Source: https://github.com/policyengine/policyengine-taxsim/blob/main/README.md

Extract a specified number of records from a large input CSV file for comparison. This is useful for reducing processing time and focusing on a subset of data.

```bash
policyengine-taxsim sample-data input.csv --sample 1000
```

--------------------------------

### Run Email Simulation via REST API

Source: https://context7.com/policyengine/policyengine-taxsim/llms.txt

Use this endpoint to validate a CSV, run a tax simulation, and email the results. Optionally subscribe the user to the mailing list. Ensure the 'Content-Type' header is set to 'application/json'.

```bash
curl -s -X POST http://localhost:8440/run/email \
  -H "Content-Type: application/json" \
  -d '{
    "csv": "taxsimid,year,state,mstat,pwages,depx,page,sage,idtl\n1,2023,44,1,75000,0,35,0,0",
    "email": "researcher@university.edu",
    "filename": "my_cohort_2023.csv",
    "disable_salt": false,
    "assume_w2_wages": false,
    "idtl": 0,
    "subscribe": true
  }'
```

```json
{ "message": "Results will be emailed to researcher@university.edu when processing completes." }
```

```json
{
  "message": "Results emailed to researcher@university.edu.",
  "csv": "...",
  "rows_processed": 1
}
```

```json
{ "detail": "Missing required column(s): year." }
```

```json
{ "detail": "Invalid email address." }
```

```json
{ "detail": "Column 'state' contains non-numeric values: ['California']." }
```

--------------------------------

### Generate PolicyEngine Household Situation from TAXSIM Variables

Source: https://context7.com/policyengine/policyengine-taxsim/llms.txt

Converts a dictionary of TAXSIM input variables into a PolicyEngine household situation dictionary. This dictionary is ready to be used directly with `policyengine_us.Simulation`.

```python
from policyengine_taxsim import generate_household

# Single filer with wages and dividends in California
taxsim_vars = {
    "taxsimid": 1,
    "year": 2023,
    "state": 6,       # California
    "mstat": 1,       # Single
    "page": 35,
    "pwages": 80000,
    "dividends": 5000,
    "ltcg": 3000,
    "depx": 0,
    "idtl": 0,
}

situation = generate_household(taxsim_vars)
# Returns a PolicyEngine situation dict:
# {
#   "people": {"you": {"age": {"2023": 35}, "employment_income": {"2023": 80000}, ...}},
#   "tax_units": {"your tax unit": {"members": ["you"], ...}},
#   "households": {"your household": {"state_name": {"2023": "CA"}, "members": ["you"]}},
#   ...
# }

# Use directly with PolicyEngine
from policyengine_us import Simulation
sim = Simulation(situation=situation)
federal_tax = sim.calculate("income_tax", period="2023")[0]
print(f"Federal income tax: ${federal_tax:,.2f}")
```

--------------------------------

### Generate Per-State Comparison Statistics

Source: https://context7.com/policyengine/policyengine-taxsim/llms.txt

Generates a dictionary summarizing household counts and mismatch rates per state for debugging. Useful for identifying states with low match rates.

```python
from policyengine_taxsim.comparison.statistics import ComparisonStatistics

stats = ComparisonStatistics(results, input_df)
breakdown = stats.state_breakdown()

# breakdown is a dict keyed by state code (e.g. "CA", "NY", "TX"):
# {
#   "CA": {
#     "state_fips": 6,
#     "total_households": 312,
#     "federal_mismatches": 14,
#     "state_mismatches": 27,
#     "federal_match_rate": 95.51,
#     "state_match_rate": 91.35,
#   },
#   "NY": { ... },
# }

for state, data in sorted(breakdown.items()):
    if data["state_match_rate"] < 90.0:
        print(f"{state}: state match rate {data['state_match_rate']:.1f}% "
              f"({data['state_mismatches']} mismatches / {data['total_households']} hh)")
```

--------------------------------

### Execute TaxSim command and capture output

Source: https://github.com/policyengine/policyengine-taxsim/blob/main/run-project.ipynb

Executes the defined command using subprocess.Popen, captures stdout and stderr, and stores stdout lines in the result list. Raises an exception if the command fails.

```python
process = subprocess.Popen(
    cmd, shell=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE
)

for output in process.stdout:
    result.append(output)

error_code = process.returncode

for line in result:
    print(line.strip())

if error_code is not None:
    raise Exception(f"cmd {cmd} failed, see above for details")
```

--------------------------------

### Generate PolicyEngine YAML Test File

Source: https://context7.com/policyengine/policyengine-taxsim/llms.txt

Generates a PolicyEngine YAML test file for regression testing. Set `logs=True` to actually write the file. This function requires household data, desired outputs, and a file name.

```python
from policyengine_taxsim import generate_household
from policyengine_taxsim.core.yaml_generator import generate_pe_tests_yaml

taxsim_vars = {
    "taxsimid": 7,
    "year": 2023,
    "state": 25,      # Massachusetts
    "mstat": 1,
    "page": 29,
    "pwages": 95000,
    "depx": 0,
    "idtl": 0,
}
situation = generate_household(taxsim_vars)

outputs = [
    {"variable": "ma_income_tax", "value": 4750.0},
    {"variable": "income_tax",    "value": 14625.0},
]

generate_pe_tests_yaml(
    household=situation,
    outputs=outputs,
    file_name="taxsim_record_7_2023.yaml",
    logs=True,   # Must be True to actually write the file
)
```

```yaml
- name: taxsim_record_7_2023.yaml
  absolute_error_margin: 2
  period: 2023
  input:
    people:
      person1:
        age: 29
        employment_income: 95000
        ssi: 0
        ...
    households:
      household:
        members: [person1]
        state_fips: 25
  output:
    ma_income_tax: 4750.0
```

--------------------------------

### Test PolicyEngine TAXSIM R Package

Source: https://github.com/policyengine/policyengine-taxsim/blob/main/r-package/README.md

Run package tests using devtools::test().

```r
devtools::test("r-package/policyenginetaxsim")
```

--------------------------------

### Python API: ComparisonStatistics.state_breakdown()

Source: https://context7.com/policyengine/policyengine-taxsim/llms.txt

Generates a per-state dictionary summarising household counts and mismatch rates for targeted debugging.

```APIDOC
## Python API: `ComparisonStatistics.state_breakdown()`

Generates a per-state dictionary summarising household counts and mismatch rates for targeted debugging.

```python
from policyengine_taxsim.comparison.statistics import ComparisonStatistics

stats = ComparisonStatistics(results, input_df)
breakdown = stats.state_breakdown()

# breakdown is a dict keyed by state code (e.g. "CA", "NY", "TX"):
# {
#   "CA": {
#     "state_fips": 6,
#     "total_households": 312,
#     "federal_mismatches": 14,
#     "state_mismatches": 27,
#     "federal_match_rate": 95.51,
#     "state_match_rate": 91.35,
#   },
#   "NY": { ... },
# }

for state, data in sorted(breakdown.items()):
    if data["state_match_rate"] < 90.0:
        print(f"{state}: state match rate {data['state_match_rate']:.1f}% "
              f"({data['state_mismatches']} mismatches / {data['total_households']} hh)")
```
```

--------------------------------

### generate_household(taxsim_vars)

Source: https://context7.com/policyengine/policyengine-taxsim/llms.txt

Converts a dictionary of TAXSIM input variables into a PolicyEngine household situation dictionary, ready for use with policyengine_us.Simulation.

```APIDOC
## Python API: `generate_household(taxsim_vars)`

Converts a dictionary of TAXSIM input variables into a PolicyEngine household situation dict, ready to be passed directly to `policyengine_us.Simulation`.

```python
from policyengine_taxsim import generate_household

# Single filer with wages and dividends in California
taxsim_vars = {
    "taxsimid": 1,
    "year": 2023,
    "state": 6,       # California
    "mstat": 1,       # Single
    "page": 35,
    "pwages": 80000,
    "dividends": 5000,
    "ltcg": 3000,
    "depx": 0,
    "idtl": 0,
}

situation = generate_household(taxsim_vars)
# Returns a PolicyEngine situation dict:
# {
#   "people": {"you": {"age": {"2023": 35}, "employment_income": {"2023": 80000}, ...}},
#   "tax_units": {"your tax unit": {"members": ["you"], ...}},
#   "households": {"your household": {"state_name": {"2023": "CA"}, "members": ["you"]}},
#   ...
# }

# Use directly with PolicyEngine
from policyengine_us import Simulation
sim = Simulation(situation=situation)
federal_tax = sim.calculate("income_tax", period="2023")[0]
print(f"Federal income tax: ${federal_tax:,.2f}")
```
```

--------------------------------

### Compare TAXSIM and PolicyEngine Results with Python API

Source: https://context7.com/policyengine/policyengine-taxsim/llms.txt

Compares two DataFrames of TAXSIM-formatted results using TaxComparator. Requires 'taxsimid', 'fiitax', and 'siitax' columns in input DataFrames. Configurable federal and state tolerances can be set.

```python
import pandas as pd
from policyengine_taxsim.comparison.comparator import TaxComparator, ComparisonConfig
from policyengine_taxsim.comparison.statistics import ComparisonStatistics

# Assume taxsim_df and pe_df are DataFrames with columns: taxsimid, fiitax, siitax
taxsim_df = pd.read_csv("taxsim_output_2023.csv")
pe_df     = pd.read_csv("policyengine_output_2023.csv")
input_df  = pd.read_csv("input_2023.csv")

config = ComparisonConfig(
    federal_tolerance=15.0,   # $15 tolerance
    state_tolerance=15.0,
)
comparator = TaxComparator(taxsim_df, pe_df, config)
results = comparator.compare()

# Print summary
stats = ComparisonStatistics(results, input_df)
stats.print_summary()
# Comparison Results (TAXSIM vs PolicyEngine):
# Total Records: 5000
# Federal Tax Matches: 4785 (95.70%)
# State Tax Matches:   4612 (92.24%)

# Print full report with state-by-state breakdown
print(stats.detailed_report())

# Save consolidated CSV (2 rows per household: taxsim row + policyengine row)
from pathlib import Path
results.save_consolidated_results(Path("output/"), input_df, year=2023)
# Writes: output/comparison_results_2023.csv
# Columns include: source, federal_match, state_match, overall_match, state_code, fiitax, siitax, ...
```

--------------------------------

### generate_pe_tests_yaml(household, outputs, file_name, logs)

Source: https://context7.com/policyengine/policyengine-taxsim/llms.txt

Generates a PolicyEngine YAML test file for a single household when `logs=True`. The YAML file can be used for regression testing and reproducing specific tax scenarios in PolicyEngine's test suite.

```APIDOC
## Python API: `generate_pe_tests_yaml(household, outputs, file_name, logs)`

### Description
Generates a PolicyEngine YAML test file for a single household when `logs=True`. The YAML file can be used for regression testing and reproducing specific tax scenarios in PolicyEngine's test suite.

### Parameters
- **household** (object) - Required - The household object generated by `generate_household`.
- **outputs** (list of dict) - Required - A list of dictionaries, where each dictionary specifies a variable and its expected value.
- **file_name** (string) - Required - The name of the YAML file to be generated.
- **logs** (boolean) - Required - If True, the YAML file will be written to disk. Defaults to False.

### Request Example
```python
from policyengine_taxsim import generate_household
from policyengine_taxsim.core.yaml_generator import generate_pe_tests_yaml

taxsim_vars = {
    "taxsimid": 7,
    "year": 2023,
    "state": 25,      # Massachusetts
    "mstat": 1,
    "page": 29,
    "pwages": 95000,
    "depx": 0,
    "idtl": 0,
}
situation = generate_household(taxsim_vars)

outputs = [
    {"variable": "ma_income_tax", "value": 4750.0},
    {"variable": "income_tax",    "value": 14625.0},
]

generate_pe_tests_yaml(
    household=situation,
    outputs=outputs,
    file_name="taxsim_record_7_2023.yaml",
    logs=True,   # Must be True to actually write the file
)
```

### Output
This function writes a YAML file to disk if `logs` is True. The content of the YAML file includes test case details, input variables, and expected outputs.
```

--------------------------------

### Run TAXSIM Simulation via REST API (Synchronous)

Source: https://context7.com/policyengine/policyengine-taxsim/llms.txt

Synchronous REST API endpoint to run a TAXSIM simulation. Accepts a TAXSIM CSV string and returns the output CSV in a JSON body. Useful for smaller datasets or immediate results.

```bash
# Local server
uvicorn policyengine_taxsim.api:local_app --port 8440

# POST /run — synchronous, returns full CSV in JSON body
curl -s -X POST http://localhost:8440/run \
  -H "Content-Type: application/json" \
  -d '{ 
    "csv": "taxsimid,year,state,mstat,pwages,depx,page,sage,idtl\n1,2023,44,1,75000,0,35,0,0\n2,2023,6,2,120000,0,42,40,2",
    "disable_salt": false,
    "assume_w2_wages": false,
    "idtl": null
  }'

# Response:
# { 
#   "csv": "taxsimid,year,state,fiitax,siitax,fica\n1,2023,44,8206.0,0.0,5738.0\n2,2023,6,...",
#   "rows_processed": 2
# }

# With warnings for unrecognized columns:
# { 
#   "csv": "...",
#   "rows_processed": 2,
#   "warnings": ["Unrecognized column(s): my_custom_col. These will be ignored."]
# }
```

--------------------------------

### Define TaxSim command

Source: https://github.com/policyengine/policyengine-taxsim/blob/main/run-project.ipynb

Defines the command string to execute the TaxSim CLI script with a specified input file.

```python
cmd = "python policyengine_taxsim/cli.py resources/taxsim35/taxsim_input.csv"
```

--------------------------------

### Document PolicyEngine TAXSIM R Package

Source: https://github.com/policyengine/policyengine-taxsim/blob/main/r-package/README.md

Regenerate package documentation after editing roxygen comments using devtools::document().

```r
devtools::document("r-package/policyenginetaxsim")
```

--------------------------------

### Import subprocess module

Source: https://github.com/policyengine/policyengine-taxsim/blob/main/run-project.ipynb

Imports the subprocess module to run external commands.

```python
import subprocess
```

--------------------------------

### Compare PolicyEngine Results with TAXSIM

Source: https://github.com/policyengine/policyengine-taxsim/blob/main/r-package/policyenginetaxsim/README.md

Compare the tax calculations from PolicyEngine with the embedded TAXSIM executable. This function returns a data frame with differences and match indicators.

```r
comparison <- compare_with_taxsim(my_data)
print(comparison)
#>   taxsimid year state fiitax_taxsim fiitax_pe fiitax_diff fiitax_match ...
#> 1        1 2023     5          4118      4118           0         TRUE ...

# Check match rates
mean(comparison$fiitax_match)  # Federal match rate
mean(comparison$siitax_match)  # State match rate

# Detailed summary
summary_comparison(comparison)
```

--------------------------------

### Calculate Taxes for Multiple Households

Source: https://github.com/policyengine/policyengine-taxsim/blob/main/r-package/policyenginetaxsim/README.md

Calculate taxes for multiple households simultaneously by providing vectors for state and wages. The output includes taxsimid for each household.

```r
households <- data.frame(
  year = 2023,
  state = c("CA", "TX", "NY"),
  mstat = 1,
  pwages = c(50000, 75000, 100000)
)

results <- policyengine_calculate_taxes(households)
print(results)
```

--------------------------------

### Calculate Taxes from CSV File

Source: https://github.com/policyengine/policyengine-taxsim/blob/main/r-package/policyenginetaxsim/README.md

Load tax unit data from a CSV file and calculate taxes. The results can then be saved to another CSV file.

```r
# Load data from CSV
my_data <- read.csv("tax_units.csv")

# Calculate taxes
results <- policyengine_calculate_taxes(my_data)

# Save results
write.csv(results, "tax_results.csv", row.names = FALSE)
```

--------------------------------

### Python API: TaxComparator and ComparisonResults

Source: https://context7.com/policyengine/policyengine-taxsim/llms.txt

Compares two DataFrames of TAXSIM-formatted results and returns a ComparisonResults object with match rates, mismatch records, and consolidated CSV export.

```APIDOC
## Python API: `TaxComparator` and `ComparisonResults`

Compares two DataFrames of TAXSIM-formatted results (e.g., one from TAXSIM-35 and one from PolicyEngine) and returns a `ComparisonResults` object with match rates, mismatch records, and consolidated CSV export.

```python
import pandas as pd
from policyengine_taxsim.comparison.comparator import TaxComparator, ComparisonConfig
from policyengine_taxsim.comparison.statistics import ComparisonStatistics

# Assume taxsim_df and pe_df are DataFrames with columns: taxsimid, fiitax, siitax
taxsim_df = pd.read_csv("taxsim_output_2023.csv")
pe_df     = pd.read_csv("policyengine_output_2023.csv")
input_df  = pd.read_csv("input_2023.csv")

config = ComparisonConfig(
    federal_tolerance=15.0,   # $15 tolerance
    state_tolerance=15.0,
)
comparator = TaxComparator(taxsim_df, pe_df, config)
results = comparator.compare()

# Print summary
stats = ComparisonStatistics(results, input_df)
stats.print_summary()
# Comparison Results (TAXSIM vs PolicyEngine):
# Total Records: 5000
# Federal Tax Matches: 4785 (95.70%)
# State Tax Matches:   4612 (92.24%)

# Print full report with state-by-state breakdown
print(stats.detailed_report())

# Save consolidated CSV (2 rows per household: taxsim row + policyengine row)
from pathlib import Path
results.save_consolidated_results(Path("output/"), input_df, year=2023)
# Writes: output/comparison_results_2023.csv
# Columns include: source, federal_match, state_match, overall_match, state_code, fiitax, siitax, ...
```
```

--------------------------------

### Check PolicyEngine TAXSIM R Package

Source: https://github.com/policyengine/policyengine-taxsim/blob/main/r-package/README.md

Check package integrity and compliance using devtools::check().

```r
devtools::check("r-package/policyenginetaxsim")
```

--------------------------------

### REST API: POST /run/stream

Source: https://context7.com/policyengine/policyengine-taxsim/llms.txt

Server-Sent Events endpoint that streams per-chunk progress messages followed by the final result. Ideal for large datasets and browser-based integrations.

```APIDOC
## REST API: `POST /run/stream`

Server-Sent Events endpoint that streams per-chunk progress messages followed by the final result. Ideal for large datasets and browser-based integrations.

```javascript
// Browser / Node.js EventSource example
const response = await fetch("http://localhost:8440/run/stream", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    csv: csvText,         // full TAXSIM CSV string
    disable_salt: false,
    idtl: 2,
  }),
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  const lines = decoder.decode(value).split("\n");
  for (const line of lines) {
    if (!line.startsWith("data: ")) continue;
    const msg = JSON.parse(line.slice(6));
    if (msg.type === "progress") {
      console.log(`Progress: ${msg.rows_done}/${msg.total_rows} rows`);
      // msg: { type: "progress", chunks_done: 1, total_chunks: 5, rows_done: 10000, total_rows: 48000 }
    } else if (msg.type === "result") {
      console.log("Done! CSV length:", msg.csv.length);
      console.log("Rows processed:", msg.rows_processed);
      // msg: { type: "result", csv: "...", rows_processed: 48000 }
    } else if (msg.type === "error") {
      console.error("Error:", msg.error);
    }
  }
}
```
```

--------------------------------

### Stream TAXSIM Simulation Results via REST API (SSE)

Source: https://context7.com/policyengine/policyengine-taxsim/llms.txt

Server-Sent Events (SSE) endpoint for streaming TAXSIM simulation results. Ideal for large datasets and browser-based integrations, providing progress updates and final results.

```javascript
// Browser / Node.js EventSource example
const response = await fetch("http://localhost:8440/run/stream", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    csv: csvText,         // full TAXSIM CSV string
    disable_salt: false,
    idtl: 2,
  }),
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  const lines = decoder.decode(value).split("\n");
  for (const line of lines) {
    if (!line.startsWith("data: ")) continue;
    const msg = JSON.parse(line.slice(6));
    if (msg.type === "progress") {
      console.log(`Progress: ${msg.rows_done}/${msg.total_rows} rows`);
      // msg: { type: "progress", chunks_done: 1, total_chunks: 5, rows_done: 10000, total_rows: 48000 }
    } else if (msg.type === "result") {
      console.log("Done! CSV length:", msg.csv.length);
      console.log("Rows processed:", msg.rows_processed);
      // msg: { type: "result", csv: "...", rows_processed: 48000 }
    } else if (msg.type === "error") {
      console.error("Error:", msg.error);
    }
  }
}
```

--------------------------------

### PolicyEngineRunner for Direct PolicyEngine Microsimulation

Source: https://context7.com/policyengine/policyengine-taxsim/llms.txt

Direct runner for PolicyEngine microsimulation (years 2021+). Processes records in chunks of 10,000 using PolicyEngine's vectorized engine. Supports an `on_progress` callback for streaming progress updates.

```python
import pandas as pd
from policyengine_taxsim.runners.policyengine_runner import PolicyEngineRunner

df = pd.DataFrame([
    {"taxsimid": i, "year": 2023, "state": 44, "mstat": 1,
     "pwages": 50000 + i * 1000, "depx": 0, "page": 35, "sage": 0, "idtl": 2}
    for i in range(1, 501)   # 500 records
])

def progress_callback(chunks_done, total_chunks, rows_done, total_rows):
    print(f"Progress: {rows_done}/{total_rows} rows ({chunks_done}/{total_chunks} chunks)")

runner = PolicyEngineRunner(
    df,
    logs=False,
    disable_salt=False,
    assume_w2_wages=False,
)
results = runner.run(show_progress=True, on_progress=progress_callback)
```

--------------------------------

### PolicyEngineRunner

Source: https://context7.com/policyengine/policyengine-taxsim/llms.txt

A direct runner for PolicyEngine microsimulation (years 2021+). It processes records in chunks of 10,000 using PolicyEngine's vectorized engine and supports an `on_progress` callback for streaming progress updates.

```APIDOC
## Python API: `PolicyEngineRunner`

Direct runner for PolicyEngine microsimulation (years 2021+). Processes records in chunks of 10,000 using PolicyEngine's vectorized engine. Supports an `on_progress` callback for streaming progress updates.

```python
import pandas as pd
from policyengine_taxsim.runners.policyengine_runner import PolicyEngineRunner

df = pd.DataFrame([
    {"taxsimid": i, "year": 2023, "state": 44, "mstat": 1,
     "pwages": 50000 + i * 1000, "depx": 0, "page": 35, "sage": 0, "idtl": 2}
    for i in range(1, 501)   # 500 records
])

def progress_callback(chunks_done, total_chunks, rows_done, total_rows):
    print(f"Progress: {rows_done}/{total_rows} rows ({chunks_done}/{total_chunks} chunks)")

runner = PolicyEngineRunner(
    df,
    logs=False,
    disable_salt=False,
    assume_w2_wages=False,
)
results = runner.run(show_progress=True, on_progress=progress_callback)

```

--------------------------------

### Print Mean Federal and State Tax

Source: https://context7.com/policyengine/policyengine-taxsim/llms.txt

Calculates and prints the mean federal and state tax from a results DataFrame. Assumes the DataFrame contains 'fiitax' and 'siitax' columns.

```python
print(f"Mean federal tax: ${results['fiitax'].mean():,.2f}")
print(f"Mean state tax:   ${results['siitax'].mean():,.2f}")
```

--------------------------------

### Calculate Taxes for Single Filer

Source: https://github.com/policyengine/policyengine-taxsim/blob/main/r-package/policyenginetaxsim/README.md

Calculate federal and state income taxes for a single filer with specified wages and state. Requires the 'policyenginetaxsim' library to be loaded.

```r
library(policyenginetaxsim)

# Single filer with $50,000 wages in California
my_data <- data.frame(
  year = 2023,
  state = "CA",
  mstat = 1,
  pwages = 50000
)

results <- policyengine_calculate_taxes(my_data)
print(results)
```