nztaxmicrosim 0.3.1

A Python-based microsimulation model for the New Zealand tax and transfer system.

NZ Personal Tax Microsimulation Model

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.

• 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.

For a list of the current features and their release status, see the Module Status.

Quick Start

Installation

Install the core dependencies:

pip install .

For development work:

make install-dev-deps

Running an Example

To run the basic usage example:

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:

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.

Tests

Install development dependencies:

make install-dev-deps

Run the test suite with tox:

tox

Linting, Type Checking and Security

Run formatting, linting, static type checks and security scans with pre-commit:

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 for a history of changes.

Security

See our security policy in docs/SECURITY.md.

Contributing

Contributions are welcome! See docs/CONTRIBUTING.md for guidelines.

License

Licensed under the Apache 2.0 License – see docs/LICENSE.

Cite Us

If you use this software in your research, cite the project as described in 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.