tracts_to_h3: Convert census tract aggregates to an H3 grid using CNEFE...

In cnefetools: Access and Analysis of Brazilian CNEFE Address Data

Convert census tract aggregates to an H3 grid using CNEFE points

Description

tracts_to_h3() performs a dasymetric interpolation with the following steps:

1. census tract totals are allocated to CNEFE dwelling points inside each tract;

2. 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.

Unlike cnefe_counts() and compute_lumi(), this function does not expose a backend argument and relies on DuckDB exclusively. The dominant cost here is a spatial overlay between the full CNEFE point set of the municipality and the census tract polygons, which is a different workload from the tabular aggregation those other functions perform. Running that overlay in R would take prohibitively long in medium and large municipalities, so a pure-R fallback would offer users a path that does not finish rather than a slower one.

Usage

tracts_to_h3(
  code_muni,
  year = 2022,
  h3_resolution = 9,
  vars = c("pop_ph", "pop_ch"),
  cache = TRUE,
  cache_dir = NULL,
  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_ph is allocated only to private dwellings. pop_ch is allocated only to collective dwellings. n_resp is allocated only to private dwellings (same rule as pop_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_resp is assigned (not split) to each private dwelling point; tracts with no private dwellings receive no allocation.
cache	Logical. Whether to use the package cache for the census tract assets and the CNEFE files.
cache_dir	Character. Directory to use for cached downloads. If NULL (default), the CNEFETOOLS_CACHE_DIR environment variable is used when it is set, otherwise tools::R_user_dir() with which = "cache". Use this to point large downloads at a secondary drive or a shared volume.
verbose	Logical. Whether to print step messages and timing.

Value

An sf object (CRS 4326) with an H3 grid and the requested interpolated variables.

Examples

# Interpolate population to H3 hexagons
hex_pop <- tracts_to_h3(
  code_muni = 2929057,
  vars = c("pop_ph", "pop_ch"),
  cache = FALSE
)

cnefetools documentation built on Oct. 2, 2026, 1:08 a.m.