Convert census tract aggregates to an H3 grid using CNEFE points
Source:R/tracts_to_h3.R
tracts_to_h3.Rdtracts_to_h3() performs a dasymetric interpolation with the following steps:
census tract totals are allocated to CNEFE dwelling points inside each tract;
allocated values are aggregated to an H3 grid at a user-defined resolution.
The function uses DuckDB with the spatial and H3 extensions for the heavy work.
Usage
tracts_to_h3(
code_muni,
year = 2022,
h3_resolution = 9,
vars = c("pop_ph", "pop_ch"),
cache = TRUE,
verbose = TRUE
)Arguments
- code_muni
Integer. Seven-digit IBGE municipality code.
- year
Integer. The CNEFE data year. Currently only 2022 is supported. Defaults to 2022.
- h3_resolution
Integer. H3 resolution (0 to 15). Defaults to 9.
- vars
Character vector. Names of tract-level variables to interpolate. Supported variables:
pop_ph: population in private households (Domicílios particulares).pop_ch: population in collective households (Domicílios coletivos).male: total male population.female: total female population.age_0_4,age_5_9,age_10_14,age_15_19,age_20_24,age_25_29,age_30_39,age_40_49,age_50_59,age_60_69,age_70m: population by age group.race_branca,race_preta,race_amarela,race_parda,race_indigena: population by race/color (cor ou raça).n_resp: number of household heads (Pessoas responsáveis por domicílios).avg_inc_resp: average income of the household heads.
For a reference table mapping these variable names to the official IBGE census tract codes and descriptions, see tracts_variables_ref.
Allocation rules:
pop_phis allocated only to private dwellings.pop_chis allocated only to collective dwellings.n_respis allocated only to private dwellings (same rule aspop_ph).Demographic variables (
male,female,age_*,race_*) are allocated to private dwellings when the tract has any; if the tract has zero private dwellings but has collective dwellings, they are allocated to collective.avg_inc_respis assigned (not split) to each private dwelling point; tracts with no private dwellings receive no allocation.
- cache
Logical. Whether to use the existing package cache for assets and CNEFE zips.
- verbose
Logical. Whether to print step messages and timing.
Examples
# \donttest{
# Interpolate population to H3 hexagons
hex_pop <- tracts_to_h3(
code_muni = 2929057,
vars = c("pop_ph", "pop_ch")
)
#> ℹ Processing code 2929057
#> ℹ Step 1/6: connecting to DuckDB and loading extensions...
#> ✔ Spatial extension loaded
#> ℹ Step 1/6: connecting to DuckDB and loading extensions...
#> ✔ Step 1/6 (DuckDB ready) [280ms]
#>
#> ℹ Step 2/6: preparing census tracts in DuckDB...
#> ℹ Downloading sc_29.parquet from GitHub release
#> ℹ Downloading "sc_29.parquet"...
#> ℹ Downloading sc_29.parquet from GitHub release
#>
|
| | 0%
|
| | 1%
|
|= | 1%
|
|= | 2%
|
|== | 2%
|
|== | 3%
|
|== | 4%
|
|=== | 4%
|
|=== | 5%
|
|==== | 5%
|
|==== | 6%
|
|===== | 7%
|
|====== | 9%
|
|======= | 10%
|
|======= | 11%
|
|======== | 11%
|
|========= | 13%
|
|========== | 14%
|
|=========== | 15%
|
|============ | 17%
|
|============ | 18%
|
|============= | 19%
|
|============== | 19%
|
|============== | 20%
|
|=============== | 21%
|
|=============== | 22%
|
|================ | 22%
|
|================ | 23%
|
|================= | 24%
|
|================= | 25%
|
|================== | 25%
|
|================== | 26%
|
|=================== | 26%
|
|=================== | 27%
|
|==================== | 29%
|
|===================== | 29%
|
|===================== | 30%
|
|===================== | 31%
|
|====================== | 31%
|
|====================== | 32%
|
|======================= | 32%
|
|======================== | 34%
|
|========================= | 36%
|
|========================== | 36%
|
|========================== | 37%
|
|=========================== | 38%
|
|============================ | 40%
|
|============================ | 41%
|
|============================= | 42%
|
|============================== | 42%
|
|============================== | 43%
|
|=============================== | 44%
|
|================================ | 46%
|
|================================= | 47%
|
|================================= | 48%
|
|================================== | 48%
|
|================================== | 49%
|
|=================================== | 51%
|
|==================================== | 51%
|
|==================================== | 52%
|
|===================================== | 53%
|
|===================================== | 54%
|
|====================================== | 54%
|
|======================================= | 55%
|
|======================================== | 57%
|
|========================================= | 58%
|
|========================================== | 60%
|
|=========================================== | 61%
|
|============================================ | 62%
|
|============================================ | 63%
|
|============================================ | 64%
|
|============================================= | 64%
|
|============================================= | 65%
|
|============================================== | 65%
|
|============================================== | 66%
|
|=============================================== | 67%
|
|=============================================== | 68%
|
|================================================ | 68%
|
|================================================= | 70%
|
|================================================= | 71%
|
|================================================== | 71%
|
|================================================== | 72%
|
|=================================================== | 72%
|
|==================================================== | 74%
|
|==================================================== | 75%
|
|===================================================== | 75%
|
|====================================================== | 77%
|
|======================================================= | 78%
|
|======================================================== | 79%
|
|========================================================= | 81%
|
|========================================================== | 83%
|
|=========================================================== | 85%
|
|============================================================ | 86%
|
|============================================================= | 87%
|
|============================================================== | 89%
|
|=============================================================== | 90%
|
|================================================================ | 92%
|
|================================================================== | 94%
|
|=================================================================== | 96%
|
|==================================================================== | 98%
|
|===================================================================== | 98%
|
|======================================================================| 100%
#> ✔ Downloading sc_29.parquet from GitHub release [1.6s]
#>
#> ℹ Step 2/6: preparing census tracts in DuckDB...
#> ✔ Step 2/6 (Tracts ready) [1.8s]
#>
#> ℹ Step 3/6: preparing CNEFE points in DuckDB...
#> ℹ Using cached file: /home/runner/.cache/R/cnefetools/2929057_SAO_FELIX_DO_CORIBE.zip
#> ℹ Step 3/6: preparing CNEFE points in DuckDB...
#> ✔ Step 3/6 (CNEFE points ready) [235ms]
#>
#> ℹ Step 4/6: spatial join (points to tracts) and allocation prep...
#> ✔ Step 4/6 (Join and allocation) [87ms]
#>
#> ℹ Step 5/6: aggregating allocated values to H3 cells...
#> ✔ Step 5/6 (Hex aggregation) [15ms]
#>
#> ℹ Step 6/6: building H3 grid and joining results...
#> ✔ Step 6/6 (sf output) [5.2s]
#>
#>
#> ── Dasymetric interpolation diagnostics ──
#>
#> ── Stage 1: Tracts → CNEFE points
#> ! Unallocated total for population from private households (pop_ph): 0 of 15183
#> (0.00%)
#> ! Unallocated total for population from collective households (pop_ch): 0 of 0
#> (0.00%)
#> ! Unmatched CNEFE points (no tract): 4 of 6949 points (0.06% of total points)
#> ! Tracts with NA totals: pop_ch in 1 of 40 tracts (2.50% of total tracts)
#>
#> ── Stage 2: CNEFE points → H3 hexagons
#> ℹ CNEFE points mapped to H3 cells: 6945 of 6945 allocated points (100.00%)
# }