Package {microdatasus}

Title: Download and Process 'DataSUS' Files
Version: 3.0.0
URL: https://github.com/rfsaldanha/microdatasus, https://rfsaldanha.github.io/microdatasus/
BugReports: https://github.com/rfsaldanha/microdatasus/issues
Description: Downloads and processes health microdata from Brazilian Unified Health System ('DataSUS') information systems. It handles the compressed 'DBC' format internally and provides functions to organize variables and add labels to categorical fields from mortality, live births, hospital admissions, outpatient care, health facilities, and notifiable diseases data. For details, see Saldanha et al. (2019) <doi:10.1590/0102-311x00032419>.
License: MIT + file LICENSE
Copyright: See file inst/COPYRIGHTS.
Encoding: UTF-8
LazyData: true
LazyDataCompression: xz
Imports: checkmate, cli, curl, data.table, dplyr (≥ 1.2.0), foreign, magrittr, rlang, stringi, tibble, utils, zip
Suggests: lubridate, testthat (≥ 3.0.0)
Config/testthat/edition: 3
Depends: R (≥ 4.1.0)
Config/Needs/website: rmarkdown
Config/roxygen2/version: 8.0.0
NeedsCompilation: yes
Packaged: 2026-07-29 13:17:02 UTC; raphaelsaldanha
Author: Raphael Saldanha ORCID iD [aut, cre], Sidney da Silva Pereira Bissoli [ctb, cph] (DBC decompression code), Mark Adler [ctb, cph] (blast decompressor)
Maintainer: Raphael Saldanha <raphael.saldanha@fiocruz.br>
Repository: CRAN
Date/Publication: 2026-07-29 13:40:02 UTC

microdatasus: Download and prepare DataSUS microdata

Description

Provides a reproducible workflow for DataSUS microdata: fetch_datasus() discovers, downloads, and combines published DBC files; read_dbc() reads a local DBC file; and the ⁠process_*()⁠ functions convert system-specific fields into analysis-ready values and labels.

Details

Start with fetch_datasus() and then use the processor corresponding to the selected system, such as process_sim(), process_sinasc(), process_sih(), process_sia(), process_cnes(), or one of the ⁠process_sinan_*()⁠ functions. fetch_cadger() and fetch_sigtab() retrieve current auxiliary tables used by CNES and SIA processing.

For concepts, coverage, data flows, and caveats of each Brazilian health information system, see Saldanha (2026), Sistemas de Informação em Saúde no Brasil.

Author(s)

Maintainer: Raphael Saldanha raphael.saldanha@fiocruz.br (ORCID)

Authors:

Other contributors:

See Also

Useful links:

Pipe operator

Description

See magrittr::%>% for details.

Usage

lhs %>% rhs

Arguments

lhs

A value or the magrittr placeholder.

rhs

A function call using the magrittr semantics.

Value

The result of calling rhs(lhs).

CNES-PF sample

Description

CNES-PF sample with the first 100 rows from AC 2016-6 file.

Usage

cnes_pf_sample

Format

An object of class data.frame with 100 rows and 39 columns.

Details

The variable CPF_PROF was removed due non-ASCII characters.

CNES-ST sample

Description

CNES-ST sample with the first 100 rows from AC 2016-6 file.

Usage

cnes_st_sample

Format

An object of class data.frame with 100 rows and 201 columns.

Equipe table

Description

Equipe table, based on INE_EQUIPE_BR.dbf file from SIM TabWIN definitions file.

Usage

equipe

Format

A data frame with 2428 rows and 2 variables:

COD

Code

equipe_ref

Label

Download the current CADGER table

Description

Downloads and reads the current CNES establishment-name table distributed by DataSUS. process_cnes() can use this table to add establishment names.

Usage

fetch_cadger(timeout = 240)

Arguments

timeout

A positive numeric scalar. Download and connection timeout, in seconds.

Value

A data frame with character columns CNES (establishment code) and FANTASIA (trade name).

Network access

This function downloads the current TAB_CNES.zip archive from DataSUS. Transfer progress is displayed by default. The temporary archive and extracted files are removed before the function returns or aborts.

References

Saldanha, R. F. (2026). CNES – Cadastro Nacional de Estabelecimentos de Saúde.

See Also

process_cnes(), fetch_datasus()

Download DataSUS microdata

Description

Downloads published DBC files from DataSUS, reads them with read_dbc(), and combines the records in deterministic period, state, and file-part order.

Usage

fetch_datasus(
  year_start,
  month_start = NULL,
  year_end,
  month_end = NULL,
  uf = "all",
  information_system,
  vars = NULL,
  stop_on_error = FALSE,
  timeout = 240,
  track_source = FALSE,
  quiet = FALSE
)

Arguments

year_start, year_end

Numeric scalars giving the first and last requested years, inclusive.

month_start, month_end

Numeric scalars giving the first and last requested months, inclusive. Months are required for SIH, SIA, and CNES systems and ignored, with a warning, for annual systems.

uf

A Brazilian state abbreviation, a character vector of abbreviations, or "all". "all" cannot be combined with individual states. A warning alert is displayed when this argument is ignored for systems published only as national files.

information_system

A single system identifier listed in Supported systems.

vars

NULL, or a character vector of column names to retain. Selection is applied to each file before the files are combined.

stop_on_error

Logical scalar. If TRUE, abort after any listing, download, or read failure. If FALSE, warn and return the files that could be read successfully.

timeout

A positive numeric scalar giving the connection and transfer timeout, in seconds, for each network attempt.

track_source

Logical scalar. If TRUE, append a source column with the original DBC file name. This column is retained even when vars is supplied. The function aborts if the downloaded data already contain a column named source.

quiet

Logical scalar. If FALSE (the default), display the transfer progress reported by curl::curl_download() and announce each file before downloading it. If TRUE, suppress status messages, per-file announcements, and progress meters. Warnings and errors are not suppressed.

Details

The function first lists the relevant DataSUS directories and downloads only files present in those listings. When more than one publication represents the same system, period, state, and file part, definitive/current data take precedence over preliminary data, and current data take precedence over historical copies.

Downloads are sequential. Unless quiet = TRUE, transfer progress is displayed by curl::curl_download(). Transient network failures are retried up to two times; missing, empty, invalid DBC, and incompatible-schema files are not retried. Partial files and other temporary files are removed before the function returns or aborts.

Years and state abbreviations refer to DataSUS processing periods and places of processing, which may differ from dates or places of occurrence and residence contained in the records.

Value

A tibble containing all successfully read records, or NULL if no requested file could be read. No diagnostic attributes are added.

Supported systems

Network access

An Internet connection and FTP access to DataSUS are required. DataSUS may restrict FTP access from some countries.

References

Saldanha, R. F. (2026). Sistemas de Informação em Saúde no Brasil, especially the chapters on SIM, SINASC, SIH, SIA, SINAN, and CNES.

See Also

read_dbc() for local DBC files; process_sim(), process_sinasc(), process_sih(), process_sia(), process_cnes(), and the ⁠process_sinan_*()⁠ functions for system-specific recoding.

Examples


sim <- fetch_datasus(
  year_start = 2014,
  year_end = 2014,
  uf = "AC",
  information_system = "SIM-DO",
  vars = c("CODMUNRES", "DTOBITO", "CAUSABAS")
)

sih <- fetch_datasus(
  year_start = 2014,
  month_start = 1,
  year_end = 2014,
  month_end = 2,
  uf = c("AC", "RR"),
  information_system = "SIH-RD"
)

Download the current SIGTAB table

Description

Downloads and reads the current SIA procedure table distributed by DataSUS. process_sia() can use this table to add procedure descriptions.

Usage

fetch_sigtab(timeout = 240)

Arguments

timeout

A positive numeric scalar. Download and connection timeout, in seconds.

Value

A data frame with character columns COD (procedure code) and nome_proced (procedure name).

Network access

This function downloads the current TAB_SIA.zip archive from DataSUS. Transfer progress is displayed by default. The temporary archive and extracted files are removed before the function returns or aborts.

References

Saldanha, R. F. (2026). SIA – Sistema de Informações Ambulatoriais do SUS.

See Also

process_sia(), fetch_datasus()

paisnet table

Description

paisnet table, based on PAISNET.DBF file from CNES TabWIN definitions file.

Usage

paisnet

Format

A data frame with 266 rows and 3 variables:

ID_PAIS

Country code 1

COPAISINF

Contry code 2

NM_PAIS

Label

Prepare CNES microdata

Description

Recodes supported CNES fields into descriptive values and normalizes escaped Unicode text. Establishment ("CNES-ST") and professional ("CNES-PF") records have different layouts and are processed accordingly.

Usage

process_cnes(
  data,
  information_system = c("CNES-ST", "CNES-PF"),
  nomes = FALSE,
  municipality_data = TRUE
)

Arguments

data

A data frame returned by fetch_datasus() or another data frame with a compatible CNES layout.

information_system

A single character string: "CNES-ST" for establishments or "CNES-PF" for professionals.

nomes

Logical scalar. For "CNES-ST" data, if TRUE, download the current CADGER table with fetch_cadger() and add establishment trade names. This requires network access. It has no effect for "CNES-PF".

municipality_data

Logical scalar. If TRUE, add municipality names and available territorial attributes for supported municipality-code columns.

Details

Columns not explicitly recoded are retained, but Unicode normalization is applied to every column and consequently the returned tibble contains character columns. Lookup joins can add establishment, occupation, and municipality information.

Value

A tibble with character columns. Supported codes are replaced with descriptions, and requested lookup fields are added where applicable.

References

Saldanha, R. F. (2026). CNES – Cadastro Nacional de Estabelecimentos de Saúde.

See Also

fetch_datasus(), fetch_cadger()

Examples

process_cnes(cnes_st_sample, information_system = "CNES-ST")
process_cnes(cnes_pf_sample, information_system = "CNES-PF")

Prepare SIA outpatient-production microdata

Description

Recodes supported fields from SIA individual outpatient-production records ("SIA-PA") into descriptive values and normalizes escaped Unicode text. Lookup joins can add procedure, occupation, team, and municipality descriptions.

Usage

process_sia(
  data,
  information_system = "SIA-PA",
  nome_proced = TRUE,
  nome_ocupacao = TRUE,
  nome_equipe = TRUE,
  municipality_data = TRUE
)

Arguments

data

A data frame returned by fetch_datasus() with information_system = "SIA-PA", or a compatible layout.

information_system

A single character string. Currently only "SIA-PA" is supported.

nome_proced

Logical scalar. If TRUE, download the current SIGTAB table with fetch_sigtab() and join procedure names. This requires network access.

nome_ocupacao

Logical scalar. If TRUE, join occupation descriptions for supported occupation-code columns.

nome_equipe

Logical scalar retained for API compatibility. Team descriptions are currently joined whenever PA_INE is present, regardless of this value.

municipality_data

Logical scalar. If TRUE, add municipality names and available territorial attributes for supported municipality-code columns.

Details

Columns not explicitly recoded are retained, but Unicode normalization is applied to every column and consequently the returned tibble contains character columns. Other SIA layouts downloadable with fetch_datasus() are not currently supported by this processing function.

Value

A tibble with character columns. Supported codes are replaced with descriptions, and requested lookup fields are added where applicable.

References

Saldanha, R. F. (2026). SIA – Sistema de Informações Ambulatoriais do SUS.

See Also

fetch_datasus(), fetch_sigtab()

Examples

process_sia(sia_pa_sample, nome_proced = FALSE)

Prepare SIH hospital-admission microdata

Description

Recodes supported fields from reduced hospital-admission records ("SIH-RD") into descriptive values and normalizes escaped Unicode text.

Usage

process_sih(data, information_system = "SIH-RD", municipality_data = TRUE)

Arguments

data

A data frame returned by fetch_datasus() with information_system = "SIH-RD", or a compatible layout.

information_system

A single character string. Currently only "SIH-RD" is supported.

municipality_data

Logical scalar. If TRUE, add municipality names and available territorial attributes for supported municipality-code columns.

Details

Columns not explicitly recoded are retained, but Unicode normalization is applied to every column and consequently the returned tibble contains character columns. Other SIH layouts downloadable with fetch_datasus() are not currently supported by this processing function.

Value

A tibble with character columns. Supported codes are replaced with descriptions, and municipality fields are added when requested and available.

References

Saldanha, R. F. (2026). SIH – Sistema de Informações Hospitalares do SUS.

See Also

fetch_datasus()

Examples

process_sih(sih_rd_sample)

Prepare SIM mortality microdata

Description

Recodes supported SIM mortality fields into descriptive values and normalizes escaped Unicode text. Codes without a documented conversion are retained.

Usage

process_sim(data, municipality_data = TRUE)

Arguments

data

A data frame returned by fetch_datasus() for a SIM mortality system, or another data frame with a compatible layout.

municipality_data

Logical scalar. If TRUE, add municipality names and available territorial attributes for supported municipality-code columns.

Details

Columns not explicitly recoded are retained, but Unicode normalization is applied to every column and consequently the returned tibble contains character columns.

Value

A tibble with character columns. Supported codes are replaced with descriptions, and municipality fields are added when requested and available.

References

Saldanha, R. F. (2026). SIM – Sistema de Informação sobre Mortalidade.

See Also

fetch_datasus()

Examples

process_sim(sim_do_sample)

Prepare SINAN Chagas disease microdata

Description

Recodes supported fields from SINAN Chagas disease notifications into descriptive values and normalizes escaped Unicode text. Columns not explicitly recoded are retained, but the returned tibble contains character columns.

Usage

process_sinan_chagas(data, municipality_data = TRUE)

Arguments

data

A data frame returned by fetch_datasus() with information_system = "SINAN-CHAGAS", or a compatible layout.

municipality_data

Logical scalar retained for API compatibility. It is not currently used by this processing function.

Value

A tibble with character columns. Supported codes are replaced with descriptions.

References

Saldanha, R. F. (2026). SINAN – Sistema de Informação de Agravos de Notificação.

See Also

fetch_datasus()

Examples

process_sinan_chagas(sinan_chagas_sample)

Prepare SINAN chikungunya microdata

Description

Recodes supported fields from SINAN chikungunya notifications into descriptive values and normalizes escaped Unicode text. Columns not explicitly recoded are retained, but the returned tibble contains character columns.

Usage

process_sinan_chikungunya(data, municipality_data = TRUE)

Arguments

data

A data frame returned by fetch_datasus() with information_system = "SINAN-CHIKUNGUNYA", or a compatible layout.

municipality_data

Logical scalar. If TRUE, add municipality names and available territorial attributes for supported municipality-code columns.

Value

A tibble with character columns. Supported codes are replaced with descriptions, and municipality fields are added when requested and available.

References

Saldanha, R. F. (2026). SINAN – Sistema de Informação de Agravos de Notificação.

See Also

fetch_datasus()

Examples

process_sinan_chikungunya(sinan_chikungunya_sample)

Prepare SINAN dengue microdata

Description

Recodes supported fields from SINAN dengue notifications into descriptive values and normalizes escaped Unicode text. Columns not explicitly recoded are retained, but the returned tibble contains character columns.

Usage

process_sinan_dengue(data, municipality_data = TRUE)

Arguments

data

A data frame returned by fetch_datasus() with information_system = "SINAN-DENGUE", or a compatible layout.

municipality_data

Logical scalar. If TRUE, add municipality names and available territorial attributes for supported municipality-code columns.

Value

A tibble with character columns. Supported codes are replaced with descriptions, and municipality fields are added when requested and available.

References

Saldanha, R. F. (2026). SINAN – Sistema de Informação de Agravos de Notificação.

See Also

fetch_datasus()

Examples

process_sinan_dengue(sinan_dengue_sample)

Prepare SINAN tegumentary leishmaniasis microdata

Description

Recodes supported fields from SINAN tegumentary leishmaniasis notifications into descriptive values and normalizes escaped Unicode text. Columns not explicitly recoded are retained, but the returned tibble contains character columns.

Usage

process_sinan_leishmaniose_tegumentar(data, municipality_data = TRUE)

Arguments

data

A data frame returned by fetch_datasus() with information_system = "SINAN-LEISHMANIOSE-TEGUMENTAR", or a compatible layout.

municipality_data

Logical scalar retained for API compatibility. It is not currently used by this processing function.

Value

A tibble with character columns. Supported codes are replaced with descriptions.

References

Saldanha, R. F. (2026). SINAN – Sistema de Informação de Agravos de Notificação.

See Also

fetch_datasus()

Examples

process_sinan_leishmaniose_tegumentar(sinan_leishmaniose_tegumentar_sample)

Prepare SINAN visceral leishmaniasis microdata

Description

Recodes supported fields from SINAN visceral leishmaniasis notifications into descriptive values and normalizes escaped Unicode text. Columns not explicitly recoded are retained, but the returned tibble contains character columns.

Usage

process_sinan_leishmaniose_visceral(data, municipality_data = TRUE)

Arguments

data

A data frame returned by fetch_datasus() with information_system = "SINAN-LEISHMANIOSE-VISCERAL", or a compatible layout.

municipality_data

Logical scalar retained for API compatibility. It is not currently used by this processing function.

Value

A tibble with character columns. Supported codes are replaced with descriptions.

References

Saldanha, R. F. (2026). SINAN – Sistema de Informação de Agravos de Notificação.

See Also

fetch_datasus()

Examples

process_sinan_leishmaniose_visceral(sinan_leishmaniose_visceral_sample)

Prepare SINAN malaria microdata

Description

Recodes supported fields from SINAN malaria notifications into descriptive values and normalizes escaped Unicode text. Columns not explicitly recoded are retained, but the returned tibble contains character columns.

Usage

process_sinan_malaria(data, municipality_data = TRUE)

Arguments

data

A data frame returned by fetch_datasus() with information_system = "SINAN-MALARIA", or a compatible layout.

municipality_data

Logical scalar retained for API compatibility. It is not currently used by this processing function.

Value

A tibble with character columns. Supported codes are replaced with descriptions.

References

Saldanha, R. F. (2026). SINAN – Sistema de Informação de Agravos de Notificação.

See Also

fetch_datasus()

Examples

process_sinan_malaria(sinan_malaria_sample)

Prepare SINAN Zika virus disease microdata

Description

Recodes supported fields from SINAN Zika virus disease notifications into descriptive values and normalizes escaped Unicode text. Columns not explicitly recoded are retained, but the returned tibble contains character columns.

Usage

process_sinan_zika(data, municipality_data = TRUE)

Arguments

data

A data frame returned by fetch_datasus() with information_system = "SINAN-ZIKA", or a compatible layout.

municipality_data

Logical scalar retained for API compatibility. It is not currently used by this processing function.

Value

A tibble with character columns. Supported codes are replaced with descriptions.

References

Saldanha, R. F. (2026). SINAN – Sistema de Informação de Agravos de Notificação.

See Also

fetch_datasus()

Examples

process_sinan_zika(sinan_zika_sample)

Prepare SINASC live-birth microdata

Description

Recodes supported SINASC live-birth fields into descriptive values and normalizes escaped Unicode text. Codes without a documented conversion are retained.

Usage

process_sinasc(data, municipality_data = TRUE)

Arguments

data

A data frame returned by fetch_datasus() with information_system = "SINASC", or a compatible layout.

municipality_data

Logical scalar. If TRUE, add municipality names and available territorial attributes for supported municipality-code columns.

Details

Columns not explicitly recoded are retained, but Unicode normalization is applied to every column and consequently the returned tibble contains character columns.

Value

A tibble with character columns. Supported codes are replaced with descriptions, and municipality fields are added when requested and available.

References

Saldanha, R. F. (2026). SINASC – Sistema de Informação sobre Nascidos Vivos.

See Also

fetch_datasus()

Examples

process_sinasc(sinasc_sample)

Read a DBC file

Description

Decompresses a DataSUS DBC file to a temporary DBF file and reads it into a tibble. Use this function for a DBC file already available locally; use fetch_datasus() to discover and download files from DataSUS.

Usage

read_dbc(file, as_character = TRUE)

Arguments

file

A single character string with the path to a readable, non-empty DBC file.

as_character

If TRUE (the default), converts every column to character. If FALSE, preserves the types inferred from the DBF metadata.

Details

Decompression is performed through the package's bundled DBC implementation. The intermediate DBF file is created in the R temporary directory and removed before the function returns or aborts. The implementation was adapted from the healthbR package.

Invalid input files, decompression failures, and DBF reading failures abort with errors in the microdatasus_dbc_error family.

Value

A tibble with one column per DBF field. By default, all columns are character vectors; with as_character = FALSE, DBF-inferred types are retained.

References

Saldanha, R. F. (2026). Sistemas de Informação em Saúde no Brasil.

See Also

fetch_datasus()

SIA-PA sample

Description

SIA-PA sample with the first 100 rows from AC 2016-6 file.

Usage

sia_pa_sample

Format

An object of class data.frame with 100 rows and 60 columns.

Procediments table

Description

Procediments table, based on TB_SIGTAP.dbf file from SIA TabWIN definitions file.

Usage

sigtab

Format

A data frame with 5325 rows and 2 variables:

COD

Code

nome_proced

Procediment name

SIH-RD sample

Description

SIH-RD sample with the first 100 rows from AC 2016-6 file.

Usage

sih_rd_sample

Format

An object of class data.frame with 100 rows and 113 columns.

SIM-DO sample

Description

SIM-DO sample with the first 100 rows from AC 2016 file.

Usage

sim_do_sample

Format

An object of class data.frame with 100 rows and 88 columns.

SINAN Chagas sample

Description

SINAN Chagas sample with the first 100 rows from the 2023 file.

Usage

sinan_chagas_sample

Format

An object of class data.frame with 100 rows and 108 columns.

SINAN Chikungunya sample

Description

SINAN Chikungunya sample with the first 100 rows from the 2022 file.

Usage

sinan_chikungunya_sample

Format

An object of class data.frame with 100 rows and 122 columns.

SINAN Dengue sample

Description

SINAN Dengue sample with the first 100 rows from the 2010 file.

Usage

sinan_dengue_sample

Format

An object of class data.frame with 100 rows and 66 columns.

SINAN Leishmaniose Tegumentar sample

Description

SINAN Leishmaniose Tegumentar sample with the first 100 rows from the 2023 file.

Usage

sinan_leishmaniose_tegumentar_sample

Format

An object of class data.frame with 100 rows and 74 columns.

SINAN Leishmaniose Visceral sample

Description

SINAN Leishmaniose Visceral sample with the first 100 rows from the 2023 file.

Usage

sinan_leishmaniose_visceral_sample

Format

An object of class data.frame with 100 rows and 76 columns.

SINAN Malaria sample

Description

SINAN Malaria sample with the first 100 rows from the 2016 file.

Usage

sinan_malaria_sample

Format

An object of class data.frame with 100 rows and 50 columns.

SINAN Zika sample

Description

SINAN Zika sample with the first 100 rows from the 2016 file.

Usage

sinan_zika_sample

Format

An object of class data.frame with 100 rows and 38 columns.

SINASC sample

Description

SINASC sample with the first 100 rows from AC 2016 file.

Usage

sinasc_sample

Format

An object of class data.frame with 100 rows and 61 columns.

CBO table

Description

CBO table, based on CBO2002.CNV file from SIM TabWIN definitions file.

Usage

tabCBO

Format

A data frame with 2428 rows and 2 variables:

cod

Code

nome

Label

Municipalities table

Description

Municipalities table

Usage

tabMun

Format

A data frame with 5659 rows and 2 variables:

munResCod

Municipality IBGE code with 6 numbers

munResStatus

Status

munResTipo

Type

munResNome

Name

munResUf

UF (state)

munResLat

Latitude

munResLon

Longitude

munResAlt

Altitude

munResArea

Area

Naturalidade table

Description

Naturalidade table, based on NATUR.CNV file from SIM TabWIN definitions file.

Usage

tabNaturalidade

Format

A data frame with 292 rows and 2 variables:

cod

Code

nome

Label

Ocupations table

Description

Ocupations table, based on OCUPACAO.CNV file from SIM TabWIN definitions file.

Usage

tabOcupacao

Format

A data frame with 350 rows and 2 variables:

cod

Code

nome

Label