# NZ Personal Tax Microsimulation Model
[](https://github.com/edithatogo/nztaxmicrosim/actions/workflows/ci.yml)
[](https://codecov.io/gh/edithatogo/nztaxmicrosim)
[](https://badge.fury.io/py/nztaxmicrosim)
[](https://pypi.org/project/nztaxmicrosim)
[](https://opensource.org/licenses/Apache-2.0)
A microsimulation model for New Zealand's tax and benefit system.
This model is designed to be a flexible and extensible tool for researchers, policymakers, and the public to explore the impacts of different tax and benefit policies in New Zealand.
The filename of this document is capitalised as `README.md` so that GitHub
renders it by default when viewing the repository.
## Key Features
For a more detailed breakdown of all features, see [FEATURES.md](FEATURES.md).
- **Comprehensive Rule Coverage:**
- **Income Tax:** Full progressive income tax brackets.
- **Levies:** ACC Earner's Levy.
- **Tax Credits:** Independent Earner Tax Credit (IETC).
- **Working for Families:** Family Tax Credit (FTC), In-Work Tax Credit (IWTC), Best Start Tax Credit (BSTC), and Minimum Family Tax Credit (MFTC).
- **Main Benefits:** Jobseeker Support (JSS), Sole Parent Support (SPS), and Supported Living Payment (SLP).
- **Other Assistance:** Accommodation Supplement, Winter Energy Payment, and NZ Superannuation.
- **Deductions:** KiwiSaver and Student Loan repayments.
- **Extensive Historical Data:**
- Parameterised policy rules for tax years from 2005 to 2025.
- Automatic fallback to historical data, with coverage from 1890 to 2028.
- **Synthetic Population Generation:**
- Includes the `syspop` tool to generate realistic synthetic populations for simulation.
- **Flexible Simulation Modes:**
- Supports both **static** (single-year) and **dynamic** (multi-year) simulations.
- Extensible framework for modeling behavioural responses over time.
- **Modular and Extensible:**
- A modular plug-in simulation pipeline where tax and benefit rules can be
independently enabled, ordered or substituted.
- **Advanced Analysis Tools:**
- Reporting utilities and sensitivity analysis, including Expected Value of
Perfect Information (EVPI).
### Feature Matrix
For a detailed comparison of this project with other microsimulation models, see the [Feature Comparison](docs/feature_comparison.md).
For a list of the current features and their release status, see the [Module Status](docs/module_status.md).
## Quick Start
### Installation
Install the core dependencies:
```bash
pip install .
```
For development work:
```bash
make install-dev-deps
```
### Running an Example
To run the basic usage example:
```bash
make run-example
```
This will execute the `examples/basic_usage.py` script and write the output to `basic_usage_output.txt`.
Here is a simplified example of how to use the library:
```python
from src.microsim import load_parameters, taxit
# Load parameters for a specific tax year
params = load_parameters("2024-2025")
# Calculate income tax for an individual
income = 50000
tax = taxit(income, params.tax_brackets)
print(f"Income tax for an income of ${income}: ${tax:.2f}")
```
## Project Structure
- `src/` – core Python source code and parameter files
- `examples/` – scripts demonstrating how to use the model
- `docs/` – detailed documentation, licences and contribution guides
- `tests/` – unit tests
- `syspop/` – synthetic population generator
- `scripts/` – utility scripts
- `conf/` and `config/` – configuration files
- `reports/` – output from reporting scripts
- `Makefile` – common development tasks
- `pyproject.toml` – dependency and tooling configuration
## Development
For more detailed development guidelines, see [DEVELOPMENT.md](docs/DEVELOPMENT.md).
### Tests
Install development dependencies:
```bash
make install-dev-deps
```
Run the test suite with [tox](https://tox.wiki/):
```bash
tox
```
### Linting, Type Checking and Security
Run formatting, linting, static type checks and security scans with
[pre-commit](https://pre-commit.com/):
```bash
pre-commit run --all-files
```
Install pre-commit hooks with `pre-commit install` to run these checks
automatically.
## Parameters
Policy parameters are stored in a SQLite database (`src/data/parameters.db`).
The database provides a structured and efficient way to manage historical and
future policy settings.
Parameters are loaded into Pydantic models via the `load_parameters` function,
which queries the database for the specified year. This ensures that all data is
validated and type-checked at runtime.
For details on the database schema and Pydantic models, see `src/parameters.py`.
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for a history of changes.
## Security
See our security policy in [docs/SECURITY.md](docs/SECURITY.md).
## Contributing
Contributions are welcome! See
[docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for guidelines.
## License
Licensed under the Apache 2.0 License – see [docs/LICENSE](docs/LICENSE).
## Cite Us
If you use this software in your research, cite the project as described in
[docs/CITATION.cff](docs/CITATION.cff).
## Roadmap
The project is in a mature state, with most of the core features completed. The current focus is on improving the model's flexibility, optimization capabilities, and architecture.
### In Progress
- **Policy Optimisation Module:** Integrating an optimization library (e.g., Optuna) to intelligently search for optimal policy parameters.
- **Configuration-Driven Pipelines:** Refactoring the simulation to be driven by configuration files (e.g., YAML) to make it more flexible.
### Completed
- **Parameter Database:** Policy parameters have been migrated from JSON files to a SQLite database, providing more robust data management.
- **Web API:** The simulation engine is now accessible via a web API, making it easier to integrate with other applications.
### Future Plans
- **Enhanced CI/CD:** Improving the CI/CD pipeline with dynamic badges, automated data audits, and performance regression testing.
For more details, see the full [Roadmap](docs/ROADMAP.md).
Raw data
{
"_id": null,
"home_page": null,
"name": "nztaxmicrosim",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "NZ Tax Microsimulation Team <contact@nztaxmicrosim.org>",
"keywords": "taxation, microsimulation, new-zealand, policy-analysis, economics",
"author": null,
"author_email": "NZ Tax Microsimulation Team <contact@nztaxmicrosim.org>",
"download_url": "https://files.pythonhosted.org/packages/d3/a0/deec3733d41b72ba90b88543f8b967cf02db82d5533bfee0a5b1aafd476e/nztaxmicrosim-0.3.0.tar.gz",
"platform": null,
"description": "# NZ Personal Tax Microsimulation Model\n\n[](https://github.com/edithatogo/nztaxmicrosim/actions/workflows/ci.yml)\n[](https://codecov.io/gh/edithatogo/nztaxmicrosim)\n[](https://badge.fury.io/py/nztaxmicrosim)\n[](https://pypi.org/project/nztaxmicrosim)\n[](https://opensource.org/licenses/Apache-2.0)\n\nA microsimulation model for New Zealand's tax and benefit system.\n\nThis model is designed to be a flexible and extensible tool for researchers, policymakers, and the public to explore the impacts of different tax and benefit policies in New Zealand.\n\nThe filename of this document is capitalised as `README.md` so that GitHub\nrenders it by default when viewing the repository.\n\n## Key Features\n\nFor a more detailed breakdown of all features, see [FEATURES.md](FEATURES.md).\n\n- **Comprehensive Rule Coverage:**\n - **Income Tax:** Full progressive income tax brackets.\n - **Levies:** ACC Earner's Levy.\n - **Tax Credits:** Independent Earner Tax Credit (IETC).\n - **Working for Families:** Family Tax Credit (FTC), In-Work Tax Credit (IWTC), Best Start Tax Credit (BSTC), and Minimum Family Tax Credit (MFTC).\n - **Main Benefits:** Jobseeker Support (JSS), Sole Parent Support (SPS), and Supported Living Payment (SLP).\n - **Other Assistance:** Accommodation Supplement, Winter Energy Payment, and NZ Superannuation.\n - **Deductions:** KiwiSaver and Student Loan repayments.\n- **Extensive Historical Data:**\n - Parameterised policy rules for tax years from 2005 to 2025.\n - Automatic fallback to historical data, with coverage from 1890 to 2028.\n- **Synthetic Population Generation:**\n - Includes the `syspop` tool to generate realistic synthetic populations for simulation.\n- **Flexible Simulation Modes:**\n - Supports both **static** (single-year) and **dynamic** (multi-year) simulations.\n - Extensible framework for modeling behavioural responses over time.\n- **Modular and Extensible:**\n - A modular plug-in simulation pipeline where tax and benefit rules can be\n independently enabled, ordered or substituted.\n- **Advanced Analysis Tools:**\n - Reporting utilities and sensitivity analysis, including Expected Value of\n Perfect Information (EVPI).\n\n### Feature Matrix\n\nFor a detailed comparison of this project with other microsimulation models, see the [Feature Comparison](docs/feature_comparison.md).\n\nFor a list of the current features and their release status, see the [Module Status](docs/module_status.md).\n\n\n## Quick Start\n\n### Installation\n\nInstall the core dependencies:\n\n```bash\npip install .\n```\n\nFor development work:\n\n```bash\nmake install-dev-deps\n```\n\n### Running an Example\n\nTo run the basic usage example:\n\n```bash\nmake run-example\n```\n\nThis will execute the `examples/basic_usage.py` script and write the output to `basic_usage_output.txt`.\n\nHere is a simplified example of how to use the library:\n\n```python\nfrom src.microsim import load_parameters, taxit\n\n# Load parameters for a specific tax year\nparams = load_parameters(\"2024-2025\")\n\n# Calculate income tax for an individual\nincome = 50000\ntax = taxit(income, params.tax_brackets)\n\nprint(f\"Income tax for an income of ${income}: ${tax:.2f}\")\n```\n\n## Project Structure\n\n- `src/` \u2013 core Python source code and parameter files\n- `examples/` \u2013 scripts demonstrating how to use the model\n- `docs/` \u2013 detailed documentation, licences and contribution guides\n- `tests/` \u2013 unit tests\n- `syspop/` \u2013 synthetic population generator\n- `scripts/` \u2013 utility scripts\n- `conf/` and `config/` \u2013 configuration files\n- `reports/` \u2013 output from reporting scripts\n- `Makefile` \u2013 common development tasks\n- `pyproject.toml` \u2013 dependency and tooling configuration\n\n## Development\n\nFor more detailed development guidelines, see [DEVELOPMENT.md](docs/DEVELOPMENT.md).\n\n### Tests\n\nInstall development dependencies:\n\n```bash\nmake install-dev-deps\n```\n\nRun the test suite with [tox](https://tox.wiki/):\n\n```bash\ntox\n```\n\n### Linting, Type Checking and Security\n\nRun formatting, linting, static type checks and security scans with\n[pre-commit](https://pre-commit.com/):\n\n```bash\npre-commit run --all-files\n```\n\nInstall pre-commit hooks with `pre-commit install` to run these checks\nautomatically.\n\n## Parameters\n\nPolicy parameters are stored in a SQLite database (`src/data/parameters.db`).\nThe database provides a structured and efficient way to manage historical and\nfuture policy settings.\n\nParameters are loaded into Pydantic models via the `load_parameters` function,\nwhich queries the database for the specified year. This ensures that all data is\nvalidated and type-checked at runtime.\n\nFor details on the database schema and Pydantic models, see `src/parameters.py`.\n\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for a history of changes.\n\n## Security\n\nSee our security policy in [docs/SECURITY.md](docs/SECURITY.md).\n\n## Contributing\n\nContributions are welcome! See\n[docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for guidelines.\n\n## License\n\nLicensed under the Apache 2.0 License \u2013 see [docs/LICENSE](docs/LICENSE).\n\n## Cite Us\n\nIf you use this software in your research, cite the project as described in\n[docs/CITATION.cff](docs/CITATION.cff).\n\n## Roadmap\n\nThe project is in a mature state, with most of the core features completed. The current focus is on improving the model's flexibility, optimization capabilities, and architecture.\n\n### In Progress\n\n- **Policy Optimisation Module:** Integrating an optimization library (e.g., Optuna) to intelligently search for optimal policy parameters.\n- **Configuration-Driven Pipelines:** Refactoring the simulation to be driven by configuration files (e.g., YAML) to make it more flexible.\n\n### Completed\n\n- **Parameter Database:** Policy parameters have been migrated from JSON files to a SQLite database, providing more robust data management.\n- **Web API:** The simulation engine is now accessible via a web API, making it easier to integrate with other applications.\n\n### Future Plans\n\n- **Enhanced CI/CD:** Improving the CI/CD pipeline with dynamic badges, automated data audits, and performance regression testing.\n\nFor more details, see the full [Roadmap](docs/ROADMAP.md).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python-based microsimulation model for the New Zealand tax and transfer system.",
"version": "0.3.0",
"project_urls": {
"Bug Tracker": "https://github.com/Treasury-AnZ/nztaxmicrosim/issues",
"Changelog": "https://github.com/Treasury-AnZ/nztaxmicrosim/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/Treasury-AnZ/nztaxmicrosim/blob/main/README.md",
"Homepage": "https://github.com/Treasury-AnZ/nztaxmicrosim",
"Repository": "https://github.com/Treasury-AnZ/nztaxmicrosim"
},
"split_keywords": [
"taxation",
" microsimulation",
" new-zealand",
" policy-analysis",
" economics"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "969e861f3c1224fa4fc4e2b38243a21a1991d9ff30d90ae731c43cfc3957d904",
"md5": "cdc18125d54df806d0cf894ac0a69818",
"sha256": "b67c9a16f138f5403eda72405a1401c34912bd8ff4d88092781bf88935b2db30"
},
"downloads": -1,
"filename": "nztaxmicrosim-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cdc18125d54df806d0cf894ac0a69818",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 133600,
"upload_time": "2025-08-29T10:20:14",
"upload_time_iso_8601": "2025-08-29T10:20:14.967388Z",
"url": "https://files.pythonhosted.org/packages/96/9e/861f3c1224fa4fc4e2b38243a21a1991d9ff30d90ae731c43cfc3957d904/nztaxmicrosim-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d3a0deec3733d41b72ba90b88543f8b967cf02db82d5533bfee0a5b1aafd476e",
"md5": "eacc81ee62b008bea4f1b70c822e2a00",
"sha256": "8f5da100d9f4cf0acb1018d4744039c87abdce184871bc35e995d03fac5046eb"
},
"downloads": -1,
"filename": "nztaxmicrosim-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "eacc81ee62b008bea4f1b70c822e2a00",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 147399,
"upload_time": "2025-08-29T10:20:17",
"upload_time_iso_8601": "2025-08-29T10:20:17.470876Z",
"url": "https://files.pythonhosted.org/packages/d3/a0/deec3733d41b72ba90b88543f8b967cf02db82d5533bfee0a5b1aafd476e/nztaxmicrosim-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-29 10:20:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Treasury-AnZ",
"github_project": "nztaxmicrosim",
"github_not_found": true,
"lcname": "nztaxmicrosim"
}
JSON
