microunit 0.1.0__tar.gz

microunit-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+dist/
+build/
+*.egg-info/
+.coverage
+coverage.xml
+htmlcov/

microunit-0.1.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+<!-- towncrier release notes start -->
+
+## [0.1.0] - 2026-05-30
+
+### Added
+
+- Initial release. Rules-based tax-unit construction engine (`construct_tax_units`, `policyengine` and `census_documented` modes) extracted from policyengine-us-data, conservative SPM/SNAP/Medicaid-MAGI unit adapters, partition primitives (`UnitPartition`, `EgoUnitMembership`), and partition-match diagnostics.

microunit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PolicyEngine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

microunit-0.1.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: microunit
+Version: 0.1.0
+Summary: Policy unit assignment for PolicyEngine's microdata stack
+Project-URL: Repository, https://github.com/PolicyEngine/microunit
+Author-email: PolicyEngine <hello@policyengine.org>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: microdata,microplex,policy-simulation,spm,tax-units,unit-assignment
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Requires-Dist: towncrier>=24.8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# microunit
+
+`microunit` is PolicyEngine's unit-assignment package for microdata.
+
+It is part of the PolicyEngine microdata stack:
+
+- `microimpute`: fill missing variables and transfer attributes across data
+  sources.
+- `microcalibrate`, eventually maybe `microweight`: align microdata to external
+  targets.
+- `microunit`: construct policy units from person and relationship records.
+- `microplex`: synthesize, rebuild, and evaluate full microdata systems.
+
+It separates "who belongs with whom" from benefit and tax formulas. The same
+person table can have several policy units layered on top of it:
+
+- SPM units for poverty measurement.
+- Tax units for filing and dependency rules.
+- SNAP units for food assistance eligibility.
+- Medicaid MAGI households, which are usually focal-person units rather than a
+  single partition of the household.
+
+The package starts with the common primitives those systems need:
+
+- `UnitPartition`: one unit ID per person, useful for SPM, tax, and many SNAP
+  assignment outputs.
+- `EgoUnitMembership`: one membership set per focal person, useful for MAGI-like
+  rules where units can overlap.
+- SPM simplification adapters for programs whose true unit rules are not yet
+  implemented.
+- Diagnostics for comparing partitions within households.
+- Conservative adapters that preserve existing unit IDs from source data.
+
+## Install
+
+```bash
+uv pip install -e ".[dev]"
+```
+
+## Example
+
+```python
+import pandas as pd
+from microunit.units import assign_spm_partition
+
+persons = pd.DataFrame(
+    {
+        "person_id": [1, 2, 3],
+        "household_id": [10, 10, 10],
+        "family_id": [100, 100, 101],
+    }
+)
+
+partition = assign_spm_partition(persons)
+print(partition.to_frame())
+```
+
+## Rules-based tax-unit construction
+
+`microunit` includes the rules-based tax-unit / filing-status construction
+engine extracted from
+[`policyengine-us-data`](https://github.com/PolicyEngine/policyengine-us-data).
+It applies federal filing and dependency rules to assign people into tax
+units, infer each person's role (head / spouse / dependent), and infer a
+filing status per unit. It is the same engine reused across the CPS and ACS
+pipelines there, and is **source-agnostic**: it operates on
+already-normalized, CPS-like person frames. It is consumed by
+`policyengine-us-data` and `microplex-us`.
+
+```python
+import pandas as pd
+from microunit import construct_tax_units
+
+# person uses CPS-like column names (see "Input contract" below).
+person_assignments, tax_unit = construct_tax_units(person, year=2024)
+```
+
+`construct_tax_units(person, year, mode="policyengine")` returns:
+
+- **`person_assignments`** (indexed like the input): `TAX_ID` (`int64`,
+  dense 1-based id), `tax_unit_role_input` (bytes: `HEAD` / `SPOUSE` /
+  `DEPENDENT`), `is_related_to_head_or_spouse` (bool).
+- **`tax_unit`** (one row per `TAX_ID`): `filing_status_input` (bytes:
+  `JOINT` / `HEAD_OF_HOUSEHOLD` / `SURVIVING_SPOUSE` / `SEPARATE` /
+  `SINGLE`).
+
+The string columns are byte strings (the HDF5-friendly encoding used by the
+source pipeline); decode with `.decode()`.
+
+A `UnitPartition` adapter is also provided:
+
+```python
+from microunit.units import construct_tax_partition
+
+partition = construct_tax_partition(person, year=2024)  # UnitPartition(unit_type="tax")
+```
+
+### Modes
+
+- **`"policyengine"`** (default, `microunit.POLICYENGINE_MODE`): PolicyEngine's
+  dependency/filing-rule flow.
+- **`"census_documented"`** (`microunit.CENSUS_DOCUMENTED_MODE`): the publicly
+  documented Census tax-model flow.
+
+### Input contract
+
+Required CPS columns (raises `KeyError` if missing): `PH_SEQ`, `A_LINENO`,
+`A_AGE`, `A_MARITL`, `A_SPOUSE`, `PEPAR1`, `PEPAR2`, `A_EXPRRP`.
+
+Optional evidence columns (used when present, safely defaulted otherwise):
+income components (`WSAL_VAL`, `SEMP_VAL`, `FRSE_VAL`, `INT_VAL`, `DIV_VAL`,
+`RNT_VAL`, `CAP_VAL`, `UC_VAL`, `OI_VAL`, `ANN_VAL`, `PNSN_VAL`, `SS_VAL`),
+total money income (`PTOTVAL`), enrollment (`A_ENRLW`, `A_FTPT`, `A_HSCOL`),
+and disability flags (`PEDISDRS`, `PEDISEAR`, `PEDISEYE`, `PEDISOUT`,
+`PEDISPHY`, `PEDISREM`). Relationship codes follow the CPS ASEC `A_EXPRRP`
+recode, exposed as `microunit.CPSRelationshipCode`.
+
+### ACS column mapping is the consumer's responsibility
+
+The ACS PUMS -> CPS column mapping (`acs_to_cps_columns.py` in
+`policyengine-us-data`) is **not** part of `microunit`. That ~500-line module
+is ACS-PUMS-specific (`RELSHIPP`/`RELP` translation, marital-status recoding,
+and heuristic spouse/parent-pointer inference, since ACS provides no universal
+spouse or parent pointers) and belongs with the ACS reader. Consumers reading
+ACS should map their PUMS columns onto the CPS-like contract above and then
+call `construct_tax_units`. Accordingly, the ACS-specific tests from
+`policyengine-us-data` remain there; the full CPS construction test suite is
+ported here.
+
+### Packaged data
+
+The qualifying-relative gross income limit (the personal/dependent exemption
+amount under IRC 151(d), used by the IRC 152(d)(1)(B) gross income test) ships
+as package data at `microunit/data/dependent_gross_income_limit.yaml` and is
+loaded via `importlib.resources`, so the engine does not depend on
+`policyengine-us` being installed.
+
+## Scope
+
+This package should construct unit assignments and explain them. It should not
+calculate benefits, taxes, or eligibility amounts. Policy engines remain
+responsible for program formulas.
+
+Near-term roadmap:
+
+1. Move reusable SPM unit assignment out of `spm-calculator`.
+2. Move reusable tax-unit construction out of `policyengine-us-data` /
+   `policyengine-us`. (Done -- see "Rules-based tax-unit construction" above.)
+3. Add CPS and ACS source adapters for Microplex.
+4. Use SPM units as the temporary simplification for SNAP, Medicaid/MAGI, and
+   other program units.
+5. Replace those simplifications with real program rules once Microplex has a
+   stable end-to-end unit pipeline.

microunit-0.1.0/README.md

@@ -0,0 +1,153 @@
+# microunit
+
+`microunit` is PolicyEngine's unit-assignment package for microdata.
+
+It is part of the PolicyEngine microdata stack:
+
+- `microimpute`: fill missing variables and transfer attributes across data
+  sources.
+- `microcalibrate`, eventually maybe `microweight`: align microdata to external
+  targets.
+- `microunit`: construct policy units from person and relationship records.
+- `microplex`: synthesize, rebuild, and evaluate full microdata systems.
+
+It separates "who belongs with whom" from benefit and tax formulas. The same
+person table can have several policy units layered on top of it:
+
+- SPM units for poverty measurement.
+- Tax units for filing and dependency rules.
+- SNAP units for food assistance eligibility.
+- Medicaid MAGI households, which are usually focal-person units rather than a
+  single partition of the household.
+
+The package starts with the common primitives those systems need:
+
+- `UnitPartition`: one unit ID per person, useful for SPM, tax, and many SNAP
+  assignment outputs.
+- `EgoUnitMembership`: one membership set per focal person, useful for MAGI-like
+  rules where units can overlap.
+- SPM simplification adapters for programs whose true unit rules are not yet
+  implemented.
+- Diagnostics for comparing partitions within households.
+- Conservative adapters that preserve existing unit IDs from source data.
+
+## Install
+
+```bash
+uv pip install -e ".[dev]"
+```
+
+## Example
+
+```python
+import pandas as pd
+from microunit.units import assign_spm_partition
+
+persons = pd.DataFrame(
+    {
+        "person_id": [1, 2, 3],
+        "household_id": [10, 10, 10],
+        "family_id": [100, 100, 101],
+    }
+)
+
+partition = assign_spm_partition(persons)
+print(partition.to_frame())
+```
+
+## Rules-based tax-unit construction
+
+`microunit` includes the rules-based tax-unit / filing-status construction
+engine extracted from
+[`policyengine-us-data`](https://github.com/PolicyEngine/policyengine-us-data).
+It applies federal filing and dependency rules to assign people into tax
+units, infer each person's role (head / spouse / dependent), and infer a
+filing status per unit. It is the same engine reused across the CPS and ACS
+pipelines there, and is **source-agnostic**: it operates on
+already-normalized, CPS-like person frames. It is consumed by
+`policyengine-us-data` and `microplex-us`.
+
+```python
+import pandas as pd
+from microunit import construct_tax_units
+
+# person uses CPS-like column names (see "Input contract" below).
+person_assignments, tax_unit = construct_tax_units(person, year=2024)
+```
+
+`construct_tax_units(person, year, mode="policyengine")` returns:
+
+- **`person_assignments`** (indexed like the input): `TAX_ID` (`int64`,
+  dense 1-based id), `tax_unit_role_input` (bytes: `HEAD` / `SPOUSE` /
+  `DEPENDENT`), `is_related_to_head_or_spouse` (bool).
+- **`tax_unit`** (one row per `TAX_ID`): `filing_status_input` (bytes:
+  `JOINT` / `HEAD_OF_HOUSEHOLD` / `SURVIVING_SPOUSE` / `SEPARATE` /
+  `SINGLE`).
+
+The string columns are byte strings (the HDF5-friendly encoding used by the
+source pipeline); decode with `.decode()`.
+
+A `UnitPartition` adapter is also provided:
+
+```python
+from microunit.units import construct_tax_partition
+
+partition = construct_tax_partition(person, year=2024)  # UnitPartition(unit_type="tax")
+```
+
+### Modes
+
+- **`"policyengine"`** (default, `microunit.POLICYENGINE_MODE`): PolicyEngine's
+  dependency/filing-rule flow.
+- **`"census_documented"`** (`microunit.CENSUS_DOCUMENTED_MODE`): the publicly
+  documented Census tax-model flow.
+
+### Input contract
+
+Required CPS columns (raises `KeyError` if missing): `PH_SEQ`, `A_LINENO`,
+`A_AGE`, `A_MARITL`, `A_SPOUSE`, `PEPAR1`, `PEPAR2`, `A_EXPRRP`.
+
+Optional evidence columns (used when present, safely defaulted otherwise):
+income components (`WSAL_VAL`, `SEMP_VAL`, `FRSE_VAL`, `INT_VAL`, `DIV_VAL`,
+`RNT_VAL`, `CAP_VAL`, `UC_VAL`, `OI_VAL`, `ANN_VAL`, `PNSN_VAL`, `SS_VAL`),
+total money income (`PTOTVAL`), enrollment (`A_ENRLW`, `A_FTPT`, `A_HSCOL`),
+and disability flags (`PEDISDRS`, `PEDISEAR`, `PEDISEYE`, `PEDISOUT`,
+`PEDISPHY`, `PEDISREM`). Relationship codes follow the CPS ASEC `A_EXPRRP`
+recode, exposed as `microunit.CPSRelationshipCode`.
+
+### ACS column mapping is the consumer's responsibility
+
+The ACS PUMS -> CPS column mapping (`acs_to_cps_columns.py` in
+`policyengine-us-data`) is **not** part of `microunit`. That ~500-line module
+is ACS-PUMS-specific (`RELSHIPP`/`RELP` translation, marital-status recoding,
+and heuristic spouse/parent-pointer inference, since ACS provides no universal
+spouse or parent pointers) and belongs with the ACS reader. Consumers reading
+ACS should map their PUMS columns onto the CPS-like contract above and then
+call `construct_tax_units`. Accordingly, the ACS-specific tests from
+`policyengine-us-data` remain there; the full CPS construction test suite is
+ported here.
+
+### Packaged data
+
+The qualifying-relative gross income limit (the personal/dependent exemption
+amount under IRC 151(d), used by the IRC 152(d)(1)(B) gross income test) ships
+as package data at `microunit/data/dependent_gross_income_limit.yaml` and is
+loaded via `importlib.resources`, so the engine does not depend on
+`policyengine-us` being installed.
+
+## Scope
+
+This package should construct unit assignments and explain them. It should not
+calculate benefits, taxes, or eligibility amounts. Policy engines remain
+responsible for program formulas.
+
+Near-term roadmap:
+
+1. Move reusable SPM unit assignment out of `spm-calculator`.
+2. Move reusable tax-unit construction out of `policyengine-us-data` /
+   `policyengine-us`. (Done -- see "Rules-based tax-unit construction" above.)
+3. Add CPS and ACS source adapters for Microplex.
+4. Use SPM units as the temporary simplification for SNAP, Medicaid/MAGI, and
+   other program units.
+5. Replace those simplifications with real program rules once Microplex has a
+   stable end-to-end unit pipeline.

microunit-0.1.0/pyproject.toml

@@ -0,0 +1,112 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "microunit"
+# Base version; CI (.github/workflows/versioning.yaml) bumps this from the
+# changelog.d fragments on merge to main, so the first release publishes 0.1.0.
+version = "0.1.0"
+description = "Policy unit assignment for PolicyEngine's microdata stack"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "PolicyEngine", email = "hello@policyengine.org" }
+]
+keywords = [
+    "microdata",
+    "unit-assignment",
+    "microplex",
+    "tax-units",
+    "spm",
+    "policy-simulation",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+]
+requires-python = ">=3.11"
+dependencies = [
+    "numpy>=1.24",
+    "pandas>=2.0",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "ruff>=0.1",
+    "build>=1.0",
+    "towncrier>=24.8.0",
+]
+
+[project.urls]
+Repository = "https://github.com/PolicyEngine/microunit"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/microunit"]
+# Ship packaged rule data (the qualifying-relative gross income limit YAML)
+# alongside the Python modules.
+artifacts = ["src/microunit/data/*.yaml"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/microunit",
+    "tests",
+    "README.md",
+    "CHANGELOG.md",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+addopts = "-v --tb=short"
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]
+ignore = ["E501"]
+
+[tool.towncrier]
+package = "microunit"
+directory = "changelog.d"
+filename = "CHANGELOG.md"
+title_format = "## [{version}] - {project_date}"
+issue_format = ""
+underlines = ["", "", ""]
+
+[[tool.towncrier.type]]
+directory = "breaking"
+name = "Breaking changes"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "added"
+name = "Added"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "changed"
+name = "Changed"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "fixed"
+name = "Fixed"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "removed"
+name = "Removed"
+showcontent = true

microunit-0.1.0/src/microunit/__init__.py

@@ -0,0 +1,61 @@
+"""Microdata unit assignment primitives."""
+
+from microunit.core import EgoUnitMembership, UnitPartition
+from microunit.diagnostics import PartitionMatchReport, partition_match_report
+from microunit.registry import UnitKind, UnitScheme, get_scheme, list_schemes
+from microunit.rule_helpers import (
+    REFERENCE_PERSON_CODES,
+    REFERENCE_QUALIFYING_CHILD_CODES,
+    REFERENCE_QUALIFYING_RELATIVE_CODES,
+    REFERENCE_SPOUSE_CODES,
+    CPSRelationshipCode,
+    dependent_gross_income_limit,
+    qualifying_child_age_test,
+    reference_relationship_allows_qualifying_child,
+    reference_relationship_allows_qualifying_relative,
+    related_to_head_or_spouse,
+)
+from microunit.tax_unit_construction import (
+    CENSUS_DOCUMENTED_MODE,
+    DEPENDENT,
+    HEAD,
+    POLICYENGINE_MODE,
+    SPOUSE,
+    SUPPORTED_TAX_UNIT_CONSTRUCTION_MODES,
+    construct_tax_units,
+    estimate_dependent_gross_income,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # Core containers
+    "EgoUnitMembership",
+    "PartitionMatchReport",
+    "UnitKind",
+    "UnitPartition",
+    "UnitScheme",
+    "get_scheme",
+    "list_schemes",
+    "partition_match_report",
+    # Rules-based tax-unit construction engine
+    "construct_tax_units",
+    "estimate_dependent_gross_income",
+    "HEAD",
+    "SPOUSE",
+    "DEPENDENT",
+    "POLICYENGINE_MODE",
+    "CENSUS_DOCUMENTED_MODE",
+    "SUPPORTED_TAX_UNIT_CONSTRUCTION_MODES",
+    "CPSRelationshipCode",
+    "REFERENCE_PERSON_CODES",
+    "REFERENCE_SPOUSE_CODES",
+    "REFERENCE_QUALIFYING_CHILD_CODES",
+    "REFERENCE_QUALIFYING_RELATIVE_CODES",
+    "dependent_gross_income_limit",
+    "qualifying_child_age_test",
+    "reference_relationship_allows_qualifying_child",
+    "reference_relationship_allows_qualifying_relative",
+    "related_to_head_or_spouse",
+]