Geography and epidemiological analysis"
In datasus: An Interface to Brazilian Public Health Data

knitr::opts_chunk$set(echo = TRUE, collapse = TRUE, comment = "#>")
library(datasus)

Overview

The package includes an offline IBGE territorial reference and dependency-free helpers for common epidemiological calculations. These tools can be used with data retrieved through datasus or with any data frame that uses compatible identifiers.

Territorial reference

Inspect the current hierarchy at region, state or municipality level:

datasus_territorios("regiao")
head(datasus_territorios("uf"))
head(datasus_territorios("municipio", uf = "MS"))

DATASUS commonly uses six-digit municipality codes, while IBGE publishes a seven-digit identifier. Normalize either form explicitly:

normalizar_codigo_ibge(
  c("500270", "500370"),
  nivel = "municipio",
  formato = "ibge"
)

validar_codigo_ibge() reports whether identifiers belong to the current reference:

validar_codigo_ibge(c("5002704", "5003702", "9999999"))

Add geography to observations

Use adicionar_territorio() to attach municipality, state and region information without changing row order:

events <- data.frame(
  codigo = c("500270", "500370"),
  ano = c(2025L, 2025L),
  casos = c(18L, 7L)
)

events <- adicionar_territorio(events, codigo = "codigo")
events

The bundled hierarchy describes current territorial units. Historical observations are not automatically redistributed after boundary changes.

Make missing combinations explicit

Absent municipality-period combinations can be created before calculating rates or plotting a panel:

panel <- completar_territorios(
  events,
  codigo = "codigo",
  periodo = "ano",
  uf = "MS",
  periodos = 2023:2025,
  preencher = list(casos = 0)
)

Choose the territorial universe and periods explicitly. An absent record is not always equivalent to a true zero.

Join population denominators

juntar_populacao() requires unique population keys, preserves observation order and reports unmatched rows by default:

cases <- data.frame(
  codigo_municipio = c("5002704", "5003702"),
  ano = c(2025L, 2025L),
  casos = c(18L, 7L)
)
population <- data.frame(
  codigo_municipio = c("5002704", "5003702"),
  ano = c(2025L, 2025L),
  habitantes = c(925000, 95000)
)

analysis <- juntar_populacao(
  cases,
  population,
  por = c(
    codigo_municipio = "codigo_municipio",
    ano = "ano"
  ),
  coluna_populacao = "habitantes",
  nome = "habitantes"
)
analysis

Rates, proportions and case fatality

Vector helpers are useful for direct calculations:

calcular_taxa(
  eventos = c(10, 25),
  populacao = c(10000, 20000)
)

intervalo_taxa(
  eventos = 10,
  populacao = 10000,
  confianca = 0.95
)

The grouped indicator engine aggregates counts before calculating the estimate. This is preferable to averaging rates calculated for individual rows:

taxa_incidencia(
  analysis,
  casos = "casos",
  populacao = "habitantes",
  grupo = "ano",
  confianca = 0.95
)

outcomes <- data.frame(
  ano = c(2024L, 2024L, 2025L, 2025L),
  casos = c(50, 30, 45, 35),
  obitos = c(2, 1, 1, 2)
)
letalidade(
  outcomes,
  obitos = "obitos",
  casos = "casos",
  grupo = "ano",
  confianca = 0.95
)

proporcao() and taxa_mortalidade() use the same grouped interface.

Epidemiological calendar and moving averages

semana_epidemiologica(
  as.Date(c("2025-01-01", "2025-12-31", "2026-01-01"))
)

head(calendario_epidemiologico(2026))

media_movel(
  c(2, 5, 3, 8, 7, 6, 9),
  janela = 3,
  parcial = TRUE
)

Direct age standardization

The package supplies WHO 2000--2025, Segi and Scandinavian standard populations:

head(populacao_padrao("oms"))

Pass age-specific counts and populations to padronizar_idade():

standardized <- padronizar_idade(
  eventos = deaths_by_age$obitos,
  populacao = deaths_by_age$habitantes,
  idade = deaths_by_age$faixa_etaria,
  populacao_padrao = populacao_padrao("oms"),
  grupo = deaths_by_age$ano,
  confianca = 0.95
)