tracts_to_polygon: Convert census tract aggregates to user-provided polygons...

In cnefetools: Access and Analysis of Brazilian CNEFE Address Data

Convert census tract aggregates to user-provided polygons using CNEFE points

Description

tracts_to_polygon() 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 user-provided polygons (neighborhoods, administrative divisions, custom areas, etc.).

The function uses DuckDB with spatial 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_polygon(
  code_muni,
  polygon,
  year = 2022,
  vars = c("pop_ph", "pop_ch"),
  crs_output = NULL,
  cache = TRUE,
  cache_dir = NULL,
  verbose = TRUE
)

Arguments

code_muni	Integer. Seven-digit IBGE municipality code.
polygon	An sf::sf object with polygon geometries (POLYGON or MULTIPOLYGON). The function will automatically align CRS and issue a warning reporting the percentage of the polygon area that falls outside the municipality.
year	Integer. The CNEFE data year. Currently only 2022 is supported. Defaults to 2022.
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.
crs_output	The CRS for the output object. Default is NULL, which uses the original CRS of the polygon argument. Can be an EPSG code (e.g., 4326, 31983) or any CRS object accepted by sf::st_transform().
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 with the user-provided polygons and the requested interpolated variables. The output CRS matches the original polygon CRS (or crs_output if specified).

Examples

# Interpolate population to user-provided polygons (neighborhoods of Lauro de Freitas-BA)
# Using geobr to download neighborhood boundaries
library(geobr)
nei_ldf <- subset(
  read_neighborhood(year = 2022),
  code_muni == 2919207
)
poly_pop <- tracts_to_polygon(
  code_muni = 2919207,
  polygon = nei_ldf,
  vars = c("pop_ph", "pop_ch"),
  cache = FALSE
)

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