diff --git a/chronicle/source_package.py b/chronicle/source_package.py index 993b4d9..e6ebc23 100644 --- a/chronicle/source_package.py +++ b/chronicle/source_package.py @@ -94,6 +94,9 @@ "hmrc/salary_sacrifice_reform_2029_headcounts" ), "ici-fact-book-table-30": Path("ici/fact_book_table_30"), + "ird-working-for-families-statistics-sept-2025": Path( + "ird/working_for_families_statistics_sept_2025" + ), "isc-annual-census-2023": Path("isc/annual_census_2023"), "isc-annual-census-2024": Path("isc/annual_census_2024"), "mhclg-council-tax-levels-england-2026-27": Path( diff --git a/db/data/ird/working_for_families_statistics_sept_2025/manifest.yaml b/db/data/ird/working_for_families_statistics_sept_2025/manifest.yaml new file mode 100644 index 0000000..d73e416 --- /dev/null +++ b/db/data/ird/working_for_families_statistics_sept_2025/manifest.yaml @@ -0,0 +1,18 @@ +source_id: ird +package_id: ird-working-for-families-statistics-sept-2025 +dataset: ird_working_for_families_statistics_sept_2025 +source_page: https://www.ird.govt.nz/about-us/tax-statistics/working-for-families-statistics/working-for-families-statistics-datasets +table: Working for Families statistics - September 2025 +files: + 2024: + filename: working-for-families-statistics---sept-2025.xlsx + source_url: https://www.ird.govt.nz/-/media/project/ir/home/documents/about-us/tax-statistics---current/social-policy/wff-stats/working-for-families-statistics---sept-2025.xlsx?modified=20251111195236 + sha256: 95ae66f4d44f3f47ea3daa006328b22f061a163cf7e31b487342cde649390833 + size_bytes: 71211 + fetched_at: '2026-08-29T22:46:45+00:00' + storage: + r2: + provider: r2 + bucket: ledger-raw + key: raw/nz/ird/ird-working-for-families-statistics-sept-2025/2024/95ae66f4d44f3f47ea3daa006328b22f061a163cf7e31b487342cde649390833/working-for-families-statistics---sept-2025.xlsx + uri: r2://ledger-raw/raw/nz/ird/ird-working-for-families-statistics-sept-2025/2024/95ae66f4d44f3f47ea3daa006328b22f061a163cf7e31b487342cde649390833/working-for-families-statistics---sept-2025.xlsx diff --git a/db/data/ird/working_for_families_statistics_sept_2025/working-for-families-statistics---sept-2025.xlsx b/db/data/ird/working_for_families_statistics_sept_2025/working-for-families-statistics---sept-2025.xlsx new file mode 100644 index 0000000..3b286ea Binary files /dev/null and b/db/data/ird/working_for_families_statistics_sept_2025/working-for-families-statistics---sept-2025.xlsx differ diff --git a/docs/pe-nz-source-checklist.md b/docs/pe-nz-source-checklist.md index c0b362a..663eccd 100644 --- a/docs/pe-nz-source-checklist.md +++ b/docs/pe-nz-source-checklist.md @@ -60,7 +60,7 @@ tests, and record a verified `raw/nz/...` R2 URI. | `stats_nz/census_2023_ethnicity_age_region` | [ ] | [ ] | [ ] | | | `ird/taxable_income_distribution_2025` | [ ] | [ ] | [ ] | | | `ird/wage_salary_distribution_2025` | [ ] | [ ] | [ ] | | -| `ird/working_for_families_statistics_sept_2025` | [ ] | [ ] | [ ] | | +| `ird/working_for_families_statistics_sept_2025` | [x] | [x] | [x] | TY2024: 330 administrative facts; count/entitlement, children, family size, and full published income table. | | `ird/student_loan_statistics_march_2026` | [ ] | [ ] | [ ] | | | `msd/benefit_fact_sheets_national_march_2026` | [ ] | [ ] | [ ] | | | `msd/benefit_fact_sheets_supplementary_march_2026` | [ ] | [ ] | [ ] | | @@ -68,3 +68,22 @@ tests, and record a verified `raw/nz/...` R2 URI. | `msd/annual_report_benefit_expenses_2025` | [ ] | [ ] | [ ] | | | `mbie/tenancy_bond_rents_tla_2026` | [ ] | [ ] | [ ] | | | `stats_nz/qes_average_earnings_march_2026` | [ ] | [ ] | [ ] | | + +### WFF source semantics + +The September 2025 IRD workbook contributes 330 facts for the 2024 tax year. +The national recipient totals describe administrative claims with non-zero +entitlement, not every eligible family or cash paid during the financial year. +The income table uses an entitlement-time-weighted average of assessed family +scheme income. For Work and Income recipients who did not file a WFF return, +IRD uses individual tax-return income, which excludes partner income. These +workbook Explanatory notes qualify the published income bands; this is not the +individual taxable-income universe in the other IRD packages. Numeric band +labels remain source labels until a consumer supplies an evidenced mapping. +Unknown income and the published total remain distinct source rows; the +publisher's rounding-adjustment row is parsed and tested but is not a population +fact. Independently published family and credit totals are not reconciled here. + +The workbook was uploaded to the manifest's immutable `raw/nz/ird/...` key and +downloaded again on 2026-08-29. Its SHA-256 remained +`95ae66f4d44f3f47ea3daa006328b22f061a163cf7e31b487342cde649390833`. diff --git a/packages/ird/working_for_families_statistics_sept_2025/source_package.yaml b/packages/ird/working_for_families_statistics_sept_2025/source_package.yaml new file mode 100644 index 0000000..01be2c2 --- /dev/null +++ b/packages/ird/working_for_families_statistics_sept_2025/source_package.yaml @@ -0,0 +1,1363 @@ +# Inland Revenue's September 2025 workbook reports administrative Working for +# Families entitlements for the 2024 New Zealand income tax year. This first NZ +# package keeps the non-derived 2024 WFF/IWTC statistics in the +# workbook: recipient families and aggregate entitlement by current credit, +# supported children and family size, and the full published family-income +# distribution. The publisher's average-entitlement table is parsed but is +# outside this package's emitted count-and-total-amount scope. CTC/PTC are +# obsolete and blank in 2024. The income table's +# explicit "Rounding adjustment" row is not a population stratum; it is parsed, +# excluded from facts, and pinned in package tests. Numeric income-band labels +# are preserved as labels, not silently interpreted as interval boundaries. +schema_version: ledger.source_package.v1 +package_id: ird-working-for-families-statistics-sept-2025 +label: Inland Revenue Working for Families administrative statistics, tax year 2024 +artifact: + source_name: ird + source_table: Working for Families statistics - September 2025 + resource_package: db + resource_directory: data/ird/working_for_families_statistics_sept_2025 + manifest: manifest.yaml + vintage: september_2025_release + extracted_at: '2026-08-29' + extraction_method: xlsx used-range cell parse of the two publisher data worksheets + parser: xlsx_used_range + artifact_year: 2024 + sheets: + - Working for families data + - Working for families income +record_sets: +- record_set_id: ird_wff_statistics.ty2024.recipient_families + provenance_class: administrative + record_set_spec_id: ird_wff_statistics.recipient_families.v1 + source_record_id_prefix: ird_wff_statistics.ty2024.recipient_families + sheet_name: Working for families data + period_type: tax_year + period: 2024 + period_coverage: &tax_year_coverage + basis: tax + source_period_label: '2024 Tax Year / 2023-24 Tax Year' + start_date: '2023-04-01' + end_date: '2024-03-31' + notes: >- + Inland Revenue describes these as entitlements during an income tax year. + The workbook displays 2024 on the aggregate sheet and 2023-24 on the + income-distribution sheet. These are administrative claims with non-zero + entitlement, not an estimate of all eligible families or cash paid during + the financial year. + geography_id: NZ + geography_level: country + geography_name: New Zealand + geography_vintage: current + entity: family + entity_role: wff_entitled_family + domain: working_for_families + groupby_dimension: ird_wff_statistics.credit_component + shared_filters: + wff_entitlement_status: nonzero + shared_constraints: + - variable: wff_entitlement_status + operator: == + value: nonzero + label: Non-zero Working for Families entitlement + rows: + - value_id: all + label: 2024 tax year + ordinal: 0 + row_number: 27 + expected_row_header_column: A + expected_row_header: '2024-03-01T00:00:00' + guard_cells: + - column: A + row: 3 + expected_value: Tax Year + label: table year header + - column: A + row: 1 + expected_value: Working for Families Tax Credits - number of WFF claims with non-zero entitlement (000s) + label: table title + table_record_kind: total + measures: + - measure_id: ftc_recipient_families + label: Families with non-zero Family Tax Credit entitlement + ordinal: 0 + column: B + source_column_id: FTC + expected_column_header_row: 3 + expected_column_header: FTC + concept: ird_wff_statistics.recipient_families + source_concept: ird_wff_statistics.recipient_families + concept_relation: source_label + concept_authority: ird + concept_evidence_url: https://www.ird.govt.nz/about-us/tax-statistics/working-for-families-statistics/working-for-families-statistics-datasets + concept_evidence_notes: >- + Workbook table "number of WFF claims with non-zero entitlement (000s)", + FTC column, 2024 tax year. Inland Revenue calls the total families and + explains that a family may receive more than one credit. + unit: count + aggregation: sum + value_scale: 1000 + expected_cell_type: number + filters: {wff_credit_component: ftc} + constraints: + - {variable: wff_credit_component, operator: '==', value: ftc, label: Family Tax Credit} + - measure_id: mftc_recipient_families + label: Families with non-zero Minimum Family Tax Credit entitlement + ordinal: 1 + column: D + source_column_id: MFTC + expected_column_header_row: 3 + expected_column_header: MFTC + concept: ird_wff_statistics.recipient_families + source_concept: ird_wff_statistics.recipient_families + concept_relation: source_label + concept_authority: ird + concept_evidence_url: https://www.ird.govt.nz/about-us/tax-statistics/working-for-families-statistics/working-for-families-statistics-datasets + concept_evidence_notes: Workbook non-zero entitlement table, MFTC column, 2024 tax year. + unit: count + aggregation: sum + value_scale: 1000 + expected_cell_type: number + filters: {wff_credit_component: mftc} + constraints: + - {variable: wff_credit_component, operator: '==', value: mftc, label: Minimum Family Tax Credit} + - measure_id: iwtc_recipient_families + label: Families with non-zero In-work Tax Credit entitlement + ordinal: 2 + column: F + source_column_id: IWTC + expected_column_header_row: 3 + expected_column_header: IWTC + concept: ird_wff_statistics.recipient_families + source_concept: ird_wff_statistics.recipient_families + concept_relation: source_label + concept_authority: ird + concept_evidence_url: https://www.ird.govt.nz/about-us/tax-statistics/working-for-families-statistics/working-for-families-statistics-datasets + concept_evidence_notes: Workbook non-zero entitlement table, IWTC column, 2024 tax year. + unit: count + aggregation: sum + value_scale: 1000 + expected_cell_type: number + filters: {wff_credit_component: iwtc} + constraints: + - {variable: wff_credit_component, operator: '==', value: iwtc, label: In-work Tax Credit} + - measure_id: bstc_recipient_families + label: Families with non-zero Best Start Tax Credit entitlement + ordinal: 3 + column: G + source_column_id: BSTC + expected_column_header_row: 3 + expected_column_header: BSTC + concept: ird_wff_statistics.recipient_families + source_concept: ird_wff_statistics.recipient_families + concept_relation: source_label + concept_authority: ird + concept_evidence_url: https://www.ird.govt.nz/about-us/tax-statistics/working-for-families-statistics/working-for-families-statistics-datasets + concept_evidence_notes: Workbook non-zero entitlement table, BSTC column, 2024 tax year. + unit: count + aggregation: sum + value_scale: 1000 + expected_cell_type: number + filters: {wff_credit_component: bstc} + constraints: + - {variable: wff_credit_component, operator: '==', value: bstc, label: Best Start Tax Credit} + - measure_id: wff_recipient_families + label: Families receiving at least one Working for Families credit + ordinal: 4 + column: H + source_column_id: total_number_of_families + expected_column_header_row: 3 + expected_column_header: Total number of families* + concept: ird_wff_statistics.recipient_families + source_concept: ird_wff_statistics.recipient_families + concept_relation: source_label + concept_authority: ird + concept_evidence_url: https://www.ird.govt.nz/about-us/tax-statistics/working-for-families-statistics/working-for-families-statistics-datasets + concept_evidence_notes: >- + Workbook total number of families receiving at least one tax credit, + 2024 tax year; families receiving multiple credits are counted once. + unit: count + aggregation: sum + value_scale: 1000 + expected_cell_type: number + filters: {wff_credit_component: any} + constraints: + - {variable: wff_credit_component, operator: '==', value: any, label: At least one Working for Families credit} + +- record_set_id: ird_wff_statistics.ty2024.aggregate_entitlements + provenance_class: administrative + record_set_spec_id: ird_wff_statistics.aggregate_entitlements.v1 + source_record_id_prefix: ird_wff_statistics.ty2024.aggregate_entitlements + sheet_name: Working for families data + period_type: tax_year + period: 2024 + period_coverage: *tax_year_coverage + geography_id: NZ + geography_level: country + geography_name: New Zealand + geography_vintage: current + entity: family + entity_role: wff_entitled_family + domain: working_for_families + groupby_dimension: ird_wff_statistics.credit_component + rows: + - value_id: all + label: 2024 tax year + ordinal: 0 + row_number: 87 + expected_row_header_column: A + expected_row_header: '2024-03-01T00:00:00' + guard_cells: + - column: A + row: 63 + expected_value: Tax Year + label: table year header + - column: A + row: 61 + expected_value: Working for Families Tax Credits - aggregate entitlements ($ million) + label: table title + table_record_kind: total + measures: + - measure_id: ftc_entitlement_nzd + label: Aggregate Family Tax Credit entitlement + ordinal: 0 + column: B + source_column_id: FTC + expected_column_header_row: 63 + expected_column_header: FTC + concept: ird_wff_statistics.aggregate_entitlement + source_concept: ird_wff_statistics.aggregate_entitlement + concept_relation: source_label + concept_authority: ird + concept_evidence_url: https://www.ird.govt.nz/about-us/tax-statistics/working-for-families-statistics/working-for-families-statistics-datasets + concept_evidence_notes: Workbook aggregate entitlements ($ million), FTC column, 2024 tax year. + unit: nzd + aggregation: sum + value_scale: 1000000 + filters: {wff_credit_component: ftc} + constraints: + - {variable: wff_credit_component, operator: '==', value: ftc, label: Family Tax Credit} + - measure_id: mftc_entitlement_nzd + label: Aggregate Minimum Family Tax Credit entitlement + ordinal: 1 + column: D + source_column_id: MFTC + expected_column_header_row: 63 + expected_column_header: MFTC + concept: ird_wff_statistics.aggregate_entitlement + source_concept: ird_wff_statistics.aggregate_entitlement + concept_relation: source_label + concept_authority: ird + concept_evidence_url: https://www.ird.govt.nz/about-us/tax-statistics/working-for-families-statistics/working-for-families-statistics-datasets + concept_evidence_notes: Workbook aggregate entitlements ($ million), MFTC column, 2024 tax year. + unit: nzd + aggregation: sum + value_scale: 1000000 + filters: {wff_credit_component: mftc} + constraints: + - {variable: wff_credit_component, operator: '==', value: mftc, label: Minimum Family Tax Credit} + - measure_id: iwtc_entitlement_nzd + label: Aggregate In-work Tax Credit entitlement + ordinal: 2 + column: F + source_column_id: IWTC + expected_column_header_row: 63 + expected_column_header: IWTC + concept: ird_wff_statistics.aggregate_entitlement + source_concept: ird_wff_statistics.aggregate_entitlement + concept_relation: source_label + concept_authority: ird + concept_evidence_url: https://www.ird.govt.nz/about-us/tax-statistics/working-for-families-statistics/working-for-families-statistics-datasets + concept_evidence_notes: Workbook aggregate entitlements ($ million), IWTC column, 2024 tax year. + unit: nzd + aggregation: sum + value_scale: 1000000 + filters: {wff_credit_component: iwtc} + constraints: + - {variable: wff_credit_component, operator: '==', value: iwtc, label: In-work Tax Credit} + - measure_id: bstc_entitlement_nzd + label: Aggregate Best Start Tax Credit entitlement + ordinal: 3 + column: G + source_column_id: BSTC + expected_column_header_row: 63 + expected_column_header: BSTC + concept: ird_wff_statistics.aggregate_entitlement + source_concept: ird_wff_statistics.aggregate_entitlement + concept_relation: source_label + concept_authority: ird + concept_evidence_url: https://www.ird.govt.nz/about-us/tax-statistics/working-for-families-statistics/working-for-families-statistics-datasets + concept_evidence_notes: Workbook aggregate entitlements ($ million), BSTC column, 2024 tax year. + unit: nzd + aggregation: sum + value_scale: 1000000 + filters: {wff_credit_component: bstc} + constraints: + - {variable: wff_credit_component, operator: '==', value: bstc, label: Best Start Tax Credit} + - measure_id: wff_entitlement_nzd + label: Aggregate Working for Families entitlement + ordinal: 4 + column: H + source_column_id: total + expected_column_header_row: 63 + expected_column_header: Total + concept: ird_wff_statistics.aggregate_entitlement + source_concept: ird_wff_statistics.aggregate_entitlement + concept_relation: source_label + concept_authority: ird + concept_evidence_url: https://www.ird.govt.nz/about-us/tax-statistics/working-for-families-statistics/working-for-families-statistics-datasets + concept_evidence_notes: Workbook aggregate entitlements ($ million), Total column, 2024 tax year. + unit: nzd + aggregation: sum + value_scale: 1000000 + filters: {wff_credit_component: any} + constraints: + - {variable: wff_credit_component, operator: '==', value: any, label: All Working for Families credits} + +- record_set_id: ird_wff_statistics.ty2024.supported_children + provenance_class: administrative + record_set_spec_id: ird_wff_statistics.supported_children.v1 + source_record_id_prefix: ird_wff_statistics.ty2024.supported_children + sheet_name: Working for families data + period_type: tax_year + period: 2024 + period_coverage: *tax_year_coverage + geography_id: NZ + geography_level: country + geography_name: New Zealand + geography_vintage: current + entity: person + entity_role: wff_supported_child + domain: working_for_families + groupby_dimension: ird_wff_statistics.supported_children + rows: + - value_id: all + label: 2024 tax year + ordinal: 0 + row_number: 99 + expected_row_header_column: A + expected_row_header: '2024-03-01T00:00:00' + guard_cells: + - column: A + row: 90 + expected_value: Working for Families Tax Credits - number of children supported + label: table title + table_record_kind: total + measures: + - measure_id: wff_supported_children + label: Children supported by Working for Families + ordinal: 0 + column: B + source_column_id: total_number_of_children + expected_column_header_row: 92 + expected_column_header: Total number of children (000's) + concept: ird_wff_statistics.supported_children + source_concept: ird_wff_statistics.supported_children + concept_relation: source_label + concept_authority: ird + concept_evidence_url: https://www.ird.govt.nz/about-us/tax-statistics/working-for-families-statistics/working-for-families-statistics-technical-information + concept_evidence_notes: >- + Workbook total number of children supported, 2024 tax year. Inland Revenue + states that child counts are adjusted for known shared care, may retain + unknown shared-care double counting, and use the maximum family child count + at the start or end of the year. + unit: count + aggregation: sum + value_scale: 1000 + +- record_set_id: ird_wff_statistics.ty2024.recipient_families_by_child_count + provenance_class: administrative + record_set_spec_id: ird_wff_statistics.recipient_families_by_child_count.v1 + source_record_id_prefix: ird_wff_statistics.ty2024.recipient_families_by_child_count + sheet_name: Working for families data + period_type: tax_year + period: 2024 + period_coverage: *tax_year_coverage + geography_id: NZ + geography_level: country + geography_name: New Zealand + geography_vintage: current + entity: family + entity_role: wff_entitled_family + domain: working_for_families + groupby_dimension: ird_wff_statistics.supported_child_count + rows: + - value_id: all + label: 2024 tax year + ordinal: 0 + row_number: 99 + expected_row_header_column: A + expected_row_header: '2024-03-01T00:00:00' + guard_cells: + - column: C + row: 92 + expected_value: Number children per family (count of families 000's) + label: family-size table header + table_record_kind: total + measures: + - measure_id: wff_families_1_child + label: Working for Families families with 1 supported child + ordinal: 0 + column: C + source_column_id: 1_child + expected_column_header_row: 93 + expected_column_header: 1 Child + concept: ird_wff_statistics.recipient_families + source_concept: ird_wff_statistics.recipient_families + concept_relation: source_label + concept_authority: ird + concept_evidence_url: https://www.ird.govt.nz/about-us/tax-statistics/working-for-families-statistics/working-for-families-statistics-technical-information + concept_evidence_notes: Workbook number of families by supported child count, 2024 tax year. + unit: count + aggregation: sum + value_scale: 1000 + constraints: + - {variable: supported_child_count, operator: '==', value: 1, unit: children, label: One supported child} + - measure_id: wff_families_2_children + label: Working for Families families with 2 supported children + ordinal: 1 + column: D + source_column_id: 2_children + expected_column_header_row: 93 + expected_column_header: 2 Children + concept: ird_wff_statistics.recipient_families + source_concept: ird_wff_statistics.recipient_families + concept_relation: source_label + concept_authority: ird + concept_evidence_url: https://www.ird.govt.nz/about-us/tax-statistics/working-for-families-statistics/working-for-families-statistics-technical-information + concept_evidence_notes: Workbook number of families by supported child count, 2024 tax year. + unit: count + aggregation: sum + value_scale: 1000 + constraints: + - {variable: supported_child_count, operator: '==', value: 2, unit: children, label: Two supported children} + - measure_id: wff_families_3_children + label: Working for Families families with 3 supported children + ordinal: 2 + column: E + source_column_id: 3_children + expected_column_header_row: 93 + expected_column_header: 3 Children + concept: ird_wff_statistics.recipient_families + source_concept: ird_wff_statistics.recipient_families + concept_relation: source_label + concept_authority: ird + concept_evidence_url: https://www.ird.govt.nz/about-us/tax-statistics/working-for-families-statistics/working-for-families-statistics-technical-information + concept_evidence_notes: Workbook number of families by supported child count, 2024 tax year. + unit: count + aggregation: sum + value_scale: 1000 + constraints: + - {variable: supported_child_count, operator: '==', value: 3, unit: children, label: Three supported children} + - measure_id: wff_families_4_children + label: Working for Families families with 4 supported children + ordinal: 3 + column: F + source_column_id: 4_children + expected_column_header_row: 93 + expected_column_header: 4 Children + concept: ird_wff_statistics.recipient_families + source_concept: ird_wff_statistics.recipient_families + concept_relation: source_label + concept_authority: ird + concept_evidence_url: https://www.ird.govt.nz/about-us/tax-statistics/working-for-families-statistics/working-for-families-statistics-technical-information + concept_evidence_notes: Workbook number of families by supported child count, 2024 tax year. + unit: count + aggregation: sum + value_scale: 1000 + constraints: + - {variable: supported_child_count, operator: '==', value: 4, unit: children, label: Four supported children} + - measure_id: wff_families_5_children + label: Working for Families families with 5 supported children + ordinal: 4 + column: G + source_column_id: 5_children + expected_column_header_row: 93 + expected_column_header: 5 Children + concept: ird_wff_statistics.recipient_families + source_concept: ird_wff_statistics.recipient_families + concept_relation: source_label + concept_authority: ird + concept_evidence_url: https://www.ird.govt.nz/about-us/tax-statistics/working-for-families-statistics/working-for-families-statistics-technical-information + concept_evidence_notes: Workbook number of families by supported child count, 2024 tax year. + unit: count + aggregation: sum + value_scale: 1000 + constraints: + - {variable: supported_child_count, operator: '==', value: 5, unit: children, label: Five supported children} + - measure_id: wff_families_6_children + label: Working for Families families with 6 supported children + ordinal: 5 + column: H + source_column_id: 6_children + expected_column_header_row: 93 + expected_column_header: 6 Children + concept: ird_wff_statistics.recipient_families + source_concept: ird_wff_statistics.recipient_families + concept_relation: source_label + concept_authority: ird + concept_evidence_url: https://www.ird.govt.nz/about-us/tax-statistics/working-for-families-statistics/working-for-families-statistics-technical-information + concept_evidence_notes: Workbook number of families by supported child count, 2024 tax year. + unit: count + aggregation: sum + value_scale: 1000 + constraints: + - {variable: supported_child_count, operator: '==', value: 6, unit: children, label: Six supported children} + - measure_id: wff_families_7_plus_children + label: Working for Families families with 7 or more supported children + ordinal: 6 + column: I + source_column_id: 7_plus_children + expected_column_header_row: 93 + expected_column_header: 7+ Children + concept: ird_wff_statistics.recipient_families + source_concept: ird_wff_statistics.recipient_families + concept_relation: source_label + concept_authority: ird + concept_evidence_url: https://www.ird.govt.nz/about-us/tax-statistics/working-for-families-statistics/working-for-families-statistics-technical-information + concept_evidence_notes: Workbook number of families by supported child count, 2024 tax year. + unit: count + aggregation: sum + value_scale: 1000 + constraints: + - {variable: supported_child_count, operator: '>=', value: 7, unit: children, label: Seven or more supported children} + +- record_set_id: ird_wff_statistics.ty2024.income_distribution + provenance_class: administrative + record_set_spec_id: ird_wff_statistics.income_distribution.v1 + source_record_id_prefix: ird_wff_statistics.ty2024.income_distribution + sheet_name: Working for families income + period_type: tax_year + period: 2024 + period_coverage: *tax_year_coverage + geography_id: NZ + geography_level: country + geography_name: New Zealand + geography_vintage: current + entity: family + entity_role: wff_entitled_family + domain: working_for_families + groupby_dimension: ird_wff_statistics.family_income_band_source_label + rows: + - value_id: income_label_5000 + label: 'Published family income band 5000' + ordinal: 0 + row_number: 12 + expected_row_header_column: AO + expected_row_header: 5000 + table_record_kind: detail + filters: + family_scheme_income_band_source_label: 5000 + constraints: + - variable: family_scheme_income_band_source_label + operator: == + value: 5000 + label: Published Working for Families family-income band label + guard_cells: &income_table_guards + - column: AO + row: 10 + expected_value: 2023-24 Tax Year + label: income table tax-year label + - column: AO + row: 11 + expected_value: Family income band ($)* + label: income table band header + - column: AO + row: 52 + expected_value: '* The tables only include information for families eligible for Working for Families tax credits in that tax year. Families not eligible are excluded.' + label: income table population footnote + - value_id: income_label_10000 + label: 'Published family income band 10000' + ordinal: 1 + row_number: 13 + expected_row_header_column: AO + expected_row_header: 10000 + table_record_kind: detail + filters: + family_scheme_income_band_source_label: 10000 + constraints: + - variable: family_scheme_income_band_source_label + operator: == + value: 10000 + label: Published Working for Families family-income band label + guard_cells: *income_table_guards + - value_id: income_label_15000 + label: 'Published family income band 15000' + ordinal: 2 + row_number: 14 + expected_row_header_column: AO + expected_row_header: 15000 + table_record_kind: detail + filters: + family_scheme_income_band_source_label: 15000 + constraints: + - variable: family_scheme_income_band_source_label + operator: == + value: 15000 + label: Published Working for Families family-income band label + guard_cells: *income_table_guards + - value_id: income_label_20000 + label: 'Published family income band 20000' + ordinal: 3 + row_number: 15 + expected_row_header_column: AO + expected_row_header: 20000 + table_record_kind: detail + filters: + family_scheme_income_band_source_label: 20000 + constraints: + - variable: family_scheme_income_band_source_label + operator: == + value: 20000 + label: Published Working for Families family-income band label + guard_cells: *income_table_guards + - value_id: income_label_25000 + label: 'Published family income band 25000' + ordinal: 4 + row_number: 16 + expected_row_header_column: AO + expected_row_header: 25000 + table_record_kind: detail + filters: + family_scheme_income_band_source_label: 25000 + constraints: + - variable: family_scheme_income_band_source_label + operator: == + value: 25000 + label: Published Working for Families family-income band label + guard_cells: *income_table_guards + - value_id: income_label_30000 + label: 'Published family income band 30000' + ordinal: 5 + row_number: 17 + expected_row_header_column: AO + expected_row_header: 30000 + table_record_kind: detail + filters: + family_scheme_income_band_source_label: 30000 + constraints: + - variable: family_scheme_income_band_source_label + operator: == + value: 30000 + label: Published Working for Families family-income band label + guard_cells: *income_table_guards + - value_id: income_label_35000 + label: 'Published family income band 35000' + ordinal: 6 + row_number: 18 + expected_row_header_column: AO + expected_row_header: 35000 + table_record_kind: detail + filters: + family_scheme_income_band_source_label: 35000 + constraints: + - variable: family_scheme_income_band_source_label + operator: == + value: 35000 + label: Published Working for Families family-income band label + guard_cells: *income_table_guards + - value_id: income_label_40000 + label: 'Published family income band 40000' + ordinal: 7 + row_number: 19 + expected_row_header_column: AO + expected_row_header: 40000 + table_record_kind: detail + filters: + family_scheme_income_band_source_label: 40000 + constraints: + - variable: family_scheme_income_band_source_label + operator: == + value: 40000 + label: Published Working for Families family-income band label + guard_cells: *income_table_guards + - value_id: income_label_45000 + label: 'Published family income band 45000' + ordinal: 8 + row_number: 20 + expected_row_header_column: AO + expected_row_header: 45000 + table_record_kind: detail + filters: + family_scheme_income_band_source_label: 45000 + constraints: + - variable: family_scheme_income_band_source_label + operator: == + value: 45000 + label: Published Working for Families family-income band label + guard_cells: *income_table_guards + - value_id: income_label_50000 + label: 'Published family income band 50000' + ordinal: 9 + row_number: 21 + expected_row_header_column: AO + expected_row_header: 50000 + table_record_kind: detail + filters: + family_scheme_income_band_source_label: 50000 + constraints: + - variable: family_scheme_income_band_source_label + operator: == + value: 50000 + label: Published Working for Families family-income band label + guard_cells: *income_table_guards + - value_id: income_label_55000 + label: 'Published family income band 55000' + ordinal: 10 + row_number: 22 + expected_row_header_column: AO + expected_row_header: 55000 + table_record_kind: detail + filters: + family_scheme_income_band_source_label: 55000 + constraints: + - variable: family_scheme_income_band_source_label + operator: == + value: 55000 + label: Published Working for Families family-income band label + guard_cells: *income_table_guards + - value_id: income_label_60000 + label: 'Published family income band 60000' + ordinal: 11 + row_number: 23 + expected_row_header_column: AO + expected_row_header: 60000 + table_record_kind: detail + filters: + family_scheme_income_band_source_label: 60000 + constraints: + - variable: family_scheme_income_band_source_label + operator: == + value: 60000 + label: Published Working for Families family-income band label + guard_cells: *income_table_guards + - value_id: income_label_65000 + label: 'Published family income band 65000' + ordinal: 12 + row_number: 24 + expected_row_header_column: AO + expected_row_header: 65000 + table_record_kind: detail + filters: + family_scheme_income_band_source_label: 65000 + constraints: + - variable: family_scheme_income_band_source_label + operator: == + value: 65000 + label: Published Working for Families family-income band label + guard_cells: *income_table_guards + - value_id: income_label_70000 + label: 'Published family income band 70000' + ordinal: 13 + row_number: 25 + expected_row_header_column: AO + expected_row_header: 70000 + table_record_kind: detail + filters: + family_scheme_income_band_source_label: 70000 + constraints: + - variable: family_scheme_income_band_source_label + operator: == + value: 70000 + label: Published Working for Families family-income band label + guard_cells: *income_table_guards + - value_id: income_label_75000 + label: 'Published family income band 75000' + ordinal: 14 + row_number: 26 + expected_row_header_column: AO + expected_row_header: 75000 + table_record_kind: detail + filters: + family_scheme_income_band_source_label: 75000 + constraints: + - variable: family_scheme_income_band_source_label + operator: == + value: 75000 + label: Published Working for Families family-income band label + guard_cells: *income_table_guards + - value_id: income_label_80000 + label: 'Published family income band 80000' + ordinal: 15 + row_number: 27 + expected_row_header_column: AO + expected_row_header: 80000 + table_record_kind: detail + filters: + family_scheme_income_band_source_label: 80000 + constraints: + - variable: family_scheme_income_band_source_label + operator: == + value: 80000 + label: Published Working for Families family-income band label + guard_cells: *income_table_guards + - value_id: income_label_85000 + label: 'Published family income band 85000' + ordinal: 16 + row_number: 28 + expected_row_header_column: AO + expected_row_header: 85000 + table_record_kind: detail + filters: + family_scheme_income_band_source_label: 85000 + constraints: + - variable: family_scheme_income_band_source_label + operator: == + value: 85000 + label: Published Working for Families family-income band label + guard_cells: *income_table_guards + - value_id: income_label_90000 + label: 'Published family income band 90000' + ordinal: 17 + row_number: 29 + expected_row_header_column: AO + expected_row_header: 90000 + table_record_kind: detail + filters: + family_scheme_income_band_source_label: 90000 + constraints: + - variable: family_scheme_income_band_source_label + operator: == + value: 90000 + label: Published Working for Families family-income band label + guard_cells: *income_table_guards + - value_id: income_label_95000 + label: 'Published family income band 95000' + ordinal: 18 + row_number: 30 + expected_row_header_column: AO + expected_row_header: 95000 + table_record_kind: detail + filters: + family_scheme_income_band_source_label: 95000 + constraints: + - variable: family_scheme_income_band_source_label + operator: == + value: 95000 + label: Published Working for Families family-income band label + guard_cells: *income_table_guards + - value_id: income_label_100000 + label: 'Published family income band 100000' + ordinal: 19 + row_number: 31 + expected_row_header_column: AO + expected_row_header: 100000 + table_record_kind: detail + filters: + family_scheme_income_band_source_label: 100000 + constraints: + - variable: family_scheme_income_band_source_label + operator: == + value: 100000 + label: Published Working for Families family-income band label + guard_cells: *income_table_guards + - value_id: income_label_105000 + label: 'Published family income band 105000' + ordinal: 20 + row_number: 32 + expected_row_header_column: AO + expected_row_header: 105000 + table_record_kind: detail + filters: + family_scheme_income_band_source_label: 105000 + constraints: + - variable: family_scheme_income_band_source_label + operator: == + value: 105000 + label: Published Working for Families family-income band label + guard_cells: *income_table_guards + - value_id: income_label_110000 + label: 'Published family income band 110000' + ordinal: 21 + row_number: 33 + expected_row_header_column: AO + expected_row_header: 110000 + table_record_kind: detail + filters: + family_scheme_income_band_source_label: 110000 + constraints: + - variable: family_scheme_income_band_source_label + operator: == + value: 110000 + label: Published Working for Families family-income band label + guard_cells: *income_table_guards + - value_id: income_label_115000 + label: 'Published family income band 115000' + ordinal: 22 + row_number: 34 + expected_row_header_column: AO + expected_row_header: 115000 + table_record_kind: detail + filters: + family_scheme_income_band_source_label: 115000 + constraints: + - variable: family_scheme_income_band_source_label + operator: == + value: 115000 + label: Published Working for Families family-income band label + guard_cells: *income_table_guards + - value_id: income_label_120000 + label: 'Published family income band 120000' + ordinal: 23 + row_number: 35 + expected_row_header_column: AO + expected_row_header: 120000 + table_record_kind: detail + filters: + family_scheme_income_band_source_label: 120000 + constraints: + - variable: family_scheme_income_band_source_label + operator: == + value: 120000 + label: Published Working for Families family-income band label + guard_cells: *income_table_guards + - value_id: income_label_125000 + label: 'Published family income band 125000' + ordinal: 24 + row_number: 36 + expected_row_header_column: AO + expected_row_header: 125000 + table_record_kind: detail + filters: + family_scheme_income_band_source_label: 125000 + constraints: + - variable: family_scheme_income_band_source_label + operator: == + value: 125000 + label: Published Working for Families family-income band label + guard_cells: *income_table_guards + - value_id: income_label_130000 + label: 'Published family income band 130000' + ordinal: 25 + row_number: 37 + expected_row_header_column: AO + expected_row_header: 130000 + table_record_kind: detail + filters: + family_scheme_income_band_source_label: 130000 + constraints: + - variable: family_scheme_income_band_source_label + operator: == + value: 130000 + label: Published Working for Families family-income band label + guard_cells: *income_table_guards + - value_id: income_label_135000 + label: 'Published family income band 135000' + ordinal: 26 + row_number: 38 + expected_row_header_column: AO + expected_row_header: 135000 + table_record_kind: detail + filters: + family_scheme_income_band_source_label: 135000 + constraints: + - variable: family_scheme_income_band_source_label + operator: == + value: 135000 + label: Published Working for Families family-income band label + guard_cells: *income_table_guards + - value_id: income_label_140000 + label: 'Published family income band 140000' + ordinal: 27 + row_number: 39 + expected_row_header_column: AO + expected_row_header: 140000 + table_record_kind: detail + filters: + family_scheme_income_band_source_label: 140000 + constraints: + - variable: family_scheme_income_band_source_label + operator: == + value: 140000 + label: Published Working for Families family-income band label + guard_cells: *income_table_guards + - value_id: income_label_145000 + label: 'Published family income band 145000' + ordinal: 28 + row_number: 40 + expected_row_header_column: AO + expected_row_header: 145000 + table_record_kind: detail + filters: + family_scheme_income_band_source_label: 145000 + constraints: + - variable: family_scheme_income_band_source_label + operator: == + value: 145000 + label: Published Working for Families family-income band label + guard_cells: *income_table_guards + - value_id: income_label_150000 + label: 'Published family income band 150000' + ordinal: 29 + row_number: 41 + expected_row_header_column: AO + expected_row_header: 150000 + table_record_kind: detail + filters: + family_scheme_income_band_source_label: 150000 + constraints: + - variable: family_scheme_income_band_source_label + operator: == + value: 150000 + label: Published Working for Families family-income band label + guard_cells: *income_table_guards + - value_id: income_label_155000 + label: 'Published family income band 155000' + ordinal: 30 + row_number: 42 + expected_row_header_column: AO + expected_row_header: 155000 + table_record_kind: detail + filters: + family_scheme_income_band_source_label: 155000 + constraints: + - variable: family_scheme_income_band_source_label + operator: == + value: 155000 + label: Published Working for Families family-income band label + guard_cells: *income_table_guards + - value_id: income_label_160000 + label: 'Published family income band 160000' + ordinal: 31 + row_number: 43 + expected_row_header_column: AO + expected_row_header: 160000 + table_record_kind: detail + filters: + family_scheme_income_band_source_label: 160000 + constraints: + - variable: family_scheme_income_band_source_label + operator: == + value: 160000 + label: Published Working for Families family-income band label + guard_cells: *income_table_guards + - value_id: income_label_165000 + label: 'Published family income band 165000' + ordinal: 32 + row_number: 44 + expected_row_header_column: AO + expected_row_header: 165000 + table_record_kind: detail + filters: + family_scheme_income_band_source_label: 165000 + constraints: + - variable: family_scheme_income_band_source_label + operator: == + value: 165000 + label: Published Working for Families family-income band label + guard_cells: *income_table_guards + - value_id: income_label_170000 + label: 'Published family income band 170000' + ordinal: 33 + row_number: 45 + expected_row_header_column: AO + expected_row_header: 170000 + table_record_kind: detail + filters: + family_scheme_income_band_source_label: 170000 + constraints: + - variable: family_scheme_income_band_source_label + operator: == + value: 170000 + label: Published Working for Families family-income band label + guard_cells: *income_table_guards + - value_id: income_label_175000 + label: 'Published family income band 175000' + ordinal: 34 + row_number: 46 + expected_row_header_column: AO + expected_row_header: 175000 + table_record_kind: detail + filters: + family_scheme_income_band_source_label: 175000 + constraints: + - variable: family_scheme_income_band_source_label + operator: == + value: 175000 + label: Published Working for Families family-income band label + guard_cells: *income_table_guards + - value_id: income_label_180000 + label: 'Published family income band 180000' + ordinal: 35 + row_number: 47 + expected_row_header_column: AO + expected_row_header: 180000 + table_record_kind: detail + filters: + family_scheme_income_band_source_label: 180000 + constraints: + - variable: family_scheme_income_band_source_label + operator: == + value: 180000 + label: Published Working for Families family-income band label + guard_cells: *income_table_guards + - value_id: income_label_180000_plus + label: 'Published family income band 180,000+' + ordinal: 36 + row_number: 48 + expected_row_header_column: AO + expected_row_header: '180,000+' + table_record_kind: detail + filters: + family_scheme_income_band_source_label: '180,000+' + constraints: + - variable: family_scheme_income_band_source_label + operator: == + value: '180,000+' + label: Published Working for Families family-income band label + guard_cells: *income_table_guards + - value_id: income_unknown + label: 'Published family income band Unknown**' + ordinal: 37 + row_number: 49 + expected_row_header_column: AO + expected_row_header: 'Unknown**' + table_record_kind: detail + filters: + family_scheme_income_band_source_label: 'Unknown**' + constraints: + - variable: family_scheme_income_band_source_label + operator: == + value: 'Unknown**' + label: Published Working for Families family-income band label + guard_cells: *income_table_guards + - value_id: all_income_bands + label: 'Published family income band All' + ordinal: 38 + row_number: 51 + expected_row_header_column: AO + expected_row_header: All + table_record_kind: total + filters: + family_scheme_income_band_source_label: All + constraints: + - variable: family_scheme_income_band_source_label + operator: == + value: All + label: Published Working for Families family-income band label + guard_cells: *income_table_guards + measures: + - measure_id: wff_entitlement_nzd + label: Aggregate Working for Families entitlement by published family-income band + ordinal: 0 + column: AP + source_column_id: total_entitlement + expected_column_header_row: 11 + expected_column_header: "Total entitlement \n($million)" + concept: ird_wff_statistics.aggregate_entitlement + source_concept: ird_wff_statistics.aggregate_entitlement + concept_relation: source_label + concept_authority: ird + concept_evidence_url: https://www.ird.govt.nz/about-us/tax-statistics/working-for-families-statistics/working-for-families-statistics-datasets + concept_evidence_notes: >- + Publisher 2023-24 tax-year income table, All Working for Families credits column. + Family-income labels are preserved exactly, including Unknown and All; + numeric labels are not recoded to inferred interval boundaries. + The total includes credit components not separately shown in this table. + The workbook Explanatory notes define assessed family scheme income as an + entitlement-time-weighted average. For Work and Income recipients who did + not file a WFF return, IRD uses individual tax-return income, which + excludes partner income. + unit: nzd + aggregation: sum + value_scale: 1000000 + expected_cell_type: number + filters: {wff_credit_component: any} + constraints: + - {variable: wff_credit_component, operator: '==', value: any, label: All Working for Families credits} + - measure_id: ftc_entitlement_nzd + label: Aggregate Family Tax Credit entitlement by published family-income band + ordinal: 1 + column: AQ + source_column_id: ftc_entitlement + expected_column_header_row: 11 + expected_column_header: "FTC entitlement\n($million)" + concept: ird_wff_statistics.aggregate_entitlement + source_concept: ird_wff_statistics.aggregate_entitlement + concept_relation: source_label + concept_authority: ird + concept_evidence_url: https://www.ird.govt.nz/about-us/tax-statistics/working-for-families-statistics/working-for-families-statistics-datasets + concept_evidence_notes: >- + Publisher 2023-24 tax-year income table, Family Tax Credit column. + Family-income labels are preserved exactly, including Unknown and All; + numeric labels are not recoded to inferred interval boundaries. + The total includes credit components not separately shown in this table. + The workbook Explanatory notes define assessed family scheme income as an + entitlement-time-weighted average. For Work and Income recipients who did + not file a WFF return, IRD uses individual tax-return income, which + excludes partner income. + unit: nzd + aggregation: sum + value_scale: 1000000 + expected_cell_type: number + filters: {wff_credit_component: ftc} + constraints: + - {variable: wff_credit_component, operator: '==', value: ftc, label: Family Tax Credit} + - measure_id: iwtc_entitlement_nzd + label: Aggregate In-work Tax Credit entitlement by published family-income band + ordinal: 2 + column: AR + source_column_id: iwtc_entitlement + expected_column_header_row: 11 + expected_column_header: "IWTC entitlement\n($million)" + concept: ird_wff_statistics.aggregate_entitlement + source_concept: ird_wff_statistics.aggregate_entitlement + concept_relation: source_label + concept_authority: ird + concept_evidence_url: https://www.ird.govt.nz/about-us/tax-statistics/working-for-families-statistics/working-for-families-statistics-datasets + concept_evidence_notes: >- + Publisher 2023-24 tax-year income table, In-work Tax Credit column. + Family-income labels are preserved exactly, including Unknown and All; + numeric labels are not recoded to inferred interval boundaries. + The total includes credit components not separately shown in this table. + The workbook Explanatory notes define assessed family scheme income as an + entitlement-time-weighted average. For Work and Income recipients who did + not file a WFF return, IRD uses individual tax-return income, which + excludes partner income. + unit: nzd + aggregation: sum + value_scale: 1000000 + expected_cell_type: number + filters: {wff_credit_component: iwtc} + constraints: + - {variable: wff_credit_component, operator: '==', value: iwtc, label: In-work Tax Credit} + - measure_id: bstc_entitlement_nzd + label: Aggregate Best Start Tax Credit entitlement by published family-income band + ordinal: 3 + column: AS + source_column_id: bstc_entitlement + expected_column_header_row: 11 + expected_column_header: "BSTC entitlement\n($million)" + concept: ird_wff_statistics.aggregate_entitlement + source_concept: ird_wff_statistics.aggregate_entitlement + concept_relation: source_label + concept_authority: ird + concept_evidence_url: https://www.ird.govt.nz/about-us/tax-statistics/working-for-families-statistics/working-for-families-statistics-datasets + concept_evidence_notes: >- + Publisher 2023-24 tax-year income table, Best Start Tax Credit column. + Family-income labels are preserved exactly, including Unknown and All; + numeric labels are not recoded to inferred interval boundaries. + The total includes credit components not separately shown in this table. + The workbook Explanatory notes define assessed family scheme income as an + entitlement-time-weighted average. For Work and Income recipients who did + not file a WFF return, IRD uses individual tax-return income, which + excludes partner income. + unit: nzd + aggregation: sum + value_scale: 1000000 + expected_cell_type: number + filters: {wff_credit_component: bstc} + constraints: + - {variable: wff_credit_component, operator: '==', value: bstc, label: Best Start Tax Credit} + - measure_id: wff_recipient_families + label: Families with at least one Working for Families credit by published family-income band + ordinal: 4 + column: AT + source_column_id: wff_count + expected_column_header_row: 11 + expected_column_header: "Count of WFF " + concept: ird_wff_statistics.recipient_families + source_concept: ird_wff_statistics.recipient_families + concept_relation: source_label + concept_authority: ird + concept_evidence_url: https://www.ird.govt.nz/about-us/tax-statistics/working-for-families-statistics/working-for-families-statistics-datasets + concept_evidence_notes: >- + Publisher 2023-24 tax-year income table, At least one Working for Families credit column. + Family-income labels are preserved exactly, including Unknown and All; + numeric labels are not recoded to inferred interval boundaries. + The total includes credit components not separately shown in this table. + The workbook Explanatory notes define assessed family scheme income as an + entitlement-time-weighted average. For Work and Income recipients who did + not file a WFF return, IRD uses individual tax-return income, which + excludes partner income. + unit: count + aggregation: sum + value_scale: 1 + expected_cell_type: number + filters: {wff_credit_component: any} + constraints: + - {variable: wff_credit_component, operator: '==', value: any, label: At least one Working for Families credit} + - measure_id: ftc_recipient_families + label: Families with non-zero Family Tax Credit entitlement by published family-income band + ordinal: 5 + column: AU + source_column_id: ftc_count + expected_column_header_row: 11 + expected_column_header: "Count of FTC" + concept: ird_wff_statistics.recipient_families + source_concept: ird_wff_statistics.recipient_families + concept_relation: source_label + concept_authority: ird + concept_evidence_url: https://www.ird.govt.nz/about-us/tax-statistics/working-for-families-statistics/working-for-families-statistics-datasets + concept_evidence_notes: >- + Publisher 2023-24 tax-year income table, Family Tax Credit column. + Family-income labels are preserved exactly, including Unknown and All; + numeric labels are not recoded to inferred interval boundaries. + The total includes credit components not separately shown in this table. + The workbook Explanatory notes define assessed family scheme income as an + entitlement-time-weighted average. For Work and Income recipients who did + not file a WFF return, IRD uses individual tax-return income, which + excludes partner income. + unit: count + aggregation: sum + value_scale: 1 + expected_cell_type: number + filters: {wff_credit_component: ftc} + constraints: + - {variable: wff_credit_component, operator: '==', value: ftc, label: Family Tax Credit} + - measure_id: iwtc_recipient_families + label: Families with non-zero In-work Tax Credit entitlement by published family-income band + ordinal: 6 + column: AV + source_column_id: iwtc_count + expected_column_header_row: 11 + expected_column_header: "Count of IWTC" + concept: ird_wff_statistics.recipient_families + source_concept: ird_wff_statistics.recipient_families + concept_relation: source_label + concept_authority: ird + concept_evidence_url: https://www.ird.govt.nz/about-us/tax-statistics/working-for-families-statistics/working-for-families-statistics-datasets + concept_evidence_notes: >- + Publisher 2023-24 tax-year income table, In-work Tax Credit column. + Family-income labels are preserved exactly, including Unknown and All; + numeric labels are not recoded to inferred interval boundaries. + The total includes credit components not separately shown in this table. + The workbook Explanatory notes define assessed family scheme income as an + entitlement-time-weighted average. For Work and Income recipients who did + not file a WFF return, IRD uses individual tax-return income, which + excludes partner income. + unit: count + aggregation: sum + value_scale: 1 + expected_cell_type: number + filters: {wff_credit_component: iwtc} + constraints: + - {variable: wff_credit_component, operator: '==', value: iwtc, label: In-work Tax Credit} + - measure_id: bstc_recipient_families + label: Families with non-zero Best Start Tax Credit entitlement by published family-income band + ordinal: 7 + column: AW + source_column_id: bstc_count + expected_column_header_row: 11 + expected_column_header: "Count of BSTC" + concept: ird_wff_statistics.recipient_families + source_concept: ird_wff_statistics.recipient_families + concept_relation: source_label + concept_authority: ird + concept_evidence_url: https://www.ird.govt.nz/about-us/tax-statistics/working-for-families-statistics/working-for-families-statistics-datasets + concept_evidence_notes: >- + Publisher 2023-24 tax-year income table, Best Start Tax Credit column. + Family-income labels are preserved exactly, including Unknown and All; + numeric labels are not recoded to inferred interval boundaries. + The total includes credit components not separately shown in this table. + The workbook Explanatory notes define assessed family scheme income as an + entitlement-time-weighted average. For Work and Income recipients who did + not file a WFF return, IRD uses individual tax-return income, which + excludes partner income. + unit: count + aggregation: sum + value_scale: 1 + expected_cell_type: number + filters: {wff_credit_component: bstc} + constraints: + - {variable: wff_credit_component, operator: '==', value: bstc, label: Best Start Tax Credit} diff --git a/tests/test_chronicle_bundle.py b/tests/test_chronicle_bundle.py index 6a00ef8..4429a60 100644 --- a/tests/test_chronicle_bundle.py +++ b/tests/test_chronicle_bundle.py @@ -69,20 +69,22 @@ def test_build_bundle_writes_merged_consumer_contract(tmp_path): assert report.valid assert summary["valid"] + # NZ WFF adds 330 TY2024 facts: 329 families and 1 person, in one new + # publisher/package/country. Its measured source-only delta has no duplicates. assert summary["counts"] == { "aggregate_duplicate_key_count": 0, "entity_count": 12, "error_count": 0, - "fact_count": 171855, - "geography_count": 12536, + "fact_count": 172185, + "geography_count": 12537, "period_count": 192, "semantic_duplicate_key_count": 121, "skipped_source_count": 10, - "source_count": 43, - "source_package_count": 151, + "source_count": 44, + "source_package_count": 152, "warning_count": 1, } - assert len(rows) == 171855 + assert len(rows) == 172185 assert {row["provenance_class"] for row in rows} <= { "administrative", "census", @@ -100,7 +102,7 @@ def test_build_bundle_writes_merged_consumer_contract(tmp_path): ) assert rows[0]["aggregate_fact_key"].startswith("ledger.aggregate_fact.v2:") assert rows[0]["semantic_fact_key"].startswith("ledger.semantic_fact.v2:") - assert source_packages["source_package_count"] == 151 + assert source_packages["source_package_count"] == 152 assert source_packages["skipped_source_count"] == 10 assert sorted(item["source"] for item in source_packages["skipped_sources"]) == [ "census-acs-s0101-congressional-district-age-2024", @@ -114,7 +116,7 @@ def test_build_bundle_writes_merged_consumer_contract(tmp_path): "jct-obbba-revenue-estimates-2025", "jct-tax-expenditures-2024", ] - assert coverage["fact_count"] == 171855 + assert coverage["fact_count"] == 172185 assert coverage["counts"]["by_source"] == { "bea": 445, "bfp_economic_outlook": 5, @@ -135,6 +137,7 @@ def test_build_bundle_writes_merged_consumer_contract(tmp_path): "hhs_acf_tanf": 110, "hmrc": 20551, "ici": 12, + "ird": 330, "irs_soi": 40063, "isc": 2, "jrc_euromod_be": 90, @@ -161,7 +164,8 @@ def test_build_bundle_writes_merged_consumer_contract(tmp_path): "welshgov": 216, } table_counts = coverage["counts"]["by_source_table"] - assert len(table_counts) == 146 + assert len(table_counts) == 147 + assert table_counts["ird:Working for Families statistics - September 2025"] == 330 assert ( table_counts[ "dwp:Universal Credit childcare element statistics to August 2025, Table 1" @@ -673,8 +677,9 @@ def test_build_bundle_writes_merged_consumer_contract(tmp_path): "tax_year:2021": 9, "tax_year:2022": 41237, "tax_year:2023": 63054, - "tax_year:2024": 40, + "tax_year:2024": 370, } + assert coverage["counts"]["by_geography"]["country:NZ"] == 330 assert coverage["counts"]["by_geography"]["country:BE"] == 4888 assert coverage["counts"]["by_geography"]["country:DE"] == 36 assert coverage["counts"]["by_geography"]["country:FR"] == 36 @@ -689,17 +694,17 @@ def test_build_bundle_writes_merged_consumer_contract(tmp_path): ) assert coverage["counts"]["by_geography"]["country:K02000001"] == 4297 assert coverage["counts"]["by_geography"]["country:K03000001"] == 497 - assert len(coverage["counts"]["by_geography"]) == 12536 + assert len(coverage["counts"]["by_geography"]) == 12537 assert coverage["counts"]["by_entity"] == { "benefit_unit": 233, "dwelling": 12733, - "family": 107, + "family": 436, "firm": 1439, "government": 1313, "household": 40724, "institutional_sector": 133, "pension_plan": 2, - "person": 60466, + "person": 60467, "return": 14600, "social_protection_scheme": 36, "tax_unit": 40069, diff --git a/tests/test_nz_targets.py b/tests/test_nz_targets.py new file mode 100644 index 0000000..c9f34f1 --- /dev/null +++ b/tests/test_nz_targets.py @@ -0,0 +1,383 @@ +"""Publisher-fidelity tests for New Zealand Chronicle source packages.""" + +from __future__ import annotations + +from collections import Counter +from dataclasses import replace +from decimal import Decimal +from functools import lru_cache +import hashlib +from pathlib import Path + +import pytest +import yaml + +from chronicle.bundle import build_bundle_coverage +from chronicle.consumer_contract import ( + consumer_fact_rows, + validate_consumer_fact_contract, +) +from chronicle.core import validate_facts +from chronicle.source_package import ( + SOURCE_PACKAGE_ALIASES, + load_source_package, + validate_source_package, +) +from chronicle.sources import build_source_cell_key, validate_source_cells +from chronicle.suite import build_source_suite + + +REPO_ROOT = Path(__file__).resolve().parents[1] +WFF_ALIAS = "ird-working-for-families-statistics-sept-2025" +WFF_DIRECTORY = Path("ird/working_for_families_statistics_sept_2025") +WFF_FILENAME = "working-for-families-statistics---sept-2025.xlsx" +WFF_SHA256 = "95ae66f4d44f3f47ea3daa006328b22f061a163cf7e31b487342cde649390833" +WFF_R2_KEY = f"raw/nz/ird/{WFF_ALIAS}/2024/{WFF_SHA256}/{WFF_FILENAME}" +WFF_SOURCE_URL = ( + "https://www.ird.govt.nz/-/media/project/ir/home/documents/about-us/" + "tax-statistics---current/social-policy/wff-stats/" + f"{WFF_FILENAME}?modified=20251111195236" +) +DATA_SHEET = "Working for families data" +INCOME_SHEET = "Working for families income" +RECORD_PREFIX = "ird_wff_statistics.ty2024" + + +@lru_cache +def _package(): + return load_source_package(WFF_ALIAS) + + +@lru_cache +def _cells(): + return _package().build_source_cells(2024) + + +@lru_cache +def _facts(): + return _package().build_facts(2024, cells=_cells()) + + +@lru_cache +def _records(): + return _package().build_source_records(2024, cells=_cells()) + + +def _fact(record_set, row, measure): + record_id = f"{RECORD_PREFIX}.{record_set}.{row}.{measure}" + return next(fact for fact in _facts() if fact.source_record_id == record_id) + + +def test_wff_alias_and_package_shape(): + assert SOURCE_PACKAGE_ALIASES[WFF_ALIAS] == WFF_DIRECTORY + assert _package().package_id == WFF_ALIAS + report = validate_source_package(WFF_ALIAS, year=2024) + assert report.valid + assert not report.warnings + assert report.counts == { + "record_set_count": 5, + "row_count": 43, + "measure_count": 26, + "source_record_count": 330, + "source_region_count": 5, + } + + +def test_wff_official_artifact_is_pinned(): + data_dir = REPO_ROOT / "db" / "data" / WFF_DIRECTORY + manifest = yaml.safe_load((data_dir / "manifest.yaml").read_text()) + artifact = manifest["files"][2024] + path = data_dir / WFF_FILENAME + + assert manifest["source_id"] == "ird" + assert manifest["package_id"] == WFF_ALIAS + assert artifact["filename"] == WFF_FILENAME + assert artifact["source_url"] == WFF_SOURCE_URL + assert artifact["sha256"] == WFF_SHA256 + assert hashlib.sha256(path.read_bytes()).hexdigest() == WFF_SHA256 + assert path.stat().st_size == artifact["size_bytes"] == 71_211 + + +def test_wff_r2_provenance_and_consumer_contract(): + data_dir = REPO_ROOT / "db" / "data" / WFF_DIRECTORY + manifest = yaml.safe_load((data_dir / "manifest.yaml").read_text()) + storage = manifest["files"][2024]["storage"]["r2"] + assert storage == { + "provider": "r2", + "bucket": "ledger-raw", + "key": WFF_R2_KEY, + "uri": f"r2://ledger-raw/{WFF_R2_KEY}", + } + assert {fact.source.raw_r2_uri for fact in _facts()} == {storage["uri"]} + assert validate_consumer_fact_contract(_facts()).valid + + +def test_wff_build_suite_passes_all_source_acceptance_gates(tmp_path): + report = build_source_suite(WFF_ALIAS, tmp_path / "suite", year=2024) + assert report.valid + assert report.agent_acceptance.valid + assert all(report.agent_acceptance.checks.values()) + assert not report.agent_acceptance.errors + assert report.source_records.resolved_count == 330 + assert report.source_records.lineage_coverage == 1 + assert report.source_cells.cell_count == 4910 + assert report.consumer_facts.fact_count == 330 + assert report.agent_acceptance.counts["raw_artifact_count"] == 1 + assert report.agent_acceptance.counts["raw_r2_link_count"] == 1 + + +def test_wff_bundle_coverage_delta_has_no_duplicate_keys(): + coverage = build_bundle_coverage(consumer_fact_rows(_facts())) + assert coverage["fact_count"] == 330 + assert coverage["counts"]["by_source"] == {"ird": 330} + assert coverage["counts"]["by_period"] == {"tax_year:2024": 330} + assert coverage["counts"]["by_geography"] == {"country:NZ": 330} + assert coverage["counts"]["by_entity"] == {"family": 329, "person": 1} + assert coverage["counts"]["by_source_table"] == { + "ird:Working for Families statistics - September 2025": 330 + } + assert coverage["duplicates"] == { + "aggregate_fact_keys": [], + "semantic_fact_keys": [], + } + + +def test_wff_source_cells_and_fact_lineage_are_complete(): + cells = _cells() + facts = _facts() + assert len(cells) == 4910 + assert {cell.sheet_name for cell in cells} == {DATA_SHEET, INCOME_SHEET} + assert validate_source_cells(cells).valid + assert len(facts) == 330 + assert validate_facts(facts).valid + assert Counter(fact.entity.name for fact in facts) == { + "family": 329, + "person": 1, + } + assert {fact.provenance_class for fact in facts} == {"administrative"} + assert {fact.assertion for fact in facts} == {"observation"} + assert {fact.source.source_name for fact in facts} == {"ird"} + assert {fact.source.source_sha256 for fact in facts} == {WFF_SHA256} + assert {fact.source.url for fact in facts} == {WFF_SOURCE_URL} + assert {fact.measure.unit for fact in facts} == {"count", "nzd"} + assert {fact.measure.concept_relation for fact in facts} == {"source_label"} + cell_keys = {build_source_cell_key(cell) for cell in cells} + assert all(fact.source_cell_keys for fact in facts) + assert all(set(fact.source_cell_keys) <= cell_keys for fact in facts) + + # Every emitted value is one publisher cell with a declared unit scale; + # there is no interpolation, inferred residual, ratio, or reconciliation. + cells_by_address = {(cell.sheet_name, cell.address): cell for cell in cells} + records_by_id = {record.source_record_id: record for record in _records()} + for fact in facts: + record = records_by_id[fact.source_record_id] + selector = record.spec.selector + assert selector.end_address is None + assert record.spec.divisor_selector is None + raw_value = cells_by_address[(selector.sheet_name, selector.address)].raw_value + assert Decimal(str(fact.value)) == ( + Decimal(str(raw_value)) * Decimal(str(record.spec.value_scale)) + ) + + +def test_wff_nz_tax_year_and_country_are_explicit(): + for fact in _facts(): + assert (fact.period.type, fact.period.value) == ("tax_year", 2024) + assert (fact.geography.level, fact.geography.id) == ("country", "NZ") + coverage = fact.period_coverage + assert coverage.start_date == "2023-04-01" + assert coverage.end_date == "2024-03-31" + assert coverage.basis == "tax" + assert coverage.source_period_label == "2024 Tax Year / 2023-24 Tax Year" + assert coverage.accounting_basis is None + assert "not an estimate of all eligible families" in coverage.notes + + # A generic bundle's requested year must not relabel the fixed source year. + assert { + (fact.period.type, fact.period.value) + for fact in _package().build_facts(2023, cells=_cells()) + } == {("tax_year", 2024)} + + +@pytest.mark.parametrize( + ("component", "families", "entitlement"), + [ + ("ftc", 252_500, 2_273_000_000), + ("mftc", 2_600, 12_000_000), + ("iwtc", 150_500, 437_000_000), + ("bstc", 137_200, 320_000_000), + ("wff", 328_400, 3_043_000_000), + ], +) +def test_wff_national_credit_counts_and_entitlements(component, families, entitlement): + count = _fact("recipient_families", "all", f"{component}_recipient_families") + amount = _fact("aggregate_entitlements", "all", f"{component}_entitlement_nzd") + assert count.value == families + assert amount.value == entitlement + assert count.filters["wff_entitlement_status"] == "nonzero" + assert count.entity.role == amount.entity.role == "wff_entitled_family" + assert count.filters["wff_credit_component"] == ( + "any" if component == "wff" else component + ) + + +def test_wff_supported_children_and_family_sizes_remain_distinct(): + child_total = _fact("supported_children", "all", "wff_supported_children") + assert child_total.value == 656_500 + assert child_total.entity.name == "person" + counts = (136_600, 107_800, 50_900, 20_700, 7_700, 2_800, 1_100) + for child_count, expected in enumerate(counts, start=1): + suffix = ( + "1_child" + if child_count == 1 + else "7_plus_children" + if child_count == 7 + else f"{child_count}_children" + ) + fact = _fact( + "recipient_families_by_child_count", "all", f"wff_families_{suffix}" + ) + assert fact.value == expected + assert fact.entity.name == "family" + constraint = next( + c for c in fact.constraints if c.variable == "supported_child_count" + ) + assert constraint.value == child_count + assert constraint.unit == "children" + assert constraint.operator == (">=" if child_count == 7 else "==") + # Preserve distinct published counts; do not force one table to match another. + assert ( + sum(counts) + != _fact("recipient_families", "all", "wff_recipient_families").value + ) + + +def test_wff_complete_published_income_table_preserves_source_labels(): + facts = [ + fact + for fact in _facts() + if fact.layout.record_set_id == f"{RECORD_PREFIX}.income_distribution" + ] + assert len(facts) == 39 * 8 + assert Counter(fact.layout.measure_id for fact in facts) == { + f"{component}_{measure}": 39 + for component in ("wff", "ftc", "iwtc", "bstc") + for measure in ("entitlement_nzd", "recipient_families") + } + expected_labels = {*range(5_000, 180_001, 5_000), "180,000+", "Unknown**", "All"} + assert { + fact.filters["family_scheme_income_band_source_label"] for fact in facts + } == expected_labels + for fact in facts: + constraints = [ + constraint + for constraint in fact.constraints + if constraint.variable == "family_scheme_income_band_source_label" + ] + assert len(constraints) == 1 + assert constraints[0].operator == "==" + assert ( + constraints[0].value + == fact.filters["family_scheme_income_band_source_label"] + ) + assert "numeric labels are not recoded" in fact.measure.concept_evidence_notes + assert fact.layout.table_record_kind == ( + "total" if fact.layout.groupby_value_id == "all_income_bands" else "detail" + ) + + +def test_wff_income_definition_preserves_publisher_qualifications(): + facts = [ + fact + for fact in _facts() + if fact.layout.record_set_id == f"{RECORD_PREFIX}.income_distribution" + ] + checklist = (REPO_ROOT / "docs" / "pe-nz-source-checklist.md").read_text() + for notes in [checklist, *(fact.measure.concept_evidence_notes for fact in facts)]: + normalized = " ".join(notes.lower().split()) + assert "entitlement-time-weighted" in normalized + assert "work and income" in normalized + assert "individual tax-return income" in normalized + assert "excludes partner income" in normalized + + +@pytest.mark.parametrize( + ("row", "counts", "amounts"), + [ + ( + "income_label_5000", + (2690, 2650, 810, 940), + (20_780_000, 16_750_000, 2_330_000, 1_700_000), + ), + ( + "income_label_180000_plus", + (16150, 210, 180, 15960), + (18_370_000, 340_000, 190_000, 17_840_000), + ), + ( + "income_unknown", + (3390, 2630, 1930, 1340), + (28_020_000, 20_790_000, 4_450_000, 2_700_000), + ), + ( + "all_income_bands", + (328400, 252500, 150500, 137200), + (3_043_000_000, 2_273_000_000, 437_000_000, 320_000_000), + ), + ], +) +def test_wff_income_table_exact_anchor_rows(row, counts, amounts): + for component, count, amount in zip( + ("wff", "ftc", "iwtc", "bstc"), counts, amounts + ): + assert ( + _fact("income_distribution", row, f"{component}_recipient_families").value + == count + ) + assert ( + _fact("income_distribution", row, f"{component}_entitlement_nzd").value + == amount + ) + + +def test_wff_income_rounding_adjustments_are_not_population_facts(): + cells = {cell.address: cell for cell in _cells() if cell.sheet_name == INCOME_SHEET} + assert cells["AO50"].raw_value == "Rounding adjustment" + assert cells["AO53"].raw_value == ( + "** Income is unknown for families that have not filed a Working for Families return." + ) + for column, adjustment in zip( + ("AP", "AQ", "AR", "AS", "AT", "AU", "AV", "AW"), + (-0.43, 0.82, 0.43, -0.2, 50, 100, 180, 50), + ): + assert cells[f"{column}50"].raw_value == pytest.approx(adjustment) + detail = sum(cells[f"{column}{row}"].raw_value for row in range(12, 50)) + # IRD reports detail minus total, not an additive population row. + assert detail - cells[f"{column}50"].raw_value == pytest.approx( + cells[f"{column}51"].raw_value + ) + assert all( + record.spec.selector.sheet_name != INCOME_SHEET + or not record.spec.selector.address.endswith("50") + for record in _records() + ) + + +@pytest.mark.parametrize( + ("sheet", "address", "message"), + [ + (DATA_SHEET, "A27", "row header"), + (DATA_SHEET, "B92", "column header"), + (INCOME_SHEET, "AO10", "income table tax-year label"), + (INCOME_SHEET, "AO52", "income table population footnote"), + ], +) +def test_wff_header_guards_reject_drift(sheet, address, message): + changed_cells = [ + replace(cell, raw_value="unexpected publisher layout") + if (cell.sheet_name, cell.address) == (sheet, address) + else cell + for cell in _cells() + ] + with pytest.raises(ValueError, match=message): + _package().build_facts(2024, cells=changed_cells)