Stats NZ regional resident population at 30 June 2023 (NZ, G8-d4)

changelog.d/nz-regional-population-2023.added.md

@@ -0,0 +1,5 @@
+Add 17 Stats NZ estimated resident population facts at 30 June 2023: the
+16 regions and the directly published New Zealand total from Table 1's
+unmarked 2023 column in the existing pinned October 2025 workbook. Preserve
+the source's reference date, 2023 census base, REGC 2025 geographies and
+unmarked status; compute no ratios, growth rates or aligned values.

docs/pe-nz-population-source-notes.md

@@ -3,7 +3,8 @@
 This records the bounded source-ingestion work for demographic packages 1 and 2
 of [issue #176](https://github.com/PolicyEngine/chronicle/issues/176), checked on
 30 August 2026 UTC, with G8-d2 territorial-authority evidence added on
-13 October 2026 UTC. It does not mark the demographic target surface complete.
+13 October 2026 UTC and G8-d4's 2023-reference-date cells verified locally on
+22 October 2026 UTC. It does not mark the demographic target surface complete.
 
 ## Pinned publisher evidence
 
@@ -32,8 +33,9 @@ The NZ hub published the TA 2025 classification to its declared R2 key on
 13 October 2026 and verified it by streaming the remote object back: its
 SHA-256 matched the manifest. The workbook and its existing manifest are
 unchanged.
-The two population references share a 30 June 2025 reference date, not a
-publication date. The national landing page is evidence of the missing download
+The two population release titles refer to 30 June 2025, not their
+publication dates; the subnational workbook also publishes historical 2023
+and 2024 estimates. The national landing page is evidence of the missing download
 surface, **not** a single-year-age data artifact or a national source package.
 Both classifications are geography evidence only and emit no population facts.
 
@@ -69,11 +71,44 @@ authority areas; published rounding also qualifies comparisons with the
 territorial-authority figures. No total, Auckland local-board sum, residual,
 share, aging, imputation, or reconciliation is computed or emitted.
 
+## G8-d4: regional population at 30 June 2023
+
+The existing [regional package](../packages/stats_nz/subnational_population_estimates_2025/README.md)
+also reads Table 1!B7:B22 and B25: 16 regional council areas and the separately
+published New Zealand total. These 17 all-age ERP facts use `calendar_year: 2023`
+and equal coverage dates `2023-06-30`. Each is one publisher cell at scale 1,
+with the same ERP concept, REGC codes/names, `regc_2025` regional vintage,
+`provenance_class: census`, and `assertion: observation` as the 2025 facts.
+The national geography remains `country:NZ`, vintage `current`.
+
+Verified with openpyxl `data_only`: A3 is `Regional council areas`; A4 is
+`At 30 June 2023–2025`; A5 is `Regional council area(2)`; B5 is `At 30 June`;
+B6 is numeric `2023`, with no `P`. C6 and D6 are `2024 P` and `2025 P`.
+Samples are Northland 198,500 (B7), Auckland 1,755,200 (B8), Wellington
+538,000 (B15), Canterbury 676,600 (B20), Southland 102,700 (B22), and New
+Zealand 5,200,000 (B25). All 17 cells are compared directly in the tests.
+
+The Contents sheet and workbook footnotes do not explicitly call 2023 final or
+revised. Table 1!A34 defines `P provisional`; the unmarked B6 header is retained
+without assigning provisional, final or revised status. A26:A28 define ERP
+using the 2023 census usually resident population count, adjusted for net
+census under/overcount, residents temporarily overseas, and births, deaths
+and net migration up to the estimate date. These 2023 estimates are the
+release's 2023-base series, not the 7 March 2023 census-night count.
+
+Guards cover A3, A4, A5, B5, numeric B6, every selected row header, the
+1 January 2025 boundary footnote A29, and the P-symbol definition A34.
+Rows 23–24 (island subtotals), the 2024 P column and population-change columns
+remain preserved source cells without facts. No new source artifact is added;
+the workbook, manifest, 2,265 parsed cells, and the existing 85 facts are
+unchanged. The package constructs no ratios, growth rates or aligned values.
+
 ## S7: partial workbook package
 
 The [source package](../packages/stats_nz/subnational_population_estimates_2025/README.md)
-admits 85 cells from Tables 1 and 3: 17 geographic rows × all ages/four broad
-age bands. Its precise scope, semantics, and guards are documented there.
+admits 102 cells from Tables 1 and 3: 85 at 30 June 2025 (17 geographic rows ×
+all ages/four broad age bands), plus the 17 G8-d4 all-age cells at 30 June 2023.
+Its precise scope, semantics, and guards are documented there.
 
 The workbook does not contain the requested five-year-age × sex × region cut.
 Stats NZ's public metadata catalog lists `POPES_SUB_004`:
@@ -97,7 +132,7 @@ revision vintage before it can extend this package. In particular,
 `POPES_SUB_003` advertises **2026 boundaries** and is not a substitute.
 
 The regional five-year-age × sex table is a **follow-up**, not part of this
-package. This package lands only the 85 partial counts above. The follow-up
+package. This package lands only the 102 partial counts above. The follow-up
 extends it once an authorized export passes those checks; until then the
 package emits no five-year-age or sex-specific fact.
 
@@ -129,14 +164,14 @@ registered, and the national facts count added by S8 is **zero**.
 The partial S7 package passes source-package validation, exact source-cell
 comparisons, geography mapping checks, source-semantic drift tests, consumer
 contract validation, and an explicit one-package build. The bounded source
-build records 85/85 lineaged facts and 2,265 parsed cells.
+build records 102/102 lineaged facts and 2,265 parsed cells.
 
 The source build warns that Axiom CLI canonical-concept validation did not run.
 All mappings are source-label relations; this work claims neither Axiom
 canonical certification nor calibration quality.
 
 Microcosm retains responsibility for choosing constraints, reconciling source
 universes, aging, imputing, constructing solver targets, and activating a
-population. The 85 counts are available source facts, not proof that these
+population. The 102 counts are available source facts, not proof that these
 downstream steps have run. Independent source-fidelity and boundary review is
 still required before landing.

docs/pe-nz-source-checklist.md

@@ -53,7 +53,7 @@ tests, and record a verified `raw/nz/...` R2 URI.
 
 | Package from #176 | Artifact pinned | Package valid | `raw/nz` verified | Notes |
 |---|---:|---:|---:|---|
-| `stats_nz/subnational_population_estimates_2025` | [x] | [ ] | [x] | **Partial:** 85 validated workbook counts (16 regions + published NZ total; all ages/four broad age bands). Five-year-age × sex coverage is missing; its ADE structure request returned HTTP 401. Package-completion box stays unchecked. [Evidence and access notes](pe-nz-population-source-notes.md). |
+| `stats_nz/subnational_population_estimates_2025` | [x] | [ ] | [x] | **Partial:** 102 workbook counts: 85 at 30 June 2025 (16 regions + published NZ total; all ages/four broad age bands), plus G8-d4's 17 all-age counts at 30 June 2023 from Table 1!B7:B22 and B25. The 2023 header has no P; Contents and workbook footnotes do not explicitly call 2023 final or revised. Same pinned workbook and REGC 2025 geographies; no new artifact, ratios or alignment. Five-year-age × sex coverage is missing; its ADE structure request returned HTTP 401. Package-completion box stays unchecked. [Evidence and access notes](pe-nz-population-source-notes.md). |
 | `stats_nz/subnational_population_ta_2025` | [x] | [x] | [x] | G8-d2: 67 provisional all-age estimated resident populations at 30 June 2025, one Table 2!E cell per territorial authority; `local_authority`, `nz-ta-NNN`, `ta_2025`. Same unchanged workbook; codes and names come from the pinned 68-feature Stats NZ TA 2025 classification. The hub published the classification to its `raw/nz/stats_nz/...` key and verified it by SHA-256 on 2026-10-13. Local boards, previous years, change/percent columns and the duplicate NZ row are preserved but not emitted; no sums or reconciliation. [Scope](../packages/stats_nz/subnational_population_ta_2025/README.md) and [evidence](pe-nz-population-source-notes.md). |
 | `stats_nz/national_population_estimates_2025` | [ ] | [ ] | [ ] | **Blocked:** no original-vintage single-year-age artifact acquired. The 19 August 2025 release points to Infoshare, not an XLSX. Landing-page evidence only is hash-pinned in `raw/nz`; it emits zero facts. [Evidence and access notes](pe-nz-population-source-notes.md). |
 | `stats_nz/census_2023_households_by_region` | [x] | [ ] | [x] | **Partial:** B5: 216 published 2023 Census counts, 12 per place (NZ, 16 regional councils and separate Area Outside Region): households, three tenure categories and eight usual-resident household sizes. Requested household composition and social-renting split are absent from this product. #176 named the S2 ArcGIS hub regional-council layer as the source; the published ArcGIS household and family layers are SA1/SA2 only, so regional household composition needs the Aotearoa Data Explorer (`CEN23_FHH_038`, API key or manual export) and stays open. Package-completion box stays unchecked until then. National root plus per-place members share the 18 unchanged receipt-pinned CSVs with the family package; the hub published the 18 objects to their `raw/nz/stats_nz/...` keys and verified each by SHA-256 on 2026-10-10. [Scope and evidence](../packages/stats_nz/census_2023_households_by_region/README.md). |

packages/stats_nz/subnational_population_estimates_2025/README.md

@@ -1,15 +1,17 @@
-# Stats NZ subnational population, 30 June 2025 — partial
+# Stats NZ subnational population, 30 June 2023 and 2025 — partial
 
-This package emits 85 publisher-backed population counts: the 16 regional
+This package emits 102 publisher-backed population counts: the 16 regional
 council areas and the separately published New Zealand total, each for all ages
-and the four source age bands. It does **not** complete the five-year-age × sex ×
+at 30 June 2023 and 2025, plus the four source age bands at 30 June 2025.
+It does **not** complete the five-year-age × sex ×
 region surface requested by [issue #176](https://github.com/PolicyEngine/chronicle/issues/176).
 
 The [29 October 2025 release](https://www.stats.govt.nz/information-releases/subnational-population-estimates-at-30-june-2025/)
 and its unchanged XLSX provide these cells:
 
 | Source sheet | Exact selection | Facts |
 |---|---|---:|
+| Table 1 | B7:B22 and B25, headed numeric `2023` (no `P`) | 17 |
 | Table 1 | D7:D22 and D25, headed `2025 P` | 17 |
 | Table 3 | Columns D:G, rows 10, 13, 16, 19, 22, 25, 28, 31, 34, 37, 40, 43, 46, 49, 52, 55, 64 | 68 |
 
@@ -19,35 +21,43 @@ worksheets are parsed over their complete used ranges (2,265 cells), including
 unselected years and explanatory footnotes. Territorial-authority all-age
 counts from Table 2 are ingested separately by
 [subnational_population_ta_2025](../subnational_population_ta_2025/README.md).
-Local-board tables, island subtotals, percentages, median ages, and
-population-change components are not ingested by this package.
+The `2024 P` column, local-board tables, island subtotals, percentages, median
+ages, and population-change components are not ingested by this package.
 
 ## Reference period and population definition
 
-- Reference date: **30 June 2025**, expressed as `calendar_year: 2025` plus
-  equal start/end coverage dates `2025-06-30`. These are point-in-time counts,
+- Reference dates: **30 June 2023** and **30 June 2025**, expressed as
+  `calendar_year: 2023` / `2025` plus equal start/end coverage dates
+  `2023-06-30` / `2025-06-30`, respectively. These are point-in-time counts,
   not annual average populations.
-- Publication vintage: **29 October 2025**; all selected figures are
-  **provisional**. The source artifact remains pinned even if Stats NZ later
-  revises its historical estimates.
+- Publication vintage: **29 October 2025**. The selected **2025** figures are
+  **provisional**. Table 1!B6 is numeric `2023` without a `P` marker, so the
+  2023 facts are not marked provisional. The workbook's Contents and footnotes
+  do not explicitly label 2023 final or revised; neither status is added.
+  The source artifact remains pinned even if Stats NZ later revises its
+  historical estimates.
 - Population: estimated resident population (ERP), based on the 2023 census
   usually resident population and adjusted for net census under/overcount,
   residents temporarily overseas on census night, and subsequent births,
   deaths, and net migration. This is not the unadjusted census-night count.
+  The 2023 estimates are the release's 2023-base series, not the 7 March 2023
+  census-night count (Table 1!A26:A28).
 - Geography: regional boundaries at **1 January 2025**, with REGC codes stored
   as strings and `geography_vintage: regc_2025`. The separately pinned official
   [REGC 2025 attributes](https://services2.arcgis.com/vKb0s8tBIA3bdocZ/arcgis/rest/services/Regional_Council_2025/FeatureServer)
   supply the codes and names. The classification names code `02` “Auckland”;
   the population workbook labels the same region “Auckland region”.
-- National scope: Table 1!D25 publishes **5,324,700**, including areas outside
-  regions, such as Chatham Islands territory. The package reads the published
+- National scope: Table 1!B25 publishes **5,200,000** for 2023 and D25 publishes
+  **5,324,700** for 2025, including areas outside regions, such as Chatham
+  Islands territory. The package reads the published
   national cells directly. It neither sums the 16 regions nor constructs a
   code-`99` outside-region residual. Published rounding also prevents exact
   reconciliation from being assumed.
 - Provenance: `census` for a census-controlled ERP estimate, and
   `assertion: observation` for the historical reference date. “Observation”
   does not mean final or error-free; the source's provisional status remains
-  explicit in the period and concept evidence.
+  explicit in the 2025 period and concept evidence. The 2023 evidence retains
+  its unmarked column header.
 - Concept relation: `source_label`, with Stats NZ evidence. No Axiom canonical
   equivalence, population calibration, uprating, interpolation, or target
   activation is claimed.
@@ -58,6 +68,11 @@ footnote have guards. The tests compare every admitted value against the
 publisher workbook and every regional code/name against the independent
 publisher classification.
 
+The 2023 selectors additionally guard Table 1!A3, A5 and B5, along with A4,
+numeric B6, every selected row header, A29 and A34. Both dates use the same
+source concept, REGC 2025 geographies, provenance class and assertion. No ratio
+or growth rate is constructed.
+
 Dimension labels follow the bundle's one-label-per-id rule. `geography` is
 "Geography" and `person.age_band` is "Age band", the labels the other packages
 that emit those ids already use. These two labels are Chronicle's wording. The