cnefe_counts: Count CNEFE address species on a spatial grid

In cnefetools: Access and Analysis of Brazilian CNEFE Address Data

Count CNEFE address species on a spatial grid

Description

cnefe_counts() reads CNEFE records for a given municipality, assigns each address point to spatial units (either H3 hexagonal cells or user-provided polygons), and returns per-unit counts of COD_ESPECIE as addr_type1 to addr_type8.

Usage

cnefe_counts(
  code_muni,
  year = 2022,
  polygon_type = lifecycle::deprecated(),
  polygon = NULL,
  crs_output = NULL,
  h3_resolution = 9,
  verbose = TRUE,
  cache = TRUE,
  cache_dir = NULL,
  backend = c("duckdb", "r")
)

Arguments

code_muni	Integer. Seven-digit IBGE municipality code.
year	Integer. The CNEFE data year. Currently only 2022 is supported. Defaults to 2022.
polygon_type	The aggregation mode is now inferred from polygon: leave it NULL for an H3 grid, or pass an sf::sf object for user polygons. Passing polygon_type still works and warns.
polygon	An sf::sf object with polygon geometries. Supplying it switches the output from an H3 grid to these polygons. A warning is issued reporting the percentage of CNEFE points covered by the polygon area. If no CNEFE points fall within the polygon, an error is raised.
crs_output	The CRS for the output object. Only used when polygon is supplied. 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().
h3_resolution	Integer. H3 grid resolution (default: 9). Only used for the H3 grid, so it is ignored when polygon is supplied.
verbose	Logical; if TRUE, prints messages and timing information.
cache	Logical. If TRUE (default), the downloaded data is stored as a gzipped CSV in the user cache directory and reused in future calls. If FALSE, a temporary file is used and deleted after the call.
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.
backend	Character. "duckdb" (default) uses DuckDB with the H3 extension, and the spatial extension as well when polygon is supplied. "r" uses h3jsr and sf in R instead, and needs no DuckDB extension. "r" exists for environments where DuckDB extensions cannot be installed, such as some restricted computing clusters. It is not the lighter option: it materialises the filtered address table in R memory, so its footprint grows with the municipality, while DuckDB aggregates in a streaming fashion and stays nearly flat. On São Paulo (5.7 million addresses) the measured peak is about 9 GB under "r" against 0.7 GB under "duckdb", alongside being roughly 13 times slower. If the constraint is memory rather than installability, keep the DuckDB backend and cap it with the cnefetools.duckdb_config option instead. See ?cnefetools for that option, and the benchmark article at https://pedreirajr.github.io/cnefetools/articles/bench_duckdb.html for the measurements.

Details

The counts in the columns addr_type1 to addr_type8 correspond to:

• addr_type1: Private household (Domicílio particular)

• addr_type2: Collective household (Domicílio coletivo)

• addr_type3: Agricultural establishment (Estabelecimento agropecuário)

• addr_type4: Educational establishment (Estabelecimento de ensino)

• addr_type5: Health establishment (Estabelecimento de saúde)

• addr_type6: Establishment for other purposes (Estabelecimento de outras finalidades)

• addr_type7: Building under construction or renovation (Edificação em construção ou reforma)

• addr_type8: Religious establishment (Estabelecimento religioso)

All eight types are reported. In particular, addr_type7 is retained here, whereas compute_lumi() excludes it when computing land-use mix indices.

Value

An sf::sf object containing:

• id_hex (when polygon is NULL): H3 cell identifier

• Original columns from polygon (when polygon is supplied)

• addr_type1 ... addr_type8: counts per address type

• geometry: polygon geometry

When polygon is supplied, the output CRS matches the original polygon CRS (or crs_output if specified).

See Also

compute_lumi() for land-use mix indices on the same spatial units.

Examples

# Count addresses per H3 hexagon (resolution 9)
hex_counts <- cnefe_counts(code_muni = 2929057, cache = FALSE)

# Count addresses per user-provided polygon (neighborhoods of Lauro de Freitas-BA)
# Using geobr to download neighborhood boundaries
library(geobr)
nei_ldf <- subset(
  read_neighborhood(year = 2022),
  code_muni == 2919207
)
nei_counts <- cnefe_counts(
  code_muni = 2919207,
  polygon = nei_ldf,
  cache = FALSE
)

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