From 83335a44109f91ca52e8c1a4654499af74c4333c Mon Sep 17 00:00:00 2001 From: Max Ghenis Date: Sat, 29 Aug 2026 21:57:11 -0400 Subject: [PATCH] Add partial NZ 2025 population source facts --- .gitattributes | 4 + .../nz-partial-population-2025.added.md | 5 + chronicle/source_package.py | 3 + .../manifest.yaml | 19 + ...stimates-at-30-june-2025-landing-page.html | 111 ++ .../regional_council_2025_codes/manifest.yaml | 18 + .../regional-council-2025-codes.json | 140 +++ .../manifest.yaml | 18 + ...estimates-at-30-june-2025-provisional.xlsx | Bin 0 -> 97990 bytes docs/pe-nz-population-source-notes.md | 98 ++ docs/pe-nz-source-checklist.md | 4 +- .../README.md | 77 ++ .../source_package.yaml | 1066 +++++++++++++++++ tests/test_chronicle_bundle.py | 33 +- tests/test_chronicle_nz_population.py | 322 +++++ 15 files changed, 1905 insertions(+), 13 deletions(-) create mode 100644 .gitattributes create mode 100644 changelog.d/nz-partial-population-2025.added.md create mode 100644 db/data/stats_nz/national_population_estimates_2025/manifest.yaml create mode 100644 db/data/stats_nz/national_population_estimates_2025/national-population-estimates-at-30-june-2025-landing-page.html create mode 100644 db/data/stats_nz/regional_council_2025_codes/manifest.yaml create mode 100644 db/data/stats_nz/regional_council_2025_codes/regional-council-2025-codes.json create mode 100644 db/data/stats_nz/subnational_population_estimates_2025/manifest.yaml create mode 100644 db/data/stats_nz/subnational_population_estimates_2025/subnational-population-estimates-at-30-june-2025-provisional.xlsx create mode 100644 docs/pe-nz-population-source-notes.md create mode 100644 packages/stats_nz/subnational_population_estimates_2025/README.md create mode 100644 packages/stats_nz/subnational_population_estimates_2025/source_package.yaml create mode 100644 tests/test_chronicle_nz_population.py diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..95ede819 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,4 @@ +# Preserve hash-pinned publisher bytes, including original line endings/spacing. +db/data/stats_nz/subnational_population_estimates_2025/subnational-population-estimates-at-30-june-2025-provisional.xlsx binary +db/data/stats_nz/regional_council_2025_codes/regional-council-2025-codes.json binary +db/data/stats_nz/national_population_estimates_2025/national-population-estimates-at-30-june-2025-landing-page.html binary diff --git a/changelog.d/nz-partial-population-2025.added.md b/changelog.d/nz-partial-population-2025.added.md new file mode 100644 index 00000000..34fbf58a --- /dev/null +++ b/changelog.d/nz-partial-population-2025.added.md @@ -0,0 +1,5 @@ +Add 85 source-backed, provisional Stats NZ population counts for 30 June 2025, +covering the 16 regions and the separately published national total across all +ages and four broad age groups. Pin publisher artifacts and REGC 2025 codes. +Keep five-year-age-by-sex regional coverage and national single-year-age coverage +explicitly incomplete; no calibrated population or completed target set is added. diff --git a/chronicle/source_package.py b/chronicle/source_package.py index 993b4d9f..1e5bdfbf 100644 --- a/chronicle/source_package.py +++ b/chronicle/source_package.py @@ -74,6 +74,9 @@ SOURCE_PACKAGE_RESOURCE_PACKAGE = "packages" SOURCE_PACKAGE_ALIASES = { + "stats-nz-subnational-population-estimates-2025": Path( + "stats_nz/subnational_population_estimates_2025" + ), "bea-nipa-personal-income-components": Path("bea/nipa_personal_income_components"), "bea-nipa-personal-income-disposition": Path( "bea/nipa_personal_income_disposition" diff --git a/db/data/stats_nz/national_population_estimates_2025/manifest.yaml b/db/data/stats_nz/national_population_estimates_2025/manifest.yaml new file mode 100644 index 00000000..bb85b900 --- /dev/null +++ b/db/data/stats_nz/national_population_estimates_2025/manifest.yaml @@ -0,0 +1,19 @@ +source_id: stats_nz +package_id: national_population_estimates_2025 +dataset: stats_nz_national_population_estimates_2025 +source_page: https://www.stats.govt.nz/information-releases/national-population-estimates-at-30-june-2025/ +table: 'National population estimates: At 30 June 2025 (landing-page evidence only; + no single-year-age artifact)' +files: + 2025: + filename: national-population-estimates-at-30-june-2025-landing-page.html + source_url: https://www.stats.govt.nz/information-releases/national-population-estimates-at-30-june-2025/ + sha256: b2d2751800857895b1498d87df6f03ac3511ec8c7a9b17cc3150c8ab56533053 + size_bytes: 61286 + fetched_at: '2026-08-30T01:43:59+00:00' + storage: + r2: + provider: r2 + bucket: ledger-raw + key: raw/nz/stats_nz/national_population_estimates_2025/2025/b2d2751800857895b1498d87df6f03ac3511ec8c7a9b17cc3150c8ab56533053/national-population-estimates-at-30-june-2025-landing-page.html + uri: r2://ledger-raw/raw/nz/stats_nz/national_population_estimates_2025/2025/b2d2751800857895b1498d87df6f03ac3511ec8c7a9b17cc3150c8ab56533053/national-population-estimates-at-30-june-2025-landing-page.html diff --git a/db/data/stats_nz/national_population_estimates_2025/national-population-estimates-at-30-june-2025-landing-page.html b/db/data/stats_nz/national_population_estimates_2025/national-population-estimates-at-30-june-2025-landing-page.html new file mode 100644 index 00000000..c6b5be5b --- /dev/null +++ b/db/data/stats_nz/national_population_estimates_2025/national-population-estimates-at-30-june-2025-landing-page.html @@ -0,0 +1,111 @@ + + + + + + + + + + + +National population estimates: At 30 June 2025 | Stats NZ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+
+
+
+
+
+
+ + + +
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/db/data/stats_nz/regional_council_2025_codes/manifest.yaml b/db/data/stats_nz/regional_council_2025_codes/manifest.yaml new file mode 100644 index 00000000..ef09675a --- /dev/null +++ b/db/data/stats_nz/regional_council_2025_codes/manifest.yaml @@ -0,0 +1,18 @@ +source_id: stats_nz +package_id: regional_council_2025_codes +dataset: stats_nz_regional_council_2025_codes +source_page: https://services2.arcgis.com/vKb0s8tBIA3bdocZ/arcgis/rest/services/Regional_Council_2025/FeatureServer +table: Regional council 2025 code and name attributes (1 January 2025 boundaries) +files: + 2025: + filename: regional-council-2025-codes.json + source_url: https://services2.arcgis.com/vKb0s8tBIA3bdocZ/arcgis/rest/services/Regional_Council_2025/FeatureServer/0/query?where=1%3D1&outFields=REGC2025_V1_00%2CREGC2025_V1_00_NAME&returnGeometry=false&orderByFields=REGC2025_V1_00&f=pjson + sha256: e5d53fa6abf742121d123bff970c77658a16e8c9b405b83d1a978cc22920d660 + size_bytes: 3381 + fetched_at: '2026-08-30T01:43:16+00:00' + storage: + r2: + provider: r2 + bucket: ledger-raw + key: raw/nz/stats_nz/regional_council_2025_codes/2025/e5d53fa6abf742121d123bff970c77658a16e8c9b405b83d1a978cc22920d660/regional-council-2025-codes.json + uri: r2://ledger-raw/raw/nz/stats_nz/regional_council_2025_codes/2025/e5d53fa6abf742121d123bff970c77658a16e8c9b405b83d1a978cc22920d660/regional-council-2025-codes.json diff --git a/db/data/stats_nz/regional_council_2025_codes/regional-council-2025-codes.json b/db/data/stats_nz/regional_council_2025_codes/regional-council-2025-codes.json new file mode 100644 index 00000000..b7b0f48c --- /dev/null +++ b/db/data/stats_nz/regional_council_2025_codes/regional-council-2025-codes.json @@ -0,0 +1,140 @@ +{ + "objectIdFieldName" : "OBJECTID", + "uniqueIdField" : + { + "name" : "OBJECTID", + "isSystemMaintained" : true + }, + "globalIdFieldName" : "", + "geometryType" : "esriGeometryPolygon", + "spatialReference" : { + "wkid" : 2193, + "latestWkid" : 2193 + }, + "fields" : [ + { + "name" : "REGC2025_V1_00", + "type" : "esriFieldTypeString", + "alias" : "Regional Council Code", + "sqlType" : "sqlTypeOther", + "length" : 2, + "domain" : null, + "defaultValue" : null, + "description" : "{\"value\":\"Regional Council unique identifier\",\"fieldValueType\":\"uniqueIdentifier\"}" + }, + { + "name" : "REGC2025_V1_00_NAME", + "type" : "esriFieldTypeString", + "alias" : "Regional Council Name", + "sqlType" : "sqlTypeOther", + "length" : 254, + "domain" : null, + "defaultValue" : null, + "description" : "{\"value\":\"Regional Council name (supports macrons)\",\"fieldValueType\":\"nameOrTitle\"}" + } + ], + "features" : [ + { + "attributes" : { + "REGC2025_V1_00" : "01", + "REGC2025_V1_00_NAME" : "Northland Region" + } + }, + { + "attributes" : { + "REGC2025_V1_00" : "02", + "REGC2025_V1_00_NAME" : "Auckland" + } + }, + { + "attributes" : { + "REGC2025_V1_00" : "03", + "REGC2025_V1_00_NAME" : "Waikato Region" + } + }, + { + "attributes" : { + "REGC2025_V1_00" : "04", + "REGC2025_V1_00_NAME" : "Bay of Plenty Region" + } + }, + { + "attributes" : { + "REGC2025_V1_00" : "05", + "REGC2025_V1_00_NAME" : "Gisborne Region" + } + }, + { + "attributes" : { + "REGC2025_V1_00" : "06", + "REGC2025_V1_00_NAME" : "Hawke's Bay Region" + } + }, + { + "attributes" : { + "REGC2025_V1_00" : "07", + "REGC2025_V1_00_NAME" : "Taranaki Region" + } + }, + { + "attributes" : { + "REGC2025_V1_00" : "08", + "REGC2025_V1_00_NAME" : "Manawatū-Whanganui Region" + } + }, + { + "attributes" : { + "REGC2025_V1_00" : "09", + "REGC2025_V1_00_NAME" : "Wellington Region" + } + }, + { + "attributes" : { + "REGC2025_V1_00" : "12", + "REGC2025_V1_00_NAME" : "West Coast Region" + } + }, + { + "attributes" : { + "REGC2025_V1_00" : "13", + "REGC2025_V1_00_NAME" : "Canterbury Region" + } + }, + { + "attributes" : { + "REGC2025_V1_00" : "14", + "REGC2025_V1_00_NAME" : "Otago Region" + } + }, + { + "attributes" : { + "REGC2025_V1_00" : "15", + "REGC2025_V1_00_NAME" : "Southland Region" + } + }, + { + "attributes" : { + "REGC2025_V1_00" : "16", + "REGC2025_V1_00_NAME" : "Tasman Region" + } + }, + { + "attributes" : { + "REGC2025_V1_00" : "17", + "REGC2025_V1_00_NAME" : "Nelson Region" + } + }, + { + "attributes" : { + "REGC2025_V1_00" : "18", + "REGC2025_V1_00_NAME" : "Marlborough Region" + } + }, + { + "attributes" : { + "REGC2025_V1_00" : "99", + "REGC2025_V1_00_NAME" : "Area Outside Region" + } + } + ] +} \ No newline at end of file diff --git a/db/data/stats_nz/subnational_population_estimates_2025/manifest.yaml b/db/data/stats_nz/subnational_population_estimates_2025/manifest.yaml new file mode 100644 index 00000000..efa85675 --- /dev/null +++ b/db/data/stats_nz/subnational_population_estimates_2025/manifest.yaml @@ -0,0 +1,18 @@ +source_id: stats_nz +package_id: subnational_population_estimates_2025 +dataset: stats_nz_subnational_population_estimates_2025 +source_page: https://www.stats.govt.nz/information-releases/subnational-population-estimates-at-30-june-2025/ +table: 'Subnational population estimates: At 30 June 2025 (provisional)' +files: + 2025: + filename: subnational-population-estimates-at-30-june-2025-provisional.xlsx + source_url: https://www.stats.govt.nz/assets/Uploads/Subnational-population-estimates/Subnational-population-estimates-At-30-June-2025/Download-data/subnational-population-estimates-at-30-june-2025-provisional.xlsx + sha256: 001e8a896cfb50f5ed17836dc815b235e3bcca55ee91c9869a2afaeb054b50a6 + size_bytes: 97990 + fetched_at: '2026-08-30T01:38:43+00:00' + storage: + r2: + provider: r2 + bucket: ledger-raw + key: raw/nz/stats_nz/subnational_population_estimates_2025/2025/001e8a896cfb50f5ed17836dc815b235e3bcca55ee91c9869a2afaeb054b50a6/subnational-population-estimates-at-30-june-2025-provisional.xlsx + uri: r2://ledger-raw/raw/nz/stats_nz/subnational_population_estimates_2025/2025/001e8a896cfb50f5ed17836dc815b235e3bcca55ee91c9869a2afaeb054b50a6/subnational-population-estimates-at-30-june-2025-provisional.xlsx diff --git a/db/data/stats_nz/subnational_population_estimates_2025/subnational-population-estimates-at-30-june-2025-provisional.xlsx b/db/data/stats_nz/subnational_population_estimates_2025/subnational-population-estimates-at-30-june-2025-provisional.xlsx new file mode 100644 index 0000000000000000000000000000000000000000..8b551d33580e198a4d18e4c8677372a2637daa50 GIT binary patch literal 97990 zcmeEs^Lr*-vTbY|9oy-oV|8rXwr$(CI_%iCt&VNm#?3c#XC`yzocj-)n;(+r&AXqC zsipJL4u)0^+6t~VhW47Y zE|wPfxgbE~zW{(f$N&GI|HT#i43yhiANaQ59+l zX!bhu!D*%e5HWr5pA+-nF`Xn>e)jq1#DH@lt9&zhMo=85V#IJF-R6LM!wmM?eJaA8 zf7?A15#o0&M|zWq(oe>w`Ut3Nf!0;TL&r=@%g9}(*uiU#emoc^zd1YY!}s)1b-^Ee z5@B7B4%q1xVdahr*wG{Ymi>+lZYv3vTDd38JlbaSGqwTka@LSCykmE@800yqX_-zM z?o#0eL%3B4>b$Xb8lmX~g)r&BlWzHhmk{`6V=Twc(yfoO41qpbzw!Ak^e5}J?F=pK>1hA@{r}niznJ1*j$RfgDGvM{A?U*IgJ7(kV}+7% z+Ja8-P}1NH@O$c;4ohlGe#_f~5U)c{1Fl;}rE`{R>YY(do=YBryAx89Af#W0(M+pS zkN8_t6F6eLolxYdNRKa}MafC&9b+WrUe4kjcUakWZU8OGhYyCMuu{JtSF?sGt4g9B zhT5$ddfoZ^*`%kB=pmlBeg7(PXtEoaB z2lQa4O0X0vY+Pllujr2i!+*;+xwHAcMX011>q`9VKh$zRmERV`w-*2{&uaq<|Q%?&fdeKoVi@>v&~Om#o+BT~Ro&89hiA z^ciXa_JHw=(Oqm|w833&@=b*3FRy7^ z8acI%a|c>+NYx$E9cY9{FV!K8wOL1XdLNy(2xKK4DN@63-fRwUZ-sE02VxrDr|FE> zB^e?7t)I>az$Uh*+lpMhoQYUTj$66DLJx}0s;tx0WbUj z62VP|k$j#;5twFLlY>Wsz%xGi5Fz*${#aTCs2S7pkem)!t#{5XX_O&)$qh@(OS$j} z7yt~Jd3rp8lHeO*h{%Xe(`l||LO|w#LRUr8KN~D^MRqR&2}E>hK}PS{`;48T+kl>a&0i+Ov8Y19aHR*v_(;f{4_!y5wk7fH`RC>%8fMY z+nf8mE>lySJxkRxeV>FT+Kf3m0ulDGQ@dW6*-`*0-L1bHL9Kc`z>Vyd?AJbo!A=js zMtO=gy6N>GyNMVgBv1HQH||wYFU&<>RDP|a@{$n7%;+o%NYa91=}#>_hFV%>>K7m# z{1`~yj>I0o4|#O;eB!b=khRY0gI(DRINduA-1Nl$4WH{A?)<=&a%nmk{yfO{bxM1Yj~lwe=c-!)TX*EQVP^v*=sX1>S5phB3khA z#S8Lo&c_Lxc3G+LSc??>?xBr)_+LDNEWd16aEi&Z!v^6Qty+PVvg~Ju+rK6$%}Ae4fGU z$xgC`Wy6LgvWH*)@}YvjmITNzd->TGiT;=OJzW|g;sWS74A^2;;4n)k??%@^Aw=z- zl5=_;)X3tZkQOqE@0Gt4G1B0EWPgjWM71>$Un+hr5{tRAND_Hb<~LAI>#h(9Ttn6H z_C9aA{#f3(DYAEAekul)WDyh5qt)Rx6#u1gyJgJ)g{d&K0`q5;Ou≠S4+(`)7{~ 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�$Nfz3gvM6MFW;vpSA1$T6Dr4+-`Mn!DV?A6`V{&+c?MK z`N${nX`0&Q|Jy3 zQQP*LQbxm;=bAm<1bIRgGh&?SV;Gb_Ah=i#C^D zcLn)&d>DKUNdxS)maC|R^i`_QLOJzDV z4WY0IjbyTPN&fPa5AZOBqvzddKXvSD=KMA5^(UscJ8~&v#EDIfXcs?{^rD}+fSfx- zPF@U05{fX0EJq9pr0n2IE6n8VZF0f1s=Q zs(2>c>s*T(Cd~ zeD*MIOtR=Z**Qqz1>rMREw!uuA{Xk@zrtrOEcQ zOV%}^EC(Sx3#%n@0Cv+W@R#!@xN3=~JkrwKbW%*R?0!q|1X(zSJPN~E=*el*zpLNQ zbTzvUCdEimwK}oR7AeuUt|bz4q1Q z8(`U2!#8x+y(Uz$S`FgL2Z~qumnXBx#GW^0fA{WZoS^2XqW(YSHH#5X7I52S3fLmV z?EJCHG_b|?-`-|3?>UG}f@|1k?Dm=YvYdjfwW^?;Kd`FohoqljS~k8bbwXvto5b|L z?G_RZw0w^|(n-{5q6f{ms1$T`(K4NAXzC1O^=qQw#c*5&Q`BT3s$Gm8<_g}pf!qEq z%oK6Bmq&9O)3FFveb`@Kd|)cNK09Y6guCmH2{XA7Ye`b$(vhD%n7o>ZZf_~-Wcvq? z9pdsWCpJ*I@hfsdE-f0Y-2&Yhs`c?*1t}rcr#V0iPJ@-yg}h8?XdoZ?dF^(?c@_$XQ|a?B;k*SvtUDxvSG9p*pO(5$ZD0Z?G$y}Jl#>ZA`+ncRd~Z5= zs{)^F-gN_w=fHUK_03%g*EBP`FiO}AP+q+TB@cqWTA$cef)XNUmIH+DJP6e5V9jC+@_J8-*)Leb$rI zs$EsP>Q}Y*sY8so{%frKNHDXp*2{C2JR6}_asw+_98D53$o-KFbmu}aDM0t3X&;pU z1zyPKb#X=w+SKbH8e<~P02EuCwVY^qldKkkMLZ3MSR4R2ydb~hhh2Cq5FS+ceP%yDu8WiTFo zh<*cToe`iNyK!p1fwkFQQEV28MAZk}zZCTV;}TG~dA8xr+1uc?{F%OT#58lo61W^w zO~7%>ny5nYZ7_m)pl;R9EK=r@fsGMiajBc<;2~u!qg|tJ!_)i&+n{g#dE6P5T39aP zuoajPTXUyC?u{{l43n_F2q{p)m-0M8Nkojh9;x+ykUL;GiO@8r=p~@V4+osBUHf=a zhevywEVlTuZT)-*tiaLaCsE`T%V4^5{b#I#>MmTp=(fgr(0>GSgUK>}qNd6-^e~Yw zw{pCcc%&Pz4ipEP>-UW){OHZrum#=-^d8_14&EopqTsWF(CMX$T`-j0C5B%w7%MLl z)COq8aux%i5z!4S2~fm|gToVPu-|k1fK)qb07DgPd6oP|0b)AI4&A>$T|pWVk+wVW zv(KSYy3v;}^>wh1NngC)w3P)>KK)rtvbJ zYeUmTpZlm%H-u;4CbZ{y)F*@lDR2Zro-2x+s>V^JUweQkb z<;!z!)A}R~Iq)6E6CtS4KX(X*%eYGJV>_@+!OUbI&=o1unj1+Lu!O2k*H7&Sjfu& zsxec>^Pc#-QZjP>u9SraoYNjx|8p7RfYTR`gWY3~i(>OylVYN9-ihX7H?|76u_@N9 zQzei`UG~5p&bP&e0={3Djb4W>E$;#xl!5I(A73UjisQ&6dx>HHk~9U7tbHW_uzFj> zzhk_~anDI`z_!eQSOJT-F zDz+K^-G%=F5T!wBr%jf;@`eDWLtx>^hfvG0fkmUZwGWr#f@TI$WJ$ zp8<~Nbwj_VW~hI8(dcv$P5EQP6|I}`2+bY!Su$}TKRQ4ZiG@8;6*lO%nc+iFUfT;t z@1~9MHz;=YV6q^jV5E{tb?gK+47QbIh7okCz~kTTJ$2ecp7YA*$DDl94&$Qb-9poB zO9vqpe)Dj*9ImLX5&&>lZ)G`q2v9T*3nw9DT9z%`uRU_}S`nOmB_}Z=2hZJ!t7X84 z+greVLkVsNnM4eDTz(}t)XZ)=910EW*+bxEbj_)kevM5N`;4DK?3UJd;|2f6`|BaI zaO6T@W!e6q?%x?WHdu-pEw~~XstTtb66bhmRqF@z7V6!}P@w$r=$?|R-qZ5FOO00v zvO~1+D9*v^)Sl~)>ae8@z+%qz|AoawpIT`6av)X#OuFo`0hq)za(ux@L8T(A_vdbh`F8v5yQn4<$48XPoj;h%tQN|p|a;X>;O3vQrB9vfZh z1kgr;SPT@w@B#Xb${PUam-xhi58eTwU&?;`X@f}OLHt7>X5oT{fZ!sI;^@rYh28?n z_Qx7&H23Z%KmEcBTHbXuxn3mV%eZl6VKd)z*j*cD2V{t@DU+rCycPgKh7(&p_#3tj zEU1C5DT7Fc#SIbl{9|6<`gHVe#x=NSu9};*;=Nj`MlTt5^kEngLof98c6L7{EbkKF z=x-+$9wGMoTF@MP9nkNz!peq~ zFz#BsD@8ek%ipAWx67LKMS^36a&6gLBR%55@c~@b=M@6DqB*euOq1nrAitef2Zl;0ANjab|nk`20&~j#J?YaS6JgkZ}Sg+iw%jd9%@hrV%pjV z{j3iNE#k0~-P8=zNYx5E3Qu;?^i%+`gXXpZ>FmBV0rS`nTv;D27~e4YR}(lXkGZnH zWitou1W0e)!5$zzct^-v22HVFZKr=^hkV=Hp`U37v<>mfTlHVIorKNvTir3%+2mEQ zV#myOiJ`nQ01*TBU&H{6k034heSa0i1b*9GfJ=cAl99$@sen603zT!S<#-eTkq?In zXGb4#F5<2t1bx$U{6ve~Z|zsk92uCU7~uUE!(;xLN1f)!%}vXd{UrqiR%U~?ID3hm z4TQ9b;Ru1DhKWoG?B+nLS{8G3uQFzuCS|PXq}=(jJ;X(Fz;Ps^8Zg^DYoJp{6K7`B z!SYRjC>9GFz|{p016m8DN=O+3XVqz(pd1Jq1=K2V9oO?h?Uq zY{R5(v|gyeRuMpc0m68WCNCDS+L|JBtD|u%@(oJnw+OZqM*viV;GOP2YZ8oeX6rq$ zG0ua3;s_>NpH|J?MAXyu|U40;Q-&>zOmR@N0z?-w3aBWWYlt!)Fadehiiq zyU}Zc)=3h~1ZbGa!Wm%5aO+tOz-;EYpr)-;*ffe^T#Gq)`lEW?6^WYGw~a{(Qwlh}P3|0n}qSPTZ#< zo&k<&aL*6mnDF-9r#XK?AsACzU;OG*<^WV5Qas*O9QAlyT6mLJTmh~aYV-)}ISqg>8sdUFwq9b>Adl!8J0v5|(eE19NO0LfQ`&!>(EQ@W@wftu}$zE#Op>oy=+(hrr=OxR8?(p%={4! z-Dp{nXdDZ7@(MN3OMn`d1Uj7gdarDZb>O!(`5`ORgfWJs7PnKDd_Aga5$Q4mcIJco zJsQ8i{s=ZD=G0u(ndiMb;g=_(+ z)C(yZ6|#$&_%Mh92<@0pbGHmiM<*r^ETi;~pggNUwLy;f&a3$|?h! z=z%5izd{$L3)eAd)-)SLyF&?Jb-}uF-I88Y8E-ezCH2C>fy|77b;1t4;DV$8k!R$5 z^M><`)XB91AwiOp>lK{-CQ%~T!>qaVt^aSnKhzhT^#|DRpV)T*Vh?}KuBBrlZCP=$-{QUU@HHc|V6sezGx0EjwOEX%x55;<9gh z872J$jLxAzBEV|#ESvz=0GR<`iyXifXX_X?O?+@#1jqND@t>={;onF%d%`j!rtLsB zh@(0T+}1hVC*VqmNx6Bz^Qye>CHHU>pc3nIG-tPdXqAr*|E*G%rh;uvy#TobOoDWC z3ob=s|I_)n0?tz!1!a1|n}o;K9!n$ap!MnF_Y=%PYfFD?nE>u_o8CYj6}(P6G{L@% z+Lr7M5&#)yO4#7h30BzGj%?%ajHC(}DEdE=bL6k$4NNYO?=~OpqF2VdDUp1l__EOqPJu z5~n=bVYbUf4OfB+Nedz`>u~s!B*{St;K~W8RaQF!gZuF~e%<1Bh3v1sMw}I;<|U?A zwgaw!xIlVhG7ZU*ZVN}cCkOCDDElT#C?E$>TdvE`!%rTl9(KO9xkwWZW2YgFGq_$& zzT4Y2FMWM{RzVEXa#07G>*Nk|;Jg4&*`8MdphkCMNeAJPVf*8}pZ^E|kJ?8I&gI$= zzlrtQ{nmnJw|hbmvM>(A{c4e-ED`xA4Lu5=UFkxuwe(g1@q4%`{eF`gFDFGA&Pg*u z4%H-3U&_R(c|Q)YxOSLdZ`v}`LqLfDZ3t{00$jR?jNGS|RoGxs;_+jW06p~$p4_+E zDwOdh^Pl0rMn7Dp0{C@Z6hH`B7U4Ad#`Hk_jR3_P1cEaewI$zL!1D5PojucmtK|Yj z#DOXRw&7ZY95e>TMmY#OupV;s^G1DMYQC{$8gfi9EO{^vYi)UF09M5d?~GmNv$s;k z>u3i=YuNUzv2xcwkD%J#Kh#>vf5_GJA9BTJ;lu=$0W8*WheW_) zg=6HbvrIu&f7`GVSHgRP0U)pCetRYCEB)u}WyC+)hUYN|QARy78^fIXq2D7Ms4Ir7 zL>4C{-xem8vkG?g((P|QQGGIDJ<{D^R=7Jrxh zK%Idqo^o(ub6kTLjByuEtqZCP0A0GH@{Ih05iWEP8~`V-vL^>{;^;=IM)ag4cGsbs zqU?cs9Z(&F4>Z8M~cl8Q8Of066WA zzfRkQ{jbyBni~4ILdpNGP>cO5$x&6YL62Qred{653-X&quu7VN592M%kJ%8?8ShTk zjFmd8bC1R6dxUK;x`MnO0421003}TD4*(^9fOS!B?!cu)2*HWaG^%0Gm-X{EHuXzy zrek>UR}BiOz)j=w$Js#dj>b?#v>oY!K9xcnak?nskxQeto&oTdC36#`etED2dM#YN53)b zOd+Jfh}6h`p8=BH>Y%8fFtz91kuXBY&r5k#`>T!HnjqVs+YTP9kYomGo{M15X!U#5 z6#&!=5eG0fHNf>Rj`7Nv0M0SP{d1l=5qU@0(~z+rhQJHEgtq-`A-=fXQ>F3!14V+g1a~YFz`> zMq+DP(G2TLL|=v#j?$vGcHYJdjRfi_H50%-t8#D>CQN_O(%GIc9c%P zF}tMXAAQu=E2b%qUGL8p!&@qDN^yA1Ep@|)>T1b1u6qflWQIw}A?HletvTraEPEbQ zr75*Fa5*FY`JGRf>_>fqgRU9$N<(uT`Q{W5dC{_U5BIhD$FczLvwvft-SbcM!_Kc1 z4bX?t+c}8#s#Hl&q7Ukm6(U_we*dpOar}Ojes8xMEC0{qE^+^kyNI?Jc>;sOLD&E* z1s60bRrr~J+hO%m^(`|f7FBkWmuJK!?06qL%DF<|<%L>mt&ZuMmA4(rKBO{*bpNJT z>X9V)n8*#?j;`WadUK&p^-8rrtXd4;_&AAOP$9UKAQpwqK%BB#MV=8b1_CQ_pk+cgetaHu~a9jVTo=BB5#~L{3G|`Q{>W z^`3{<=MrGuhA{E`$+}nRPN!fu@UBD{NSEVz037!S!>XPIK9OgxcANqD7~-%}-U{3E zzO}n@Y&X6iEeR0oe-7FIuZLOs!#D1HA%K8ZaDjkO0cU_bZ0KDqOl?j7b7lN{j^#pA z+8&o3sT=de|J!5EiJ@fkkI_IfX~#?sMjJBG*u|)I(?MN2iSbxFQ70OOJPWORrMwn` zsAgc4ywv-ZR@u2?fls0ELn$pS7aIzQ*LsBJ!4HmW>}iJ@UH>!&7lDvpJhtG;6-Pkv zEQi7wVpY3#J?^Ho0!n)>5!mvQ)M+T#Iy)X;UDh7DL!?Adk0nm{EkPP(HeD(SL^Q^p z$>yY?<|K3|mAfSoQo@0Vfp+~;OHOTyQVg=7N&8@<+t@J{5(+y%LrN-6V9Hadj|_~5 zOD6)f%YW%XrLV5oM0C78cki_p%sEkU%jAJhY60I6-VN}1mVyk{s@&wECrwdM+Uij6 zJ@}w1Q(VwqoTtlo)9*0gsl&@7!~d3{?$UC0wU*lfO4Ay4?bwoQVJa~P;(!yhrj`b@ z#cNTsoUyo;0l!fgkm&qTO2=k6AZc>cjmxw32$$ z^k`PH;BW(BavMYDW8bt^+U5Zog)KWGZE-oPM_Hl8 zxKz>i8h)RDTk6IpoHEt z^N|l0Zuv^#cU;XXIE;zIY?YM8l&z5Zayful)>&qf@1~Z?n>#caXJ&hsPNmDA(>m=E z6A>}|f!d*%WITZ9QRKLdzc>g%hxdc6Sfx1pR0$E)QK!0b5y2AQB8s1HIgSPLg_Y}x z%y;wL>K-VLj7E!!^<}X)oQ@u)<+~c>80%zOV4*YO|7i@R_`|L3uFt(SljxQG8MuU^ z{f&SuwnLsC%-!-Zq7e$|!-SZpyHl_=GftVUe^3RR@>;G)&f>MWeu{GOa-yD>dxUKd z=?~e=W1W#N%9XxGLCX#47THhq3GqeK(C*6FKL2i^+@uLi{Zz~%tn&MUYc^dEr($v+ z5$p|hWidO+g>Y$(A7Q*2ECWI51jnFS7y~PvAMOtEy=I6gI=&*RorDK)Ue8h3(j@7L zv83azA)NCxnZRjyg|@>QFt(lPLg!w5b*dspO#|U>o<$tt(_?96EKJVVKjxyy9n{RI zE3Sttjf%MDY^tr$Nix3wjJ0x3?#rDh@7v$Zm_7P-64N^lk9E>?!SH4v7PfxnCYIYK z+R&|lIfjKOc|}t7R3Aq*EZLxu9vVL)?p4e)Bo1yTEBlDwnmr^b>eht1I@S3^rFrYaEFz%^6(a<;!*uV}s`0AW1 zEq07VY1A}bWg0gU=&1DfTuS1{gFPag+Q`*`T|fNtyqTX;tse~Nf?omF+_tuVMro%# z=h5jW;HImMQ-(O`Tew8c({1+1iGC#T0iAK-PY zWwlDOn2HBx!X|7TDxwd_X?`jpF&Qkt+y669dCkNgHHI71V2Zv&Yy=XR650fivm9%p zxH1_@wiS1)-61w;UqkI zM4dfauq|SZq_JBMVe0wZ0O56k*C3J0NWPuz66p~2CmHHX2;6BOXH?<(1OInNFGJWW zcD;~*fN*MofZ+cVt(;vvZA_j2#VOr$yMtl$PyM`W0ZP$$wB#ZpQKh@}?dK?nQ3$~c z5b*X;!HFc<5X|HPcDJZb*_~hX%jra%%qXIFB(8`TL+co_Ih@SS-Pc*1&JsC3KJY%5 z(YQ06lsuO|3;o2M2ORHDLgh=cdv>;5!trfWIQ9w;#Phw^J)O<7lT zugJ1c5ocw)<;qx$aEY~rg23+?Y`*U4V$_)8u+|#DPs*y2g|Gal7X66cA-!&H?45k zhY->>qIw)~WQZmnMvPyICPuQmMW4lb73MIfB$OVyB}A;9pF8{d$7oC8+#5Ybj}+H9 zyPKIv=?me+M{iP!o=aP2S;Xl{?dakbj5cm4=b`?JJ zhj2~*>-{>F@?}=m-{)OIzWv(Id*|~04g&pj5N9&_xPagKLVpb0>=gXe^x`c%!MciU zh2ViYvmsSai8xp5Yg5Cw>cK4}o{=jOedp+AP`C+~Ih_AuS>3KpY%?l&Euh{2lKIUbpo@Xr3=x^oj=1 zEa7@LkT~M@*=bO2>Xje*BxKH0jq+b__A12PEh-15AHhYFrwy|UtY-}_jlbKKDe-Jf($XJHSDn4tmi(oY}+2c>b8yX8! zJ(;WSRHv{yIl9X(o=^80orQZ|@2#ORcgbfF5cT>PFn!E~uayoMm=$gana>V+cQE72 zru$*Nb}vF8ZXKK!28iuQygR&ZtV^}O_^*5vE{h`A`Y1?Y=!_(trDkDq$V z$k432cwJl!x>G>g5~; z+x-Uu2jShU(zI#Y&SV#H>|4u#Y9@0zFUvK&M+Cg~;uR~Ogna!=T3&T1&3oS5rCzU7~}<3H>tesoq!TGbzuqMm##y94+lz#ZIkd0*=^4DAz_*4x(a zGYz84w^2elgnD%DF7pgk!p5N{YxGvHvmBFl;W9fpgh{o`#P#!EDTUN-eRma0TT)Wf zJ}pXXail8jZDkKKu*3dENJbl4m39@%o4?C9r>XRzqqkY+OKQiOmzJMwSyX&I($yDE z%hqjWE<+QP=7i>j&th3?+-NuK>E)}Mn1fVH@_oMi1#^`&SeOT*#sjkhoVH$BaAWT7 zx7aB2moc1!Xz&odB=l6?DRt#&6&+?4zV^SAJJaA$%coD|Wx4uHurqMlCC+CNjm(M;1nh zzAPMf@oO$|%5F+Vpm|`LXwqR}H@bb}wT7$yR=vIplWg!99RuQ zJ)>;0AfZ7eTy_sA*-BLfwF6$Rq(hwCs3)#e=(AbFZ!8mBk^`GNRrpgUY=NR5LvzU@ zv_oAW$(Z%pt$a9@F1tXsGX5D$W2L~DTogu)r`OQ7+5ENp*Rt0JvfO7$}!Pi5gwwnOYC3`CX9(g?n~VE-y^@tY+9 z!UQ$@TFh*QiO88{TP`)Uk=axx>MzT;ir+)&1GF9H6ov6q2$Fwv#@knvGFS4_Mzp_P ztIbqk(g#1_efs8vmSxWo=KB;wgaU<7iZxXlMjxdt6r=||jf!bT)l8Peu%qjjW2Rm0 z@maUER-d6*HudxmKC8~mGg}pPLSH`i$Fo5Rl{JHfX&d8`77X)^e2y_~!H9lg z@}rh4x(SCFC`%IitjE(C6oZH%_rp}ysQ{nRXrP`^C87-U>e%lltNWR*Q->T9F;sa} zs^d7Fr@Fk3D+=K({V7HJgQ^isuSU3v2sv+`>wP>c;$ z4Gssla*&!=@OAc~eZ)er>}+c(tA@93o$|UfpVeFUt|dNpqguo67v7KkWehi{Kbonm zbo7VcTc23b%2GlSV<4O=s7qt0bSM$FznBa%D7H&fsZfM5#5@V5fq%v-eD!=a9ZHD9 zh`E%C-iE%9Yy){5do!F*zq4%ze|JR5#-p1ns1Vx=5c8>JJTONYhP9G2nBgZ$UdtDSAjQ&+OJM zW;0Z$Oy2&0=eC~9TeE}F0Bdi(UQ$_L#qgL@-#OA23@`DK-cpZ5)>i)*tNn?$Eie(& zF|eSUgo3x*I+14uJ6_{3!-LjnzYrnyHc!w)e6xO}(kO2Lo1srYRr!>%uxu4osVB)( z2hNJDU2NQ{^&#@7YAB|vNPXK{UtC{nK&g`J>8jb}*SyrBpS$^0R0ekq+D`Ok%kpMZ zWX2FVy1B%o0FrtKO2OsqGKN)t^8zxsw(Z&V3o7y{Gg9(O6K!XuEDw{Sam_C8rH+{3 zF4WHA9DyEB?sof3PJl&ii#08;J}Tb0Uu2vO|<8dg>?p8vCdAYnA+b&xabF zvWWBrrbMwG(I5MJ)$Y3MQ2t}z!hy2;n4S@jI{ST`HU8gc-*h1&=rT@7g!xEUDu2F# zdQW83T;NmU%jkb)_cYLFUfhGk+?zsbK7)NXTA}Jcj6z`I2Oq;1avG8fm_sIY2OCSy zhns*C2$~`48^=LG_W_1ZxuyHjB`v@ZPu}OeIjf)}7<9xGF-1)JjDtdx8qOf|f;;>6 zQN)szFFYJhDZy-4ks>umWPt&WUuHC=qboaxnqOL&Pybbp2RTHnu!szrQ1Oh2=JqSf zU`XKv=OY!7+50D!iQTUpll0B|+@G=iaT>d63NIj37uk?$S3vZ~?XaD-keUYbz;1Fy z(o>2wC;|D(YfAQ5@j#NyYf9Ew2|&`!V@l>&i9oWDd)FM%F3UhdYd^q3_aHDwe_bs*S8v}{u z!!lb>W`?vMRO4tSrTb0?E?1Y!=Kkuv=9~EPm#DcqNW)@i0m*t=^pJI zM%7P|n4?{WfyBP`PV`fqa6<~%0?V=eB11HI2mWD0`3O{qxN9t22Z82^4X=7vN90T3 zjYVhz579dkcJDzR#Q_TV^_3fSC=>XmE+1MYjdC3>AP)RGjdB?-AR2N!YDA>Z3`j%< zJUU47?;q7NpwnO=lEZL-=IsV1CH_UPyXHu5sm)c4-ogwO~0EC zJO{68YD&Q?f|>PJ@0lU9ASi-m07P1}h$NZ^eN*52fHaf~?NI-{For0KAJxD_dF@tc z&K$(YMyiHgB>vwZmt92h-yn`%1o`h^9Pr;mnb0?k`s_DP?=c3oz%G;O@MRiU)x!n}9v>s5)e{X*Pj7lBHDzfeoOsI2B`I zU|Ud9ex(?A@J3zvyQkP|is@i})FHk~1>DR&ui~Db_Jylb7j;~G$J`NPS-sI%R>hf@ zr`*nxRmo1uMZfn?IoK_ImSsY9=}m((?nr8H2+Y;ha`B(`m&K;#aW$xldE?R;p4u&A znb%Y!P2%qRozKwMTwe#4;-8;mzV~_{Q5P4LgkAKC3E5=+U)$bZawmT*EM=*EQ;(k- zLcSLDjN($N_4HQ@E6#DdxG(hKIzR_lJ4pWQms=yy(N|a7iTQTbHj8x;!PDuI9M4H7`L!z4p;x-@OIlGz41oNE!-{zB-EqZ z(sB?Z%(*$}=Gjw8J;@_-+~eUYzQw+A}5pV8?vu{?U0C2*%MIc?aseyx$Av!KTu|qzSb3>R#N+rdoi;ewAlQb{zUxm ziWD$|aA{Y7H%Hl7fq>Bdt4LvC=wxc5?BZl;Xa28Nv8cV}w9$&*eJ!&CT$st#kaF~8 z))3nq`{&?dSdZ0_e4#6tQbI%&SqG@GK!^2dqoP~r`V~u7@0a}ibwCnLe1JvA?eNwu zIRY@qF<#crb%6LzPcG?&k_CzCYimzY!!1S6A*S3m7%nK*u;WgjFtM!#Ib^wr~| zp?SaQx>5YN@>}b}Wgnq7jrz4U?^jenfeYuyJwY0pH0f~;v~+!sbAxro*sC+a{$qCw(;WyR`PSeFq2 z_gg7nXF&WVu2&K}EUbuPU-7${Oi3=m=ZX7nK3}bLPVa+V%MJa9PTxl>4C&3NUQS-#xaewBOeD>K`pmO1 z`4|0SVN)Xy``mVVh-;+*%*@&tCbMx)S#79#s1y=c%a(b>Y)EZGTME&oSxs}-T2{*1 z1?ANz6ioM$C64Hx1VH~jrjBHznxzwJ_&aLXC-9+)c{qC$`Sa$74F+wcV^0S5%Bh^k z99``)dIzIJ^kWM2+oXp*?j;skq#$HV6Bv8E$dK*kDn*`hWLwj_)Ks+KUw6CUx-3qB3+J- zN7k`#x(vPyzc6^}{pc}7##~2xB3NAJ!MwiQ#8W?Fb}y)(o7mBzw$DHzTn?Uj?QK}* zD`658i(;OBixg42zJDqiE$2&sHt7p5deTA=Yu?bF6qE1~zKYHM(orqTC|`d6c64J? zLT%Pf6C57y|sG1^)8r}u!Qy`~FYG@f({ou)~ldqGtqC-!uCatu-0$omgGkz57SDnAtR9}N*%)NJ4%Lz>KScFAgv2{r*7E&0y(vk1flZYQgjHn zD}vmijbNOFF@VUhE^n|16O5I$NvbJ!Lfg2;<61~%a0?Is?c3S`TQo>4pOQb6z--gh zUoAtbkZwzkklA0|Q*5zJT^14B$a463BI1MXVJ>U?txzWAnFgh zhoq~Uh{`~@<;ynF3}SY6z?4oFt;QzvOs~3|Z(R+;s!POD+D%j{l8gl}XRR&1Ml8z0Hdps_nY`j7l43-!>Z^U;DmNYUg@jL;STMP8~m_68MMeyZlg* z)ZVr2TTq;5N=awBSAQsLec~gwxPX-zre^lXy(5i6Sr7SYTe>dfoSWWH_W++=@jf3^ zid8ZUW5;YyC`UXrR{0puZH`k8K`)z)nOSDbtc{5g5L|N}Ym7g~`mE4ZFHkccu_7)s z;C>EKs8V{FA+9h1>^SUl+;8{D$3>!Ve`>yQPal{$8j#bJY=K6rLBF%u2LV+NHEI$! z{^khRWOIDN`~HqK=6)~;3ua@uPBB^(9|dX)qxJrMWEjb2wk#=G+TtB<6gdeYDBh=X z*#^`nQz{IKwzj-VXds_GAOD+2?Os&EZWeK0y1J&d2kNfR z`jM6eGfmh6jwAg@4Z6qp0M9^jp)ML8Jw z+yWTk`CvYUfI;V+_~1YIFVIrDF*LSqcJOq;N@b~&ee6k)1`Z{li00*5?b7OQ;D4eI zmDKietrAy;BDCHpdxC3+OsU4k?}xPbCs06>qO+*Qgpigd-pC*%LSCISZ3&Wxg# zqVWAZQo>DFC99(bLnL@nw4ccf{1(A^d5Lzgp z(Qk)oUUch)jqZ@Q3C=()7U4avEeNidHgI2D!ApLENO_%d-%{2TGCW4*N)5aKK60F_t}Zg8Hmoh z18YGF?4k2S+C6GT6KyivV=~GpMA?PQ1ShpHmI-`a>g@aE74fib5jeJ@0y4TzM6B9E zwrw3%Us}x6ne7nQ)$$kS>Xqq|J#rPc8B4KoL{*pCkSgVXSce@N0x9Oa%jOE zGoOoa*&46MmJ~D$DJJ1kXcf;;mL>Y>0<*a}MC)aq0IHbwtHxXcemf8k0ob=)%xbMg zrwMaYk<0?;9Jl^gfu>lDQ0o2iZv+QhHRJQ6iAI)=X8zFO=mT|mjUU4m=eh8Tf2P&A z;)Wi?+Y@Js>wXEL0>0J22(0T$SMyQ>rlG&8Gjmu!ryIR64!dHyk~@lG8*PsurKq;m zyVQbMUF>lB9Vg1=0twdllmYW_pCpp@k*=5xEOLd_HGK>v()mYY5EVLifmInqJLr5# zXip{bzSf|M{Sv;F>`nL+hd$?hYt&b`TpoX(@ca|WMtgS@z39HRrTZQQTguGI>KE`7 z^%L+^Vg;fFfsU<%bH&N-K*`mAzln)DNQ2rB$P0u3Tbv~S$q(G^ovfWLOif*!>GhpV zZJg=i0i=H-7);)<+hBkTyN0~LhXdZ$rQOh7FQ`Z`)r0^$Axg_W7izZD zE~SM|*d+CRbsTG_(`+E({*?+gl}qS9H$P-B$F|LjMV(|q3L~^1IH^ixGBir_;o>63 zbKXkhQAo;A4+hwKT&bbs6CS|FSktmN&yQ;Su{eF|EM==FJYk#1A~BgX-neOKK~?VQ zH$t7~h?S%8rx4=Q-oh&}2$}hNt$+LC>dVu5IgKa+q3U+iw=HJcQZ^wj2563OP_3lj z#ULXRNH)jK2b7~Br1zeq2ma8S2d%}(cUREY8y7+;QvcY%C<9z`%L zR-L`bWcF@-IRrq<`xw1K>@b?JSI_#uBVX99M+J^&?-d=_>_4_R^wg|1vYM&o0ZG!Tuh&H`=9j2?>>0^-tPQ21=MML2DCq_8~x~EKlJ)gl3^XB z`3XcnPc6z_TDs>yIKa-qw$}_ko;_G(>`T}e){YpmH+6Pm6J4BGWk#TjYiUlI+Pt7V zf?Z$LiN`Jm9;A#t+N2$1)A$Rjgs7P@s@9mNvQ70TVDv}b$81nC5Xq5a=8T&bY@oN}G z#_jV8Btv+CC-ZItc&opxx+~P_@+r?QPAB!ty~HqrU}nsJTH{_lk_b;~G!7Mm_i3Ja+l zD0Ei`%cAkzp7Us*r-A2c7ZrkmVZzbek@_2zf}&{9SfVm2bhV!{Vf#M|VI)LFg7DA9 zuR)%)!}mDc*-kZ8+dF&6M(PqScZ|C>?tpf>GMcaJSYJXOKN0`T_`^8pM5k|kK7#R1 zKcm-=fQN#XwVS7!J`uo*Z70t>-@yL6Kw!;}_%`rAiG}|D#i#?f+ zT0q-Fm36&gkJhgRw+PzkzOLm4ka%+vzq0;`K$^7gE{yo$n|c%VUlCY0PtUxPprlo^ zMjvkh%7y<;KRFm73#D8@AUr_|CeV*IwMQFD8mRt z2NNhGC_@KRC=)1C2jF^LY&a~qzAnIBxq7;Y!~b-Y@UF$z&@1Halpq8 z>KQ0E4R?|Ezjk^jM|;N@qBlZFLIdLivx$Nt;{%~3n1EI1AQ(Vmz|#>51hMe3a9Y8t zxb%(uLZf-%NRJ0cdKDPWt)5ToN6dKqhgPnyS}#+p-8!ZXpS0;8MPahTsxz%rU@H8& z%pY#F$kokQH-yUeT-ZB4=e>H+VTD<}g24EE%GM5_%J;TXCn!3=-D_5NFMZjJpRd2PW+w78To`qKs*q;(9PEaFI8kGg@wG^)sQ(yS zTAyrm@|MBQ9o-1PS}s$qURSq{F{x_O>US2=ceq}htzRW;Rd`!3a`sum*Rt-68cKBu z=dIl47^?asoArr}x#k=FOlL~k-8N3@vuD=ekvSso%%@utF;Gui47(afw`!kA-FhtF zzjyA8*-W~H$fv#5RHWcBw7y})PyNZ>ssAj}sAm0`oV+uhJoR`#^^y7|%_g1O_LVSx z)lKL|_?sZ&7-ouf?Ct%jP=4u9f79<;&7a?K(rbU?`tj@2L_gKd&$Ew4l!o}|w8Q^> zKKV?3lRqMg?SAUDjv{5}M6EFFHiSR0s+f=6q~FHI+%1RN&zocHHtpH8Yn6g57hay* zuHG!#^JAORrrKbyAPaRt7c;#^DVA!I3T?8%tGuwcNiKz~(CR2e(kT-^VG0%QGwI1m ze_`H6;`VX~WjJAy04$tg{ZSy+$1SxM|mCSE&gx6_^ z^fzs`oA4?N_B5ARYt5s!El=m`q9p&%m&?=0B1AB*Tzx*m9{tY)?3m2BFP^4qpFf`V z2AB23{IT8`Ipc5@d^GMWM!EHl6Lpc|ojX+w+xrjhkCruU6X(`a>X2e@Je+oT^p0ZG z%~lQbX8e{LL1yvxF{oa-W`tRDT~xhMy#6&#%j==c?%TR9u6Cx+HREq76>1)=zs+U0 zIZWrIW?*x8^y7ZZe)plarS7yG0sp_+d&{UgwxwYg5AF^DLU4!R8a%kWySuwf@Zb=f z00}O^-Q6v?ySu};cJ{d^+3cM2?e~uR=Z-hC$AUG+TK%l<>Y80WXVt8lvog%XX09%0 zGLWazzE`zxx~p`U zZZFCg)?IGBrrwHC>F^<13Jy@5Vo~)rSWijX9Z(T1E;XGPmy!0!O;+RTK05eVa~y6Q z#8-|;ll}8ksjNH&^@1K(_1*|e_7;jF+aj~}O_`C>yZByS6t=wRVM^$`#r+VagEGzO zb;r*iyi9F13$=n4>m1&sHAZVRH2NPTw&!51;LYOa(w#3whM>6->^T-&-{D4NWFxr^ z6yGX08Jq%Y9NtV!9i9(2%^o|vAhj&tP%*l*keV{<8XV%uX9mA9pFmnpKr(GYtKQ!W z+nve5zjjQU-DvLG)=>I3s8G2Q8h+OAw4XRxmDs6XvcM3g7k;rBIE+!EGD)j$*I<6u zj6Vfc@|3b)RlpQVR`i(USgL&Js;GI|#G)}r)7|A%oPJwgXXd3mIqcT-vFIG{;KoDG z=Hg86;)xang}1tUEY0pqq1xfn-JsUPUcJYGL??VQnr=2kWMGRiWZ1v|Xu|@?YgLPYuUPQb=BD}*dU2Mneueg zvsrz++vJ4OhM<_@Mv}xf&Aed>$mnD?3@Wp88K;1aF?cqMh7!K1u${6iqx1{7%rMhVn z+%%?z!*W#~j8Dm9Zudm>8!xsFhKp@fi08wc>CIGZWwF;5`B69>8#SB9q}Te&IyDTo zu8ydtw3xLd^G5ZDhl|%Q%O$8RY<*DTDFlQ}j}In4D?pVaPED(`>t)YbXV$+up2o zz73$D7uR-ek8Y8+qg?~zzUzo0dbQbZt^-u(g&O9MNI;xM3WTCrY88w@rVfUQ{kGQ{ z6`+US0dGM@441SMAf>UH`D_KDqYi*KpPr5emWP+Sm%EmGm)n-1^#g!ZB4D`%YO#JP z6{1TJsme<)|G3Z2wW8Odqk4{4?TBrJ8T;Z*3*rVPVnias$(8+|0Yql-wTEQc2h(sF|ajIte}p?mUODvqb<5pE2ERoCVjWuo{%iz zS%SUjQR`l=W_=X`x43BZ2A%w=$$hv-j#+u@5-GwY(%wb$-4&(lH_7dZ88h?FliENLcF7`Rp^YX!I+ME0oRHS%}QMb;*gH}-5YOnZdthshijmGKq!usOW$a=OL&~}>5 zJt@KR8xDBSZ?x66GOKn40uG&t>P3U%l-1p_C+{2Jf^||=H}X9yr`}Bg63uc7pMzgX z!cm86_`+0{Xs~xHEo4@96)3xlIDKp14VRl|U+UONxB0M89egA!wED3?ybZ&WIkej4 zo^fm3A%vA`PPfkcVcYkCxz^Y1kqEbm+et@k>|wbgPD2ekK&h~i`m$oxtNkuOO2Dkr zP)p^eNPWg!YH8lqh4^l|H{q5{rkGOKDBnzX?f6Ls zx*QF+YFDd+VsInhYfXiE$ezv|e_bOnt4f?c3UAwlMyKgxqhE0Na6_^2xvh||m9rp^ z9a?=)UxguGQ8JOJdgj#(XX~<*3+)vX^JBlD=*W&=>KZy}C;B3m`_3TbnxELWPMH(TjTX=%#0 zZ!^wrHqK7&Hh9uTYi_QG<@Wkm(yt(X)`FnYmSW&jeuGu5X@HWR=hS+*9D31t!*cK0h4Er+TlH8~+eb(B(g#Dwd>uPV zH94V9kggIzjE2{E9@IuQ3a8dAO^aP#eH#VuytE|8=MNTphh6LAZ4b3vBNC3ng$g`3 z9!2tqI-IFsSccHtWz;apZzkS~?{5_4M6x=9cN%rbtIyo1wDF#uHjz#`4AZ`cJYrg) zqb6V#T+Q*jMW7VS85`r8va5&pc;m{g6Srmo8jtVh7@(ho%lN^L;-(?1^k}fyc@l5W zLBcW!`zDWMtMk@jyGV^?ZH98Db587A1e>}m(qZO<4mAJM!)N8P7v+{)(AC2$knGrH z-TV2G8)_sa1_wz}76+0~`vq`XPS&d=YH1EtOPBhMhV%RP*`{()!$L2CJ+U%3)ol8k zhCZih-1=B;ebIO{3tMyuSWs8MY5K<6?A{%rViBq`a4}2W&N`)RWqIv>lC1F1#?;-< z{B)<2dVD+FYgw;a5j?h=Zt@~@qu6MJ_{eR%^1#;Iee3oMZ9)BIkitX5R{f0V(P-Kd z3%U{ykK)r4Asv#v8`S|@LSNm+W8>2OWOLKp^rHNJhRQ2u)8n7bepn#T6e3XN0h{t$ zi>on_h?^i-XVoXW#(aI2y$xm-`n3W5K6g}>v&7ttt<;<&^npi5El%~0J$;$MoAgL? z&w`ReHZR=LQ5|>5#ubiRB~)aIZHI?M~yWDhIR&R8Dv@)nwbR; zwKyyu_NrCzkH~R^jBgkMxyb4`wWgGq<)XHP^m_K)2Y1=}3*#4NM`mPQsEAJcaKpt2 z8E`q=BGqW9ZBx(IS|^J7Oau!Rx}jGo@f1Dt6W#3tdApzwUd)jc4Znl8kJg2u+?-io z%j&x2G?)`UDlh=!VAc7;r~e6JNi$qEjsQl-V=(6pbDf0h-0?&0$I4x_ z)b_rc>Iy-c#r6GD{e-b6>0{T$^2P!h+^3#6b;pyXHcO>Z?23>{ty)?xj;&-%he5Bc z?rcY?>icR{njQ_i3YMF>l;$T)hl@9BLNROqx;U^wfK@raGW-v`?3~Bo|C7NjU=^K- z<$k=8G>S4}w-&*RciUrvt|(woVA6D?go3*wP{^OMeSnY&1;KKhcs~iUL-MtWjC#w` zg7~8DDD=s661*z|COy#JIS7Tgx@eU)lheF{ zF1zSN)MAO%i$yi)V{~uq{REGr!k}Rnv-}Qhl2`e4>nA2^oq%R?v4c#RhAb+a9g^9E zq2a~gkq9#zF>yZjX`Dn*ZlVb%7vJ>VwfQ9OQ-j7!&KncU9a5xm6)@D^V|C$v`BUGH zA}eK|&5&+Rt|$zhrllNQXB2gPg4bm3_pU?siQeP2=8td5PBR}II556BLzyaLY;rk%t{g_-8QN;cUk0V9h$6jqWF<&CpX_wFwc;cT2+Mr+BE3L3pSu5R z9In|ee?Tg_hmb?_Y#G=K!$via%`QQ5dU+G64;pktTGSsk#0m}sO0uUh zFm=BKO7xcWf4QyySa{e33dpI81d4KooIb&Q80APbjd590MX-_#b{)qCmPbcHLZxqY z| z+N+Z9Std#3K@sXeh9#`f}FL3d==QoO1D} zV+(|Y3X zahZ{|B0H%_58rzvI!wRY)J|B+f_!`f5gG3x#x!oWuXJw#;#1$6QgQo*#;-XdC zyDcE3G|$|=!#UnY!C}_4zZQT{KD%Dc>=9dD>VGMj{>`-4&{2N^(cFMTcx^A|$ZzJu zmr>RXtgX-aEb<9S*rme8k7Mjl1=9J-Z1W!@f|~H8CpHS{+%*>mI;*3(C}A&)Hq}ZT5!M}SE>K&eRyID@Dyq>qoi*9UmKhaU2(%P_0B1=5OxSrc&?ls?d5M5$5u$Iz zoPC3;f;JaT_C`-8c!#QPzjz?D5v7-$)Jv)bQm}O{JH!xq8nvs~;M2-(b#I-~WMe5M z(FHAhK`tJSku$Maqpn%wc3uUxU3Jab9NWrki5Yz^K1;2&ayc%s@a6P^IJp3dP>yEK z9OPpC{PmHw`x?`PamU3}*u?;f6vUSMuUNb&xkwrR-ma~XS!WNDGKA~hN8-!6npM68@$Z%W#Fzq9rM$ zX+=}Y=K=GUQqt=)wwc}2#iFZ_{B)^1kB6D4-naV49&XRF(c^={Mji1yJCB1^H!hFN zPdFQc)vu3XhU#qJrwkuywZEAu8@2MFd*`%C&ZrPik}UE%x)55^0R_5Ei=mq5WyTzZ zuF~OA_!8%}KqCiU>S*r)31Y0ePP;))tOstjn2edb7pXR-=7tC$7tbeIR~l4rG1NXVSqc#H z25ie-yvtVq9~lj%-$vuN(fDmNejAP7M&q~9_@`5h%)gDsZ=>Vx zgUMw3Kk~q^{An~yK9E)NkwKIih-i940t?0iA@iF; ze#syxAafA}MesvnCFAmLbeFy4NQnO1Vq1FNGJ@-c#T~{2I8&PBC`VY zcEY<1(|GT2R#Z9w2rjB1U;zo100@GN0x=`2hayDFE0Pzrd~SDc%kjQir!eIm!kuyr z>qUR|9Fs6BP)dV&I?ZKbQG|N)u1ommjz$+O5=^(YSK@{w1qHZV>Itb=N>p(A`Irl} z{cyF2w>N#gWcN&WZ4>noJ}U2_Od38JBZtM2_`EQVM3mibLK@);5`w`#M8den5c)8Z z+!#h^1SO2qZ2dI1eAD2`snyS}*F^4?os``MYkd3oF7AV**_l%j5-}VmQ)1+Ws}{BU zC(n%AcJ6k_O=rfZ7Fpzdt!<;KjacOu2NOkCG_D+QflhZO4dK_q5o!IQGwg;s%Ckr4 zX#A>8ag?1a*#ck=MID(LXN)HbPeU)yXWjM#kvQ3+67S{{X+~n_DLT`j9-WCt^mV95 zhjLhRriAy@Ud$GIvyEf*+O$Tz4bO91Br4n{eo!MJC@jLkobS%rT|9TY?RyMPqx+u}_!0r+0X1gC2Xh{%ELBD;rjQ0$jy%)NpnTv5>6-vBtb4&HK|6`+HG03n#cc`Om1z*d>edIVhcJ536?- zt&(sjJLfi-XS-aG@#5{2TixQp9$#2s>WfuNeB36b-_qH%N%dk^1(PYvTj}QE z<73!Ji;WI#_?T;FR2GP^ny{~H zQ4a1ShHIvaVZ4L7W=U=xAnjN0zrHG_T=+)G?>t&SYKEwSIe(sg)gf=QxC?1%xDs`v zy!VOh^PWt5$fUApC6;JSwV2xF8xXlN+||3XvJ7}`pJTQ=#)X2xqNTPH&kK+O^Q58@ z9_99r_taq1#V%aQxi}7@>y!_KW`^s%IN8qM*4*7ByR4 zstWY(7L~a61P&*PbR~YetZ-q?R-Vdtj?wW#WIuj5>??fi>W0FvTP%5EYGy{m?|zGW zKbM;*t1R;N-`lbm(znHflFyb$hoeN*R`T@hwi8IRG@%Hfo(u|=qH7qO@q@+`V-PWN zyR`Fl`eUzEX*foG=Mp_u=A#Ldwhn#MD&=8>wM47DNO+>-48`ADzbRVH^kd>;h#J?S zp4!LcVUnuH)+eieSlcV^Yz>EWk(*EOEMAzpYq!#P4du22dCFq}i=!Z&+SQ?Ih|0xP z<&A^qf9w`aqVrm$mV9gaO2=i^utBg856+?CPCjT)B=Ujuekb(BEv8QLVWvV}Q?%jx zh(}LDYP=06U^dvom@QJ6@#rG-&3A(1#rcR*_Z8jLrs^k&i76w;F&B%Fz-;$EDw0QH+}s;F1)^1wXVy6CK6NSyZ?rFPttOOM2uTi)Xv+yjE?BN-ii6v7lV_I8*JH#> zBEQM|O!7{$0nbvOJnQ34sMvb^%cV!5*4mi%?#Wo{T%ruXcI+jz{Ohcp15Dz+4In^3 zY|wvX?R)~#x6+fgwX(LO)pM}3x3c&nVwNE54u~uR=zBcIAFi4IWo;mSP->12v+F44 zl1E^r{H6H8^=sy@sbi7ixQV&I9Q(3tk7T3Rd8YFbru$y$FcO)3F(Xxkk|L;kE?$vq zS1#iZ)^dYcaVm@k2d?z&fj0Un`3^g|jn}&jFE}HxX;b4XW|K4Ne* zNxLZ~^yorT@zILdp@`XjaJv73bNRAf?ZiQ!QfpW9-cBGW8z}&lNRJ*2G7A_{`4f;W zWDGCEfFScDn(*1+Dp5pAq3?yxfqTnhaN15r-6?6sO=K7C?J)!d9OMq-hIQDfeQfy$ z0;2w|6cXPR-Zb0fl~Ug@yDlAU^eh>n3~!Y*os_LL`r#cQ2M&b%1!n>#Mb?ep!vFG=RfWAQ>u*y6RQVL)+YFu~NQWEqCuCWbDr%z1;^ zAsJ0F&vIaTD&2gOQ}8sLclx^$M2E7pC25Zo7iASOQRsXmazOl5K%hm5-$9#`GqxFj zzy(XL8ksRn5Nq}X3BSq|HW*LLw{I0XuoQd+6ZQ#$d;<*e6;f0O1rSy_ww-aX!HX3` z>Z{t(oCdm3h3)YQQOUua6ifE)lP~V>PwA4zvr|sE=wDjL$ReQh%C*61k=u|Hr8Dhq zonxb%t`4~6m<`Zn^210}3kdDaLg>oSDZ^0QoKZ)!{5$494XsdSAwFFlrYc0?;Hj!3 z>-wXvr9!Fu@ex>y>zC%-XA!@kn!xKOL!=bxKn@hdEQ% zRDUeu>4X;3$mN{c>YLVa{id*?OVQY@V+BDC0fCCE*r&{Si!+er;SWq&{s9M7n%P03*}`%$6PCV9OzG=G2iHgnI$8seZW z-S|MI8G35y!brz>0~@EbzpE#+BGplBhDj%{@&jg9>}e_Q3us(_Eg4^^&BbIuD$0e0 zQyLY=_CaSV=qFD%o7zs2+)8-W_h(-;4-p>5>P#G_{nR3zRj%d=c>P{103aIX@& znnb~FBO1(H4(m}iZTlJ}Al(V2q`s9k;!9s^w;Y~N(i&uiT%;9g&_FT#qL#VZ*+a@i zyks~>z>GAfORbR9rG9l8fNc5l& z!U{Ki-*MY8}x$Cf&5iLqkSI z2a6t(Vy_95Qjy4@LrJ1^2IzZ!!$S=%d0!bu;0q=I+oPK=81^0&S2;_Nk1cgY$`tKs z+~U*RU8Wq)&Az%=?b~zEfNfYJ9rZVaW2o<_kW*!;q|qKT%RibnU0DRQpV(4e={?zR zPSwBMbn;2o8KT%y zk8|iiFXEP($1N{#iMy|W_LrUPLhVlW6!3`@z+Pekkv;2V-)-ynrDz0MM8EE7&-$Kz z6t7u39c;jn-$T%{n=T8Sh-x%yInBu4H*KZ0p72*yzD2R&Wl!8esdXAeY5t2>(ss9{ zcDA7SuyyeV46Vr4(86oQ)NXDs$C8PC0It6_L;7x8gVNFitFHN*A`KcT<;}k|i8?OyT1nP}ZRGE>eg@^o-Tl%6_Kxk-~ zTq(&#y*55q%2*3ks# zc|_oBE{)P2mF>J1Xh|2Wt3L3_$NcsX>Mv^=08b;|+bh6r?CFUM76|B%*B_A~YWB7| zcE%dCbbv;quVeqm=l}Zh?|;7~@LK}ECGcAUza{Wn0>35jTLQl&@LK}ECGejmAT0(8 zh6)4$1PS=cE1*Vy-PciocXNOj%HM`=|D#cxc?1W18yzBeiSJkp_4ddrqYt#q21plc zNKWDODGmM--V0uzSl2W|JV&Ai2i!^Fm!hYsttdv=oH;Z334@`VWI=|q5^g{?F{G5# z;0Y?u6I1j);>>p)uP8Vjk1I_oTa`7&F!%lBwdlF(IVLCA)GG!JL|)w!;92oblj8eg zJgIlXyuIeITm+oT-zS1%j`p|yNSfjSSV{jM#;D&jX8hAJ>epB;vpG7{&ZQT3@VrOm zRBDc~vU%$WK5fu?W|<|??x~3?(I3_g^!Dqe965yMV$IFn7^YX#?2b;Pni_7i>Sv6s zn<{hp7)3^5!^$1ZF45}h7jz;Fxgq63hp<0Km2I2eTn-u>(3&FoBTThA0C9!V&R#bx zDsJN}NjJ@)n>DNz;8t{o=xMIwChTR+A2TiFnBTn|%&L6P(8L#ncnibV!0wICUB;E@ z{7pGeFgRxpWsb4Pw@ASc0_9zNF0l;%*XgS|{(hUZphJX_>%0xt+2vUbnmUCc*ExRy zl?UTvg2Gq9HXK=nP@{*JW(dLeZzdNz!8MFqV@6HTe9blxThh;1@gjTa(@%qerER^= z4%bj;ys!=xMzeZ-sFT5I?2>dyh_#1gBhX^Nl^8ybi#N>D9CpSKoCXkUkqq$ARqc_kezO+T9{{6LU3ENY3M^e)TmfcH|K63p1TDH>0R;B;KTr4k zkEEvl@BB=UexnQVamgL<@%*}^QT&;VH0KohZ0O4MLeXO4JIzX&dFNjnUOF09%`XgK zdXVoif{;>)hCS{ngz*<}_&+yhB%nV9Zk#nE-#OO$zLyl$vNNZY&Z_s|YWm z+gG7$?@Q6Lqe^+Wz8SJ(`?y>)iY-Jd?!kBYZt2Z?PLuV*4N4!2HrExzLgC%g)gg2y zaZHazC@mq4<39-r^z0r{0hPfE=S zWv)EW|NbtO$YQn_F&ZH)iDlR-&8X_SuwWb1ePn7tgN-syxX6a+e3 zzyNMQ1;&TEuRk=&KHw`JUZcaZ41aKNuRmWM+Z;ii?->D$bST{`|IF3CTUCMp&%x9v zwK9k_;$E~8-~ePYXJO3x4<8Q5<8a9rhLpH`qH!rcw`wo%5N!xk`IfXNzN#)>pJHjXRpo8`+X;LL#x)Pw+tQ&n7(-7U#mlO?dT9}b?vKD8lbM=Tp z1iwR{;d@Rna(gO*gR?-E>9OSU&MD9;)1pwxCwZ7~R}t~kH2e%FAfN_ zB9J6Vig;(!jZkam)NT!S?R)#Z0N3g7`W=GTL6!y3?>c~f{|Ec~FK^60nqm;z1YSd0M_^7X58S2*7dvfwE#-( z2&GS})(G`fQt3|irFWOugST6BxUM57D-H=Onx4cM!hG_JR-P5WTFSD3JOh8FX~7GV zK8q#pj$1fR*fC-e{4!96*Jx7G4~l5GJo>W+RSEuuzoHn=@XQt6_0`JQ>`-`#!e;76 z_~b^y#xcEXCQ#mW0a<#w<-w8V=w4hqa^Pvsg0j`}&v65k$^9|C!s@Q_L#`bD@+uF$ z=V4i|f;*)c>LHKXARpC7y%L#VF8Ixt->G)Wtejme&7uNK;%s&W{awP%0u;&}hq$fH z6aUnMXZqocj&Y=u7L-MDGG=D0umd)%-Q#cJMKrmI)W^)-#0rzKk^@L4FREtg;=g%=7^n79dbteu;Z+P-tfL= zxze8DO{a-mGTH4Vx)deVK0VaUYzP@b)$Np#fE@Wxc~ zEFV&a{rZh8t`+kfs*`n;f-C`My7!+_r}jx;<0(Zk`}H$$3u74~*;Sk>U++3-SlK^X zyuH%N=eHujzlE5%NfJGMVutf`x)wY{r|ZK= zGrQ>aTKMIogL*tE;U5{R{+ky3NZj~a3;r~D04)F{umoslx=NDz5ow|Bf zMj^(_KCnTKji#Q~RkHEUr|%VH2yqex#x%_wQ6T!!h{FsRq~R4slY~t~TJs)~6W zJee{)-Y87t^k_5#JGg#|zHgRjUw(<#OAVZTkCeI4#VrS20!u_{#JwMYM}F74eb9=gMKoA8oa2-7PcAC?N{Da z{!b*gk3^uVj4>5L2d(bIM6UX71VWv^P!5u^^OssQJD{{F8 zxy01X7JhIhErUW1z&r%UT<~asZf!EOPtl;7;BIkv)|qf zN_|TEKv<%pxx`)c4Nj$$xN3Q2>&950y6ncB+BGu4oV)IejfTq6lR+wmej}K3SwrRi zt~+-*zQv2jnbssb6D`(+m@^S)yqm|JolZvU>=8FNwj_u=yuxEzn)WYTJ^@2FU#x^L zcQ(FkX=rMyi_`j5OXA;^Y-)QxO|lidODZw%CC{ zh~DkFdWYm_y$;dJ2(bvva%L*Ddt)p!T`=RU4yCC;+8-M$s6cc9MIOIKC?ea|RcsNo zMqEJO$%I#3lZ8ZmLLaP1EUh&~UI2DFUPm+TtWjZlzIk`#=~}ogE^9DZ)1b$cAYa)A z2Jg-~I;iQZVj$Bpvu8WlF->HERm8fN>xs$^41>aBUv?m_m%yg8O(e-$=0^wIyAelu zK~}=**+XzxLK>h&PFI6V>i%YhAs;wL^}LR{tFN+LZ z(ZJ`=w{oPcarn&RI>OMT7+@C($(8GKuTt2F?w)fOrE~MlR+)Ki!W(IPpgPAPvtG0g-mmwg0B;@EgJ z)tFoEaSC!9ML3t<71dl*tM)m}s<+db^}gri6~Pm%i;dJ)^O{UZl(? zn6H~8Jj6*>{Dl}>n^0y^O2d7EEl<|4ihEZX`y+g6yXbM?ufaJ+CrIRmBNC-zFonyG zz>dw4Q9{~#-$FOc9CQvAA$JB{O+VqnCd~Gtra(n_PkSQXu|lqQ)_w&dtj&UMYV zQidWmU%`rU${BVPiMm^1I zfC0Ck=?LHQYt22wo?gD8kk|}?4W%+kL#0%wb*B0l#K|c5kL4-V+xPp!s<#tSg35vLcc#?wiZJWiW10hJSDSzB9`$rHE-ynNr(=rnZkB z!Qb=)-O7|@c&d}}Zav5$TOA( zop!Kl&33MrsgKy`Qt3uzvmMbhmBgo}?fd#~IoX(npWg8G2ch)?s#r)-82Th2UEZ3O z<5*YI$=bHeS(W)?^Pszw`S+M1`xT!e%<}6Y!E5CLCG4pS?4(YUzN5h&X2ajP5Td>f zoDdP7$M;$m0SBv%T^_hqMz^P~y5oY>>(c$0rSA)MnyKo$O3>01-bhrc(qY_j6zEI> zO{s*K=4m&926w`Ny_&#y9q#hkL*g#d`%6ArkhkvmMCd%G46?)reAWi}l^e25;Mgkl zRe`3kB1Dx07Fb*kBIa?C7Q)@vDWy=S^p}W^7H?avF&Xv|(@*Ll(^gWbLZbb??Y=k} zUi7+61@civlgBgI?U4C2ximA*FLP?aaU(yx5t2A^x^#d@VR=f)P#^I6t?FVpUlHVP z*kaG!u-Fm*!JyrTL-?8#=H0=5t&bwbiUX;;T*e6DIXR2$I(Yeut`Bqjp^}mRo~7ei{M`;`gRsWl<_JCBiIVNc+a~!RaQKE0MybPhyu5o*pv+& z)vmCDP>puO!Tf`4pNFr_?kV^2M;w<&B6xMMMjx=74md>lD0P9<;2GHNR}#VU{+6iQ zD0PEu)eN2*TI@kt4bq)2(D9W^7gqC`&)%)Pv2U8GBWmzl6{esKm=-)SXk@^ed{lo_ z@>H3?dLz|_#;80VPsu+_emO6NvODM2N2L^Vze{c_CRryrZ5&rUDd?DWELjxok;x-n zgl&s3QUtO6(f5l`D}JFi=x%Lzn?*S`>l<*I6@EQ? zP%H8tozdBwlOQeI=#_lroT;TG3~?LO+u$0o6u>+ zDd}%33dBI`tl*j>8r!&*R@y75S5{H#n_aIi_l0U!Bjma1K@zt5*w?r<8qiZwA+Ahf zq(2V58;;?>czce6WW~y70hGdO#g^qbeA1bQJDbQ_)(%Ev?XN_IxtuPphbq2LexiY0 z6C*HkF&Lw#N65kHQi9fFMot$;7#bay7~|8LMoXt#MsFt1FoC`9JT#-n#Xn&(QhcTu z$~**p+Iep2m9;ppe?24+JeLTgO+_V>rCs&_|8Mzt^mCNu_$?Oz&^ z!(PXUr-&fY2g)g}m00r`3%cpe;m;i=Mxz{eO4v9fqTRNXlr^?Y=48&Lu6KJkD8be5 z6dcVQY%Ri!8=EflPtuKV>RQ;E`e$j(pcn{>8iEn3Xv8jmntdp{%qbj&LQD!$}NqEa3R_og_v57`!k5*$d`u!fGN zmg}!p=e!kV1KBF-v)pH4>d9AMew%>Z-y@)$@#wo-eWCltF=-3@C=IpNGpk$uoZqZ_ z_<*oTpLPu7!FLfRY*ppLSA|XzsbY)*xuEUpxR8umLf=7mp$)o0)d1JK`V1IqJ+A;H z`Hn7Dm$$TXiW2(hl%vJ4ss$>su9Hp$Q=fFnt2&%<#&$Hyq6&i+8=`l z{|LxG_%$Co+P6O&BZ_lEN;nk9njE&iUEPe~%kWeaf%nd)EpP;KZe6AoC5v;()`CGo zl}cVm1%f4A&!C(_#YSA;(@ne|FO%3SvVGsRyaTL>++?P$sN^x8Mw|B<25+=+_P4V~ zljy5~*=C3*FW6w!ob8CHJrv;t#xLZ;H@~17%Lxvmp;O1`)z68aqC8*nXpyHHNW0zU&uv{ zI)$T_!4D7Vzjf9|ygX?kI9T)Ho$m(qYe0C>gqF?Gjm;jUSkZ3LZ>lwl5G*6So&IW> zm=sZF!}<>0?aB-WM{)x#EX<0?gj2F8(Bn+&-{T=*5Nbe$ z(ElfpMakh3zY#Er(E5E*-yg%}pPL%L6`&-5rM;HCi?xBB#vii^(qexFplCK3fB*nX zfR%xOx$B?WCBS9%r<3A)35Dl7(iPoU)dHeQ2;hK#{)jO6(Z~ViOPtMV|EN!-Yh`8j zt6x=Qtmu&h{Hh=z90&Wyo`81TPoPxmpOUn0|!siq-Cd3<4H9$@qQIKbHLDBdn<$J-D=ag|(x{ucY z#Uf>Xek>I=zodMxIr5y+Lm6tCKnMh6H}ssc0+TYe$P7d9QxNR06&mGK>F;!zsd>l9Prnr#Xke2xq+Xpf&8VN{OhvGp8=J; z&jCLcQT}-t|9P?C4-Pm#@ZXjWK0k@S#{d4<7YN82u$uEnkjB5mGoAzf8dv)>Kt=jF z;QLAZ(%Ans2J>f%o$PbUFYWwaV-kM`e3E+(_Gtn{hrtW literal 0 HcmV?d00001 diff --git a/docs/pe-nz-population-source-notes.md b/docs/pe-nz-population-source-notes.md new file mode 100644 index 00000000..a51df0b1 --- /dev/null +++ b/docs/pe-nz-population-source-notes.md @@ -0,0 +1,98 @@ +# NZ population source notes + +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. It does not mark the demographic target surface complete. + +## Pinned publisher evidence + +| Artifact | Publisher reference | SHA-256 | Bytes | +|---|---|---|---:| +| Subnational population workbook | At 30 June 2025, published 29 October 2025 | `001e8a896cfb50f5ed17836dc815b235e3bcca55ee91c9869a2afaeb054b50a6` | 97,990 | +| Regional council code/name attributes | Boundaries at 1 January 2025 | `e5d53fa6abf742121d123bff970c77658a16e8c9b405b83d1a978cc22920d660` | 3,381 | +| National population release landing page only | At 30 June 2025, published 19 August 2025 | `b2d2751800857895b1498d87df6f03ac3511ec8c7a9b17cc3150c8ab56533053` | 61,286 | + +All artifacts came directly from Stats NZ's website or Stats NZ's official +geographic service. Their manifests record exact publisher URLs, hashes, +retrieval timestamps, sizes, and immutable country-scoped R2 keys: + +- [Subnational workbook manifest](../db/data/stats_nz/subnational_population_estimates_2025/manifest.yaml). +- [REGC 2025 classification manifest](../db/data/stats_nz/regional_council_2025_codes/manifest.yaml). +- [National landing-page evidence manifest](../db/data/stats_nz/national_population_estimates_2025/manifest.yaml). + +The objects use +`r2://ledger-raw/raw/nz/stats_nz//2025//`. +After upload, all three remote objects were downloaded through the authorized +Chronicle/Wrangler path and their byte counts and SHA-256 hashes matched the +local publisher artifacts. +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 +surface, **not** a single-year-age data artifact or a national source package. +The classification is geography evidence only and emits no population facts. + +## 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. + +The workbook does not contain the requested five-year-age × sex × region cut. +Stats NZ's public metadata catalog lists `POPES_SUB_004`: + +> Subnational population estimates (RC, SA2), by age and sex, at 30 June 1996-2025 (2025 boundaries) + +This identifies the needed population/age/sex/boundary family, not a claim that +the query's original publication vintage has been verified. The documented API +request for its structure returned **HTTP 401** without a subscription: + +```text +https://api.data.stats.govt.nz/rest/dataflow/STATSNZ/POPES_SUB_004/1.0?references=all&detail=referencepartial +``` + +The [official API guide](https://www.stats.govt.nz/tools/aotearoa-data-explorer/ade-api-user-guide/) +describes API subscription access. No existing subscription was available to +this ingestion run. No account was created and no authentication bypass was +attempted. An authorized export still needs verification of the exact five-year +age categories, sex categories, 2025 REGC boundaries, reference date, and source +revision vintage before it can extend this package. In particular, +`POPES_SUB_003` advertises **2026 boundaries** and is not a substitute. + +## S8: national single-year ages remain missing + +The pinned [19 August 2025 national release](https://www.stats.govt.nz/information-releases/national-population-estimates-at-30-june-2025/) +contains headline counts and directs users to Infoshare's Population / Population +Estimates – DPE tables for annual and quarterly single-year-age data. Its page +payload contains no downloadable XLSX/CSV document block. This corrects the +inventory's assumption that the release itself provided a single-year-age XLSX. + +No reproducible publisher single-year-age artifact for this original reference +date/publication vintage was acquired. The public ADE catalog query did not +identify a corresponding national 2025 age table. The missing artifact remains +an access/discovery gap, not a zero population count. A subscribed API request +may assist discovery, but access alone does not establish that the required +original-vintage table is available. + +The release explicitly says that Stats NZ revises the preceding six quarters. +A current 2025 observation may therefore differ from the 19 August 2025 +publication. An eventual publisher export must carry its actual revision +vintage; it must not be relabeled as the original release. No latest-2026 +population, projection, mirrored third-party bytes, or inferred age allocation +has been substituted. No national single-year-age source-package alias is +registered, and the national facts count added by S8 is **zero**. + +## Validation and boundary + +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. + +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 +downstream steps have run. Independent source-fidelity and boundary review is +still required before landing. diff --git a/docs/pe-nz-source-checklist.md b/docs/pe-nz-source-checklist.md index c0b362a5..41ef2a20 100644 --- a/docs/pe-nz-source-checklist.md +++ b/docs/pe-nz-source-checklist.md @@ -53,8 +53,8 @@ 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` | [ ] | [ ] | [ ] | | -| `stats_nz/national_population_estimates_2025` | [ ] | [ ] | [ ] | | +| `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/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` | [ ] | [ ] | [ ] | | | `stats_nz/census_2023_family_type` | [ ] | [ ] | [ ] | | | `stats_nz/census_2023_ethnicity_age_region` | [ ] | [ ] | [ ] | | diff --git a/packages/stats_nz/subnational_population_estimates_2025/README.md b/packages/stats_nz/subnational_population_estimates_2025/README.md new file mode 100644 index 00000000..07e1f76d --- /dev/null +++ b/packages/stats_nz/subnational_population_estimates_2025/README.md @@ -0,0 +1,77 @@ +# Stats NZ subnational population, 30 June 2025 — partial + +This package emits 85 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 × +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 | 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 | + +Table 3's columns are 0–14, 15–39, 40–64, and 65+. All selected counts include +all sexes; no sex-specific counts appear in these worksheets. Both source +worksheets are parsed over their complete used ranges (2,265 cells), including +unselected years and explanatory footnotes. The package does not ingest +territorial authority/local board tables, island subtotals, percentages, median +ages, or population-change components. + +## 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, + 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. +- 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. +- 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 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. +- Concept relation: `source_label`, with Stats NZ evidence. No Axiom canonical + equivalence, population calibration, uprating, interpolation, or target + activation is claimed. + +Every numeric value is a single selected source cell with scale 1. Row labels, +age headers, reference years, the boundary footnote, and the provisional-status +footnote have guards. The tests compare every admitted value against the +publisher workbook and every regional code/name against the independent +publisher classification. + +## Artifacts and remaining access gaps + +See [NZ population source notes](../../../docs/pe-nz-population-source-notes.md) +for the three pinned checksums, raw storage, the detailed S7 API access failure, +and S8's missing single-year-age artifact. The wave-1 checklist deliberately +keeps the package-completion checkbox unchecked. + +## Reproduce the bounded checks + +```sh +uv run chronicle validate-package stats-nz-subnational-population-estimates-2025 --year 2025 +uv run chronicle build-suite stats-nz-subnational-population-estimates-2025 --year 2025 --out /tmp/chronicle-nz-population-suite +uv run pytest -q tests/test_chronicle_nz_population.py tests/test_chronicle_artifacts.py tests/test_source_package_alias_drift.py +``` + +Source and consumer checks pass for this partial package. The concept-alignment +warning records that no Axiom CLI metadata validation ran; the source-label +mapping is not a certified canonical alignment. Independent source-fidelity +and boundary judges must review this candidate before landing. diff --git a/packages/stats_nz/subnational_population_estimates_2025/source_package.yaml b/packages/stats_nz/subnational_population_estimates_2025/source_package.yaml new file mode 100644 index 00000000..004e3815 --- /dev/null +++ b/packages/stats_nz/subnational_population_estimates_2025/source_package.yaml @@ -0,0 +1,1066 @@ +# Partial #176 source package: 85 directly published counts, not the missing +# five-year-age x sex x region table. See README.md for scope and source access. +# The all-age national total is Table 1!D25, never the sum of the 16 regions. +# REGC codes/names come from the separately pinned Stats NZ REGC2025 attributes. +schema_version: ledger.source_package.v1 +package_id: stats-nz-subnational-population-estimates-2025 +label: 'Stats NZ 30 June 2025 provisional regional population: all ages and broad age groups (partial)' +artifact: + source_name: stats_nz + source_table: 'Subnational population estimates: At 30 June 2025 (provisional), Tables 1 and 3' + resource_package: db + resource_directory: data/stats_nz/subnational_population_estimates_2025 + manifest: manifest.yaml + vintage: stats_nz_subnational_population_2025_10_29 + extracted_at: '2026-08-30' + extraction_method: xlsx used-range cell parse restricted to the two source worksheets + parser: xlsx_used_range + sheets: + - Table 1 + - Table 3 + artifact_year: 2025 +record_sets: +- &population_set + record_set_id: stats_nz.cy2025.subnational_population.all_ages + record_set_spec_id: stats_nz.subnational_population.all_ages.v1 + source_record_id_prefix: stats_nz.cy2025.subnational_population.all_ages + provenance_class: census + assertion: observation + sheet_name: Table 1 + period_type: calendar_year + period: 2025 + period_coverage: + start_date: '2025-06-30' + end_date: '2025-06-30' + basis: calendar + source_period_label: At 30 June 2025 (provisional) + notes: Point-in-time estimated resident population, not an annual average; published 29 October 2025 using the 2023 census base. + geography_id: NZ + geography_level: country + geography_name: New Zealand + geography_vintage: current + entity: person + entity_role: resident_population + domain: resident_population + groupby_dimension: geography + measures: + - &population_measure + measure_id: population + label: Estimated resident population + ordinal: 0 + column: D + source_column_id: estimated_resident_population + concept: stats_nz.estimated_resident_population + source_concept: stats_nz.estimated_resident_population + concept_relation: source_label + concept_authority: stats_nz + concept_evidence_url: https://www.stats.govt.nz/information-releases/subnational-population-estimates-at-30-june-2025/ + concept_evidence_notes: >- + Tables 1 and 3 publish provisional population counts at 30 June 2025, + using 1 January 2025 boundaries and the 2023 census base. ERP includes + adjustments for net census under/overcount, residents temporarily overseas + on census night, and subsequent births, deaths, and net migration. + These counts include all sexes; there is no sex-specific split in these + worksheets. Only all ages and the source bands 0–14, 15–39, 40–64, and 65+ + are admitted, not five-year or single-year ages. The New Zealand row + includes areas outside regions (for example Chatham Islands territory); + it is read directly, never constructed from regional counts. Published + rounding means component counts need not sum to totals. Source-only + facts: no uprating, interpolation, target activation, or calibration. + unit: count + aggregation: sum + expected_cell_type: number + expected_column_header_row: 6 + expected_column_header: 2025 P + rows: + - value_id: regc_01 + label: "Northland region" + ordinal: 0 + row_number: 7 + expected_row_header_column: A + expected_row_header: "Northland region" + geography_id: "01" + geography_level: region + geography_name: "Northland Region" + geography_vintage: regc_2025 + table_record_kind: total + guard_cells: + - column: A + row: 4 + expected_value: 'At 30 June 2023–2025' + label: point-in-time release period + - column: A + row: 29 + expected_value: '2. Boundaries at 1 January 2025.' + label: regional boundary vintage + - column: A + row: 34 + expected_value: P provisional + label: publication status + - value_id: regc_02 + label: "Auckland region" + ordinal: 1 + row_number: 8 + expected_row_header_column: A + expected_row_header: "Auckland region" + geography_id: "02" + geography_level: region + geography_name: "Auckland" + geography_vintage: regc_2025 + table_record_kind: total + guard_cells: + - column: A + row: 4 + expected_value: 'At 30 June 2023–2025' + label: point-in-time release period + - column: A + row: 29 + expected_value: '2. Boundaries at 1 January 2025.' + label: regional boundary vintage + - column: A + row: 34 + expected_value: P provisional + label: publication status + - value_id: regc_03 + label: "Waikato region" + ordinal: 2 + row_number: 9 + expected_row_header_column: A + expected_row_header: "Waikato region" + geography_id: "03" + geography_level: region + geography_name: "Waikato Region" + geography_vintage: regc_2025 + table_record_kind: total + guard_cells: + - column: A + row: 4 + expected_value: 'At 30 June 2023–2025' + label: point-in-time release period + - column: A + row: 29 + expected_value: '2. Boundaries at 1 January 2025.' + label: regional boundary vintage + - column: A + row: 34 + expected_value: P provisional + label: publication status + - value_id: regc_04 + label: "Bay of Plenty region" + ordinal: 3 + row_number: 10 + expected_row_header_column: A + expected_row_header: "Bay of Plenty region" + geography_id: "04" + geography_level: region + geography_name: "Bay of Plenty Region" + geography_vintage: regc_2025 + table_record_kind: total + guard_cells: + - column: A + row: 4 + expected_value: 'At 30 June 2023–2025' + label: point-in-time release period + - column: A + row: 29 + expected_value: '2. Boundaries at 1 January 2025.' + label: regional boundary vintage + - column: A + row: 34 + expected_value: P provisional + label: publication status + - value_id: regc_05 + label: "Gisborne region" + ordinal: 4 + row_number: 11 + expected_row_header_column: A + expected_row_header: "Gisborne region" + geography_id: "05" + geography_level: region + geography_name: "Gisborne Region" + geography_vintage: regc_2025 + table_record_kind: total + guard_cells: + - column: A + row: 4 + expected_value: 'At 30 June 2023–2025' + label: point-in-time release period + - column: A + row: 29 + expected_value: '2. Boundaries at 1 January 2025.' + label: regional boundary vintage + - column: A + row: 34 + expected_value: P provisional + label: publication status + - value_id: regc_06 + label: "Hawke's Bay region" + ordinal: 5 + row_number: 12 + expected_row_header_column: A + expected_row_header: "Hawke's Bay region" + geography_id: "06" + geography_level: region + geography_name: "Hawke's Bay Region" + geography_vintage: regc_2025 + table_record_kind: total + guard_cells: + - column: A + row: 4 + expected_value: 'At 30 June 2023–2025' + label: point-in-time release period + - column: A + row: 29 + expected_value: '2. Boundaries at 1 January 2025.' + label: regional boundary vintage + - column: A + row: 34 + expected_value: P provisional + label: publication status + - value_id: regc_07 + label: "Taranaki region" + ordinal: 6 + row_number: 13 + expected_row_header_column: A + expected_row_header: "Taranaki region" + geography_id: "07" + geography_level: region + geography_name: "Taranaki Region" + geography_vintage: regc_2025 + table_record_kind: total + guard_cells: + - column: A + row: 4 + expected_value: 'At 30 June 2023–2025' + label: point-in-time release period + - column: A + row: 29 + expected_value: '2. Boundaries at 1 January 2025.' + label: regional boundary vintage + - column: A + row: 34 + expected_value: P provisional + label: publication status + - value_id: regc_08 + label: "Manawatū-Whanganui region" + ordinal: 7 + row_number: 14 + expected_row_header_column: A + expected_row_header: "Manawatū-Whanganui region" + geography_id: "08" + geography_level: region + geography_name: "Manawatū-Whanganui Region" + geography_vintage: regc_2025 + table_record_kind: total + guard_cells: + - column: A + row: 4 + expected_value: 'At 30 June 2023–2025' + label: point-in-time release period + - column: A + row: 29 + expected_value: '2. Boundaries at 1 January 2025.' + label: regional boundary vintage + - column: A + row: 34 + expected_value: P provisional + label: publication status + - value_id: regc_09 + label: "Wellington region" + ordinal: 8 + row_number: 15 + expected_row_header_column: A + expected_row_header: "Wellington region" + geography_id: "09" + geography_level: region + geography_name: "Wellington Region" + geography_vintage: regc_2025 + table_record_kind: total + guard_cells: + - column: A + row: 4 + expected_value: 'At 30 June 2023–2025' + label: point-in-time release period + - column: A + row: 29 + expected_value: '2. Boundaries at 1 January 2025.' + label: regional boundary vintage + - column: A + row: 34 + expected_value: P provisional + label: publication status + - value_id: regc_16 + label: "Tasman region" + ordinal: 9 + row_number: 16 + expected_row_header_column: A + expected_row_header: "Tasman region" + geography_id: "16" + geography_level: region + geography_name: "Tasman Region" + geography_vintage: regc_2025 + table_record_kind: total + guard_cells: + - column: A + row: 4 + expected_value: 'At 30 June 2023–2025' + label: point-in-time release period + - column: A + row: 29 + expected_value: '2. Boundaries at 1 January 2025.' + label: regional boundary vintage + - column: A + row: 34 + expected_value: P provisional + label: publication status + - value_id: regc_17 + label: "Nelson region" + ordinal: 10 + row_number: 17 + expected_row_header_column: A + expected_row_header: "Nelson region" + geography_id: "17" + geography_level: region + geography_name: "Nelson Region" + geography_vintage: regc_2025 + table_record_kind: total + guard_cells: + - column: A + row: 4 + expected_value: 'At 30 June 2023–2025' + label: point-in-time release period + - column: A + row: 29 + expected_value: '2. Boundaries at 1 January 2025.' + label: regional boundary vintage + - column: A + row: 34 + expected_value: P provisional + label: publication status + - value_id: regc_18 + label: "Marlborough region" + ordinal: 11 + row_number: 18 + expected_row_header_column: A + expected_row_header: "Marlborough region" + geography_id: "18" + geography_level: region + geography_name: "Marlborough Region" + geography_vintage: regc_2025 + table_record_kind: total + guard_cells: + - column: A + row: 4 + expected_value: 'At 30 June 2023–2025' + label: point-in-time release period + - column: A + row: 29 + expected_value: '2. Boundaries at 1 January 2025.' + label: regional boundary vintage + - column: A + row: 34 + expected_value: P provisional + label: publication status + - value_id: regc_12 + label: "West Coast region" + ordinal: 12 + row_number: 19 + expected_row_header_column: A + expected_row_header: "West Coast region" + geography_id: "12" + geography_level: region + geography_name: "West Coast Region" + geography_vintage: regc_2025 + table_record_kind: total + guard_cells: + - column: A + row: 4 + expected_value: 'At 30 June 2023–2025' + label: point-in-time release period + - column: A + row: 29 + expected_value: '2. Boundaries at 1 January 2025.' + label: regional boundary vintage + - column: A + row: 34 + expected_value: P provisional + label: publication status + - value_id: regc_13 + label: "Canterbury region" + ordinal: 13 + row_number: 20 + expected_row_header_column: A + expected_row_header: "Canterbury region" + geography_id: "13" + geography_level: region + geography_name: "Canterbury Region" + geography_vintage: regc_2025 + table_record_kind: total + guard_cells: + - column: A + row: 4 + expected_value: 'At 30 June 2023–2025' + label: point-in-time release period + - column: A + row: 29 + expected_value: '2. Boundaries at 1 January 2025.' + label: regional boundary vintage + - column: A + row: 34 + expected_value: P provisional + label: publication status + - value_id: regc_14 + label: "Otago region" + ordinal: 14 + row_number: 21 + expected_row_header_column: A + expected_row_header: "Otago region" + geography_id: "14" + geography_level: region + geography_name: "Otago Region" + geography_vintage: regc_2025 + table_record_kind: total + guard_cells: + - column: A + row: 4 + expected_value: 'At 30 June 2023–2025' + label: point-in-time release period + - column: A + row: 29 + expected_value: '2. Boundaries at 1 January 2025.' + label: regional boundary vintage + - column: A + row: 34 + expected_value: P provisional + label: publication status + - value_id: regc_15 + label: "Southland region" + ordinal: 15 + row_number: 22 + expected_row_header_column: A + expected_row_header: "Southland region" + geography_id: "15" + geography_level: region + geography_name: "Southland Region" + geography_vintage: regc_2025 + table_record_kind: total + guard_cells: + - column: A + row: 4 + expected_value: 'At 30 June 2023–2025' + label: point-in-time release period + - column: A + row: 29 + expected_value: '2. Boundaries at 1 January 2025.' + label: regional boundary vintage + - column: A + row: 34 + expected_value: P provisional + label: publication status + - value_id: nz + label: "New Zealand" + ordinal: 16 + row_number: 25 + expected_row_header_column: A + expected_row_header: "New Zealand(3)" + geography_id: "NZ" + geography_level: country + geography_name: "New Zealand" + geography_vintage: current + table_record_kind: total + guard_cells: + - column: A + row: 4 + expected_value: 'At 30 June 2023–2025' + label: point-in-time release period + - column: A + row: 29 + expected_value: '2. Boundaries at 1 January 2025.' + label: regional boundary vintage + - column: A + row: 34 + expected_value: P provisional + label: publication status +- <<: *population_set + record_set_id: stats_nz.cy2025.subnational_population.age_0_14 + provenance_class: census + record_set_spec_id: stats_nz.subnational_population.age_0_14.v1 + source_record_id_prefix: stats_nz.cy2025.subnational_population.age_0_14 + sheet_name: Table 3 + shared_filters: + person.age_band: "0_14" + shared_constraints: + - variable: person.age_band + operator: == + value: "0_14" + label: Publisher broad age group + - variable: person.age + operator: '>=' + value: 0 + unit: years + label: Age lower bound + - variable: person.age + operator: < + value: 15 + unit: years + label: Age upper bound (exclusive) + measures: + - <<: *population_measure + column: D + expected_column_header: "0–14" + rows: &broad_age_rows + - value_id: regc_01 + label: "Northland region" + ordinal: 0 + row_number: 10 + expected_row_header_column: A + expected_row_header: "Northland region" + geography_id: "01" + geography_level: region + geography_name: "Northland Region" + geography_vintage: regc_2025 + table_record_kind: total + guard_cells: + - column: A + row: 4 + expected_value: 'At 30 June 2023–2025' + label: point-in-time release period + - column: A + row: 68 + expected_value: '2. Boundaries at 1 January 2025.' + label: regional boundary vintage + - column: A + row: 74 + expected_value: P provisional + label: publication status + - column: C + row: 10 + expected_value: 2025 P + label: historical 2025 reference-date row + - value_id: regc_02 + label: "Auckland region" + ordinal: 1 + row_number: 13 + expected_row_header_column: A + expected_row_header: "Auckland region" + geography_id: "02" + geography_level: region + geography_name: "Auckland" + geography_vintage: regc_2025 + table_record_kind: total + guard_cells: + - column: A + row: 4 + expected_value: 'At 30 June 2023–2025' + label: point-in-time release period + - column: A + row: 68 + expected_value: '2. Boundaries at 1 January 2025.' + label: regional boundary vintage + - column: A + row: 74 + expected_value: P provisional + label: publication status + - column: C + row: 13 + expected_value: 2025 P + label: historical 2025 reference-date row + - value_id: regc_03 + label: "Waikato region" + ordinal: 2 + row_number: 16 + expected_row_header_column: A + expected_row_header: "Waikato region" + geography_id: "03" + geography_level: region + geography_name: "Waikato Region" + geography_vintage: regc_2025 + table_record_kind: total + guard_cells: + - column: A + row: 4 + expected_value: 'At 30 June 2023–2025' + label: point-in-time release period + - column: A + row: 68 + expected_value: '2. Boundaries at 1 January 2025.' + label: regional boundary vintage + - column: A + row: 74 + expected_value: P provisional + label: publication status + - column: C + row: 16 + expected_value: 2025 P + label: historical 2025 reference-date row + - value_id: regc_04 + label: "Bay of Plenty region" + ordinal: 3 + row_number: 19 + expected_row_header_column: A + expected_row_header: "Bay of Plenty region" + geography_id: "04" + geography_level: region + geography_name: "Bay of Plenty Region" + geography_vintage: regc_2025 + table_record_kind: total + guard_cells: + - column: A + row: 4 + expected_value: 'At 30 June 2023–2025' + label: point-in-time release period + - column: A + row: 68 + expected_value: '2. Boundaries at 1 January 2025.' + label: regional boundary vintage + - column: A + row: 74 + expected_value: P provisional + label: publication status + - column: C + row: 19 + expected_value: 2025 P + label: historical 2025 reference-date row + - value_id: regc_05 + label: "Gisborne region" + ordinal: 4 + row_number: 22 + expected_row_header_column: A + expected_row_header: "Gisborne region" + geography_id: "05" + geography_level: region + geography_name: "Gisborne Region" + geography_vintage: regc_2025 + table_record_kind: total + guard_cells: + - column: A + row: 4 + expected_value: 'At 30 June 2023–2025' + label: point-in-time release period + - column: A + row: 68 + expected_value: '2. Boundaries at 1 January 2025.' + label: regional boundary vintage + - column: A + row: 74 + expected_value: P provisional + label: publication status + - column: C + row: 22 + expected_value: 2025 P + label: historical 2025 reference-date row + - value_id: regc_06 + label: "Hawke's Bay region" + ordinal: 5 + row_number: 25 + expected_row_header_column: A + expected_row_header: "Hawke's Bay region" + geography_id: "06" + geography_level: region + geography_name: "Hawke's Bay Region" + geography_vintage: regc_2025 + table_record_kind: total + guard_cells: + - column: A + row: 4 + expected_value: 'At 30 June 2023–2025' + label: point-in-time release period + - column: A + row: 68 + expected_value: '2. Boundaries at 1 January 2025.' + label: regional boundary vintage + - column: A + row: 74 + expected_value: P provisional + label: publication status + - column: C + row: 25 + expected_value: 2025 P + label: historical 2025 reference-date row + - value_id: regc_07 + label: "Taranaki region" + ordinal: 6 + row_number: 28 + expected_row_header_column: A + expected_row_header: "Taranaki region" + geography_id: "07" + geography_level: region + geography_name: "Taranaki Region" + geography_vintage: regc_2025 + table_record_kind: total + guard_cells: + - column: A + row: 4 + expected_value: 'At 30 June 2023–2025' + label: point-in-time release period + - column: A + row: 68 + expected_value: '2. Boundaries at 1 January 2025.' + label: regional boundary vintage + - column: A + row: 74 + expected_value: P provisional + label: publication status + - column: C + row: 28 + expected_value: 2025 P + label: historical 2025 reference-date row + - value_id: regc_08 + label: "Manawatū-Whanganui region" + ordinal: 7 + row_number: 31 + expected_row_header_column: A + expected_row_header: "Manawatū-Whanganui region" + geography_id: "08" + geography_level: region + geography_name: "Manawatū-Whanganui Region" + geography_vintage: regc_2025 + table_record_kind: total + guard_cells: + - column: A + row: 4 + expected_value: 'At 30 June 2023–2025' + label: point-in-time release period + - column: A + row: 68 + expected_value: '2. Boundaries at 1 January 2025.' + label: regional boundary vintage + - column: A + row: 74 + expected_value: P provisional + label: publication status + - column: C + row: 31 + expected_value: 2025 P + label: historical 2025 reference-date row + - value_id: regc_09 + label: "Wellington region" + ordinal: 8 + row_number: 34 + expected_row_header_column: A + expected_row_header: "Wellington region" + geography_id: "09" + geography_level: region + geography_name: "Wellington Region" + geography_vintage: regc_2025 + table_record_kind: total + guard_cells: + - column: A + row: 4 + expected_value: 'At 30 June 2023–2025' + label: point-in-time release period + - column: A + row: 68 + expected_value: '2. Boundaries at 1 January 2025.' + label: regional boundary vintage + - column: A + row: 74 + expected_value: P provisional + label: publication status + - column: C + row: 34 + expected_value: 2025 P + label: historical 2025 reference-date row + - value_id: regc_16 + label: "Tasman region" + ordinal: 9 + row_number: 37 + expected_row_header_column: A + expected_row_header: "Tasman region" + geography_id: "16" + geography_level: region + geography_name: "Tasman Region" + geography_vintage: regc_2025 + table_record_kind: total + guard_cells: + - column: A + row: 4 + expected_value: 'At 30 June 2023–2025' + label: point-in-time release period + - column: A + row: 68 + expected_value: '2. Boundaries at 1 January 2025.' + label: regional boundary vintage + - column: A + row: 74 + expected_value: P provisional + label: publication status + - column: C + row: 37 + expected_value: 2025 P + label: historical 2025 reference-date row + - value_id: regc_17 + label: "Nelson region" + ordinal: 10 + row_number: 40 + expected_row_header_column: A + expected_row_header: "Nelson region" + geography_id: "17" + geography_level: region + geography_name: "Nelson Region" + geography_vintage: regc_2025 + table_record_kind: total + guard_cells: + - column: A + row: 4 + expected_value: 'At 30 June 2023–2025' + label: point-in-time release period + - column: A + row: 68 + expected_value: '2. Boundaries at 1 January 2025.' + label: regional boundary vintage + - column: A + row: 74 + expected_value: P provisional + label: publication status + - column: C + row: 40 + expected_value: 2025 P + label: historical 2025 reference-date row + - value_id: regc_18 + label: "Marlborough region" + ordinal: 11 + row_number: 43 + expected_row_header_column: A + expected_row_header: "Marlborough region" + geography_id: "18" + geography_level: region + geography_name: "Marlborough Region" + geography_vintage: regc_2025 + table_record_kind: total + guard_cells: + - column: A + row: 4 + expected_value: 'At 30 June 2023–2025' + label: point-in-time release period + - column: A + row: 68 + expected_value: '2. Boundaries at 1 January 2025.' + label: regional boundary vintage + - column: A + row: 74 + expected_value: P provisional + label: publication status + - column: C + row: 43 + expected_value: 2025 P + label: historical 2025 reference-date row + - value_id: regc_12 + label: "West Coast region" + ordinal: 12 + row_number: 46 + expected_row_header_column: A + expected_row_header: "West Coast region" + geography_id: "12" + geography_level: region + geography_name: "West Coast Region" + geography_vintage: regc_2025 + table_record_kind: total + guard_cells: + - column: A + row: 4 + expected_value: 'At 30 June 2023–2025' + label: point-in-time release period + - column: A + row: 68 + expected_value: '2. Boundaries at 1 January 2025.' + label: regional boundary vintage + - column: A + row: 74 + expected_value: P provisional + label: publication status + - column: C + row: 46 + expected_value: 2025 P + label: historical 2025 reference-date row + - value_id: regc_13 + label: "Canterbury region" + ordinal: 13 + row_number: 49 + expected_row_header_column: A + expected_row_header: "Canterbury region" + geography_id: "13" + geography_level: region + geography_name: "Canterbury Region" + geography_vintage: regc_2025 + table_record_kind: total + guard_cells: + - column: A + row: 4 + expected_value: 'At 30 June 2023–2025' + label: point-in-time release period + - column: A + row: 68 + expected_value: '2. Boundaries at 1 January 2025.' + label: regional boundary vintage + - column: A + row: 74 + expected_value: P provisional + label: publication status + - column: C + row: 49 + expected_value: 2025 P + label: historical 2025 reference-date row + - value_id: regc_14 + label: "Otago region" + ordinal: 14 + row_number: 52 + expected_row_header_column: A + expected_row_header: "Otago region" + geography_id: "14" + geography_level: region + geography_name: "Otago Region" + geography_vintage: regc_2025 + table_record_kind: total + guard_cells: + - column: A + row: 4 + expected_value: 'At 30 June 2023–2025' + label: point-in-time release period + - column: A + row: 68 + expected_value: '2. Boundaries at 1 January 2025.' + label: regional boundary vintage + - column: A + row: 74 + expected_value: P provisional + label: publication status + - column: C + row: 52 + expected_value: 2025 P + label: historical 2025 reference-date row + - value_id: regc_15 + label: "Southland region" + ordinal: 15 + row_number: 55 + expected_row_header_column: A + expected_row_header: "Southland region" + geography_id: "15" + geography_level: region + geography_name: "Southland Region" + geography_vintage: regc_2025 + table_record_kind: total + guard_cells: + - column: A + row: 4 + expected_value: 'At 30 June 2023–2025' + label: point-in-time release period + - column: A + row: 68 + expected_value: '2. Boundaries at 1 January 2025.' + label: regional boundary vintage + - column: A + row: 74 + expected_value: P provisional + label: publication status + - column: C + row: 55 + expected_value: 2025 P + label: historical 2025 reference-date row + - value_id: nz + label: "New Zealand" + ordinal: 16 + row_number: 64 + expected_row_header_column: A + expected_row_header: "New Zealand(4)" + geography_id: "NZ" + geography_level: country + geography_name: "New Zealand" + geography_vintage: current + table_record_kind: total + guard_cells: + - column: A + row: 4 + expected_value: 'At 30 June 2023–2025' + label: point-in-time release period + - column: A + row: 68 + expected_value: '2. Boundaries at 1 January 2025.' + label: regional boundary vintage + - column: A + row: 74 + expected_value: P provisional + label: publication status + - column: C + row: 64 + expected_value: 2025 P + label: historical 2025 reference-date row +- <<: *population_set + record_set_id: stats_nz.cy2025.subnational_population.age_15_39 + provenance_class: census + record_set_spec_id: stats_nz.subnational_population.age_15_39.v1 + source_record_id_prefix: stats_nz.cy2025.subnational_population.age_15_39 + sheet_name: Table 3 + shared_filters: + person.age_band: "15_39" + shared_constraints: + - variable: person.age_band + operator: == + value: "15_39" + label: Publisher broad age group + - variable: person.age + operator: '>=' + value: 15 + unit: years + label: Age lower bound + - variable: person.age + operator: < + value: 40 + unit: years + label: Age upper bound (exclusive) + measures: + - <<: *population_measure + column: E + expected_column_header: "15–39" + rows: *broad_age_rows +- <<: *population_set + record_set_id: stats_nz.cy2025.subnational_population.age_40_64 + provenance_class: census + record_set_spec_id: stats_nz.subnational_population.age_40_64.v1 + source_record_id_prefix: stats_nz.cy2025.subnational_population.age_40_64 + sheet_name: Table 3 + shared_filters: + person.age_band: "40_64" + shared_constraints: + - variable: person.age_band + operator: == + value: "40_64" + label: Publisher broad age group + - variable: person.age + operator: '>=' + value: 40 + unit: years + label: Age lower bound + - variable: person.age + operator: < + value: 65 + unit: years + label: Age upper bound (exclusive) + measures: + - <<: *population_measure + column: F + expected_column_header: "40–64" + rows: *broad_age_rows +- <<: *population_set + record_set_id: stats_nz.cy2025.subnational_population.age_65_plus + provenance_class: census + record_set_spec_id: stats_nz.subnational_population.age_65_plus.v1 + source_record_id_prefix: stats_nz.cy2025.subnational_population.age_65_plus + sheet_name: Table 3 + shared_filters: + person.age_band: "65_plus" + shared_constraints: + - variable: person.age_band + operator: == + value: "65_plus" + label: Publisher broad age group + - variable: person.age + operator: '>=' + value: 65 + unit: years + label: Age lower bound + measures: + - <<: *population_measure + column: G + expected_column_header: "65+" + rows: *broad_age_rows diff --git a/tests/test_chronicle_bundle.py b/tests/test_chronicle_bundle.py index 6a00ef84..d6ea0e90 100644 --- a/tests/test_chronicle_bundle.py +++ b/tests/test_chronicle_bundle.py @@ -73,16 +73,16 @@ def test_build_bundle_writes_merged_consumer_contract(tmp_path): "aggregate_duplicate_key_count": 0, "entity_count": 12, "error_count": 0, - "fact_count": 171855, - "geography_count": 12536, + "fact_count": 171940, + "geography_count": 12553, "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) == 171940 assert {row["provenance_class"] for row in rows} <= { "administrative", "census", @@ -100,7 +100,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 +114,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"] == 171940 assert coverage["counts"]["by_source"] == { "bea": 445, "bfp_economic_outlook": 5, @@ -156,12 +156,20 @@ def test_build_bundle_writes_merged_consumer_contract(tmp_path): "statbel_fiscal_income": 565, "statbel_fiscal_income_distribution": 14600, "statbel_population_structure": 36, + "stats_nz": 85, "usda_snap": 852, "voa": 3001, "welshgov": 216, } table_counts = coverage["counts"]["by_source_table"] - assert len(table_counts) == 146 + assert len(table_counts) == 147 + assert ( + table_counts[ + "stats_nz:Subnational population estimates: At 30 June 2025 " + "(provisional), Tables 1 and 3" + ] + == 85 + ) assert ( table_counts[ "dwp:Universal Credit childcare element statistics to August 2025, Table 1" @@ -533,7 +541,7 @@ def test_build_bundle_writes_merged_consumer_contract(tmp_path): "calendar_year:2022": 2075, "calendar_year:2023": 6343, "calendar_year:2024": 33936, - "calendar_year:2025": 4571, + "calendar_year:2025": 4656, "calendar_year:2026": 341, "calendar_year:2027": 320, "calendar_year:2028": 320, @@ -689,7 +697,10 @@ 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 coverage["counts"]["by_geography"]["country:NZ"] == 5 + assert coverage["counts"]["by_geography"]["region:01"] == 5 + assert coverage["counts"]["by_geography"]["region:02"] == 5 + assert len(coverage["counts"]["by_geography"]) == 12553 assert coverage["counts"]["by_entity"] == { "benefit_unit": 233, "dwelling": 12733, @@ -699,7 +710,7 @@ def test_build_bundle_writes_merged_consumer_contract(tmp_path): "household": 40724, "institutional_sector": 133, "pension_plan": 2, - "person": 60466, + "person": 60551, "return": 14600, "social_protection_scheme": 36, "tax_unit": 40069, diff --git a/tests/test_chronicle_nz_population.py b/tests/test_chronicle_nz_population.py new file mode 100644 index 00000000..a6a5f5f7 --- /dev/null +++ b/tests/test_chronicle_nz_population.py @@ -0,0 +1,322 @@ +"""Source-only regression gates for the partial 30 June 2025 NZ population package.""" + +from __future__ import annotations + +from collections import Counter +from dataclasses import replace +import hashlib +import html +from io import BytesIO +import json +from pathlib import Path + +import openpyxl +import pytest +import yaml + +from chronicle.bundle import build_bundle, 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.cells import build_source_cell_key, validate_source_cells + +ALIAS = "stats-nz-subnational-population-estimates-2025" +REPO_ROOT = Path(__file__).resolve().parents[1] +DATA_ROOT = REPO_ROOT / "db" / "data" / "stats_nz" +WORKBOOK_SHA256 = "001e8a896cfb50f5ed17836dc815b235e3bcca55ee91c9869a2afaeb054b50a6" +REGC_SHA256 = "e5d53fa6abf742121d123bff970c77658a16e8c9b405b83d1a978cc22920d660" +NATIONAL_PAGE_SHA256 = ( + "b2d2751800857895b1498d87df6f03ac3511ec8c7a9b17cc3150c8ab56533053" +) +# Order and rows are from Tables 1 and 3 of the pinned publisher workbook. +REGIONS = ( + ("01", 7, 10), + ("02", 8, 13), + ("03", 9, 16), + ("04", 10, 19), + ("05", 11, 22), + ("06", 12, 25), + ("07", 13, 28), + ("08", 14, 31), + ("09", 15, 34), + ("16", 16, 37), + ("17", 17, 40), + ("18", 18, 43), + ("12", 19, 46), + ("13", 20, 49), + ("14", 21, 52), + ("15", 22, 55), + ("NZ", 25, 64), +) +# These are the source's four broad bands, not five-year-age target bands. +AGE_BANDS = { + "0_14": ("D", 0, 15), + "15_39": ("E", 15, 40), + "40_64": ("F", 40, 65), + "65_plus": ("G", 65, None), +} + + +def _artifact(package_name): + directory = DATA_ROOT / package_name + manifest = yaml.safe_load((directory / "manifest.yaml").read_text()) + entry = manifest["files"][2025] + return (directory / entry["filename"]).read_bytes(), entry + + +@pytest.fixture(scope="module") +def population(): + package = load_source_package(ALIAS) + cells = package.build_source_cells(2025) + facts = package.build_facts(2025, cells=cells) + return package, cells, facts + + +@pytest.fixture(scope="module") +def workbook(): + content, _ = _artifact("subnational_population_estimates_2025") + book = openpyxl.load_workbook(BytesIO(content), data_only=True) + yield book + book.close() + + +@pytest.mark.parametrize( + ("package_name", "expected_sha", "expected_size"), + [ + ("subnational_population_estimates_2025", WORKBOOK_SHA256, 97990), + ("regional_council_2025_codes", REGC_SHA256, 3381), + ("national_population_estimates_2025", NATIONAL_PAGE_SHA256, 61286), + ], +) +def test_publisher_artifact_bytes_and_country_storage_are_pinned( + package_name, expected_sha, expected_size +): + content, entry = _artifact(package_name) + assert hashlib.sha256(content).hexdigest() == entry["sha256"] == expected_sha + assert len(content) == entry["size_bytes"] == expected_size + assert entry["storage"]["r2"]["uri"].startswith( + f"r2://ledger-raw/raw/nz/stats_nz/{package_name}/2025/{expected_sha}/" + ) + + +def test_partial_package_counts_and_whole_sheet_preservation(population): + package, cells, facts = population + report = validate_source_package(ALIAS, year=2025) + assert report.valid + assert not report.warnings + assert report.counts["record_set_count"] == 5 + assert report.counts["source_record_count"] == len(facts) == 85 + assert "partial" in package.label.lower() + assert package.artifact.sheets == ("Table 1", "Table 3") + # Full used ranges, including unused years and source footnotes: 35x9 + 75x26. + assert len(cells) == 2265 + assert Counter(cell.sheet_name for cell in cells) == { + "Table 1": 315, + "Table 3": 1950, + } + assert validate_source_cells(cells).valid + assert validate_facts(facts).valid + + +def test_every_fact_equals_one_published_cell_with_no_scaling(population, workbook): + package, cells, facts = population + actual = { + (fact.geography.id, fact.filters.get("person.age_band", "all")): fact + for fact in facts + } + cell_keys = {build_source_cell_key(cell) for cell in cells} + assert len(actual) == 85 + for geography_id, total_row, broad_age_row in REGIONS: + assert ( + actual[(geography_id, "all")].value + == workbook["Table 1"][f"D{total_row}"].value + ) + for age_band, (column, _lower, _upper) in AGE_BANDS.items(): + assert ( + actual[(geography_id, age_band)].value + == workbook["Table 3"][f"{column}{broad_age_row}"].value + ) + for fact, spec in zip(facts, package.build_source_record_specs(2025), strict=True): + assert spec.value_scale == 1 + assert spec.divisor_selector is None + assert spec.round_to is None + assert spec.selector.end_address is None + assert fact.source_record_id == spec.source_record_id + assert fact.source_cell_keys + assert set(fact.source_cell_keys) <= cell_keys + assert fact.source.source_sha256 == WORKBOOK_SHA256 + assert fact.aggregation.method == "sum" + assert fact.measure.unit == "count" + assert type(fact.value) is int + + +def test_regc_codes_and_names_match_official_2025_classification(population): + _package, _cells, facts = population + content, _ = _artifact("regional_council_2025_codes") + classification = json.loads(content) + assert not classification.get("exceededTransferLimit", False) + codes = { + row["attributes"]["REGC2025_V1_00"]: row["attributes"]["REGC2025_V1_00_NAME"] + for row in classification["features"] + } + assert len(codes) == 17 # Sixteen regions plus publisher code 99 (outside region). + regional_facts = [fact for fact in facts if fact.geography.level == "region"] + assert {fact.geography.id for fact in regional_facts} == codes.keys() - {"99"} + assert len(regional_facts) == 80 + assert all(fact.geography.vintage == "regc_2025" for fact in regional_facts) + assert all( + fact.geography.name == codes[fact.geography.id] for fact in regional_facts + ) + assert ( + codes["02"] == "Auckland" + ) # Workbook calls the same region "Auckland region". + + +def test_national_total_is_published_not_reconciled_from_regions(population, workbook): + _package, _cells, facts = population + totals = {fact.geography.id: fact for fact in facts if not fact.filters} + # Table 1 footnote 3 includes areas outside a region (for example Chatham). + assert totals["NZ"].value == workbook["Table 1"]["D25"].value == 5_324_700 + assert totals["NZ"].value != sum( + fact.value for code, fact in totals.items() if code != "NZ" + ) + assert "99" not in totals # Do not construct an outside-region residual. + assert totals["NZ"].geography.level == "country" + assert totals["NZ"].source_record_id.endswith(".all_ages.nz.population") + + +def test_age_universes_are_only_published_broad_bands_and_all_sexes(population): + _package, _cells, facts = population + assert {fact.filters.get("person.age_band", "all") for fact in facts} == { + "all", + *AGE_BANDS, + } + for fact in facts: + assert "person.sex" not in fact.filters + assert not any( + constraint.variable == "person.sex" for constraint in fact.constraints + ) + assert fact.entity.name == "person" + assert fact.entity.role == "resident_population" + if not fact.filters: + assert not fact.constraints + continue + _column, lower, upper = AGE_BANDS[fact.filters["person.age_band"]] + age_constraints = { + (item.operator, item.value, item.unit) + for item in fact.constraints + if item.variable == "person.age" + } + expected = {(">=", lower, "years")} + if upper is not None: + expected.add(("<", upper, "years")) + assert age_constraints == expected + + +@pytest.mark.parametrize("requested_year", [2023, 2025, 2026]) +def test_requested_build_year_cannot_uprate_or_relabel_pinned_vintage( + population, requested_year +): + package, cells, original = population + facts = package.build_facts(requested_year, cells=cells) + assert facts == original + assert package.artifact.artifact_year == 2025 + for fact in facts: + assert fact.period.type == "calendar_year" + assert fact.period.value == 2025 + assert fact.period_coverage.start_date == "2025-06-30" + assert fact.period_coverage.end_date == "2025-06-30" + assert fact.period_coverage.basis == "calendar" + assert ( + fact.period_coverage.source_period_label == "At 30 June 2025 (provisional)" + ) + assert fact.source.vintage == "stats_nz_subnational_population_2025_10_29" + assert fact.assertion == "observation" + assert fact.provenance_class == "census" + + +@pytest.mark.parametrize( + ("sheet", "address", "replacement"), + [ + ("Table 1", "D6", "2026 P"), + ("Table 1", "A7", "Auckland region"), + ("Table 1", "A4", "Year ended 30 June 2023–2025"), + ("Table 1", "A29", "2. Boundaries at 1 January 2026."), + ("Table 1", "A34", "F final"), + ("Table 3", "C13", "2024 P"), + ("Table 3", "A13", "Northland region"), + ("Table 3", "E6", "15–64"), + ("Table 3", "G6", "60+"), + ("Table 3", "A68", "2. Boundaries at 1 January 2026."), + ("Table 3", "A74", "F final"), + ], +) +def test_source_semantic_drift_fails_closed(population, sheet, address, replacement): + package, cells, _facts = population + mutated = [ + replace(cell, raw_value=replacement, display_value=replacement) + if (cell.sheet_name, cell.address) == (sheet, address) + else cell + for cell in cells + ] + with pytest.raises(ValueError, match="expected"): + package.build_facts(2025, cells=mutated) + + +def test_consumer_rows_preserve_source_only_scope_and_lineage(population): + _package, _cells, facts = population + rows = consumer_fact_rows(facts) + assert validate_consumer_fact_contract(facts).valid + assert len({row["aggregate_fact_key"] for row in rows}) == 85 + assert len({row["semantic_fact_key"] for row in rows}) == 85 + for row in rows: + assert row["concept_alignment"]["relation"] == "source_label" + notes = row["concept_alignment"]["evidence_notes"] + assert "not five-year or single-year ages" in notes + assert "there is no sex-specific split" in notes + assert "outside regions" in notes + assert row["source"]["raw_r2_key"].startswith("raw/nz/stats_nz/") + assert row["lineage"]["source_cell_keys"] + assert row["lineage"]["source_record_id"] + assert ( + not {"target", "solver", "calibration", "uprating_factor", "weight"} + & row.keys() + ) + + +def test_national_landing_page_is_evidence_not_an_age_table_package(): + content, _ = _artifact("national_population_estimates_2025") + page = html.unescape(content.decode()).replace("\\/", "/") + assert "single-year of age" in page + assert "Infoshare" in page + assert "2025-08-19 10:45:00" in page + assert "DocumentBlock" not in page + assert "stats-nz-national-population-estimates-2025" not in SOURCE_PACKAGE_ALIASES + assert not ( + REPO_ROOT + / "packages/stats_nz/national_population_estimates_2025/source_package.yaml" + ).exists() + + +def test_explicit_single_package_bundle_passes_all_source_gates(tmp_path): + report = build_bundle(tmp_path / "bundle", sources=[ALIAS], year=2025) + assert report.valid + rows = [ + json.loads(line) + for line in (tmp_path / "bundle/consumer_facts.jsonl").read_text().splitlines() + ] + coverage = build_bundle_coverage(rows) + assert coverage["fact_count"] == 85 + assert coverage["counts"]["by_source"] == {"stats_nz": 85} + assert coverage["counts"]["by_period"] == {"calendar_year:2025": 85} + assert coverage["counts"]["by_geography"]["country:NZ"] == 5 + assert len(coverage["counts"]["by_geography"]) == 17 + assert not coverage["duplicates"]["aggregate_fact_keys"] + assert not coverage["duplicates"]["semantic_fact_keys"]