Skip to contents

Download CNES Health Facility Registry Data

Source: R/cnes.R
cnes_data.Rd

Downloads and returns health facility registry data from DATASUS FTP. Each row represents one health facility record (for the ST type). Data is organized monthly – one .dbc file per type, state (UF), and month.

Usage

cnes_data(
  year,
  type = "ST",
  month = NULL,
  vars = NULL,
  uf = NULL,
  parse = TRUE,
  col_types = NULL,
  cache = TRUE,
  cache_dir = NULL,
  lazy = FALSE,
  backend = c("arrow", "duckdb")
)

Arguments

year

Integer. Year(s) of the data. Required.

type

Character. File type to download. Default: "ST" (establishments). See cnes_info() for all 13 types.

month

Integer. Month(s) of the data (1-12). If NULL (default), downloads all 12 months. Example: 1 (January), 1:6 (first semester).

vars

Character vector. Variables to keep. If NULL (default), returns all available variables. Use cnes_variables() to see available variables.

uf

Character. Two-letter state abbreviation(s) to download. If NULL (default), downloads all 27 states. Example: "SP", c("SP", "RJ").

parse

Logical. If TRUE (default), converts columns to appropriate types (integer, double, Date) based on the variable metadata. Use cnes_variables() to see the target type for each variable. Set to FALSE for backward-compatible all-character output.

col_types

Named list. Override the default type for specific columns. Names are column names, values are type strings: "character", "integer", "double", "date_dmy", "date_ymd", "date_ym", "date". Example: list(COMPETEN = "character") to keep COMPETEN as character.

cache

Logical. If TRUE (default), caches downloaded data for faster future access.

cache_dir

Character. Directory for caching. Default: tools::R_user_dir("healthbR", "cache").

lazy

Logical. If TRUE, returns a lazy query object instead of a tibble. Requires the arrow package. The lazy object supports dplyr verbs (filter, select, mutate, etc.) which are pushed down to the query engine before collecting into memory. Call dplyr::collect() to materialize the result. Default: FALSE.

backend

Character. Backend for lazy evaluation: "arrow" (default) or "duckdb". Only used when lazy = TRUE. DuckDB backend requires the duckdb package.

Value

A tibble with health facility data. Includes columns year, month, and uf_source to identify the source when multiple years/months/states are combined.

Details

Data is downloaded from DATASUS FTP as .dbc files (one per type/state/month). The .dbc format is decompressed internally using vendored C code from the blast library. No external dependencies are required.

CNES data is monthly, so downloading an entire year for all states requires 324 files (27 UFs x 12 months) per type. Use uf and month to limit downloads.

The CNES has 13 file types. The default "ST" (establishments) is the most commonly used. Use cnes_info() to see all types.

See also

cnes_info() for file type descriptions, censo_populacao() for population denominators.

Other cnes: cnes_cache_status(), cnes_clear_cache(), cnes_dictionary(), cnes_info(), cnes_variables(), cnes_years()

Examples

if (FALSE) { # interactive()
# all establishments in Acre, January 2023
ac_jan <- cnes_data(year = 2023, month = 1, uf = "AC")

# only key variables
cnes_data(year = 2023, month = 1, uf = "AC",
          vars = c("CNES", "CODUFMUN", "TP_UNID", "VINC_SUS"))

# hospital beds
leitos <- cnes_data(year = 2023, month = 1, uf = "AC", type = "LT")

# health professionals
prof <- cnes_data(year = 2023, month = 1, uf = "AC", type = "PF")
}