juntar_populacao: Join validated population denominators

In datasus: An Interface to Brazilian Public Health Data

Join validated population denominators

Description

Performs a many-to-one join from observations to a population table, preserving observation order and rejecting ambiguous denominator keys. This is designed to connect outputs from [populacao_residente()] to event tables before calculating population-based indicators.

Usage

juntar_populacao(
  dados,
  populacao,
  por,
  coluna_populacao = "populacao",
  nome = "populacao",
  ausente = c("erro", "na"),
  sobrescrever = FALSE
)

Arguments

dados	Observation data frame.
populacao	Population data frame.
por	Character vector of join columns. An unnamed vector uses the same names in both tables. In a named vector, names refer to columns in 'dados' and values to columns in 'populacao'.
coluna_populacao	Name of the numeric denominator column in 'populacao'.
nome	Name assigned to the joined denominator column.
ausente	How to handle observations without a denominator: '"erro"' stops and '"na"' keeps them with a missing value.
sobrescrever	Whether an existing 'nome' column in 'dados' may be replaced.

Value

'dados' with one validated population denominator column appended.

Examples

eventos <- data.frame(codigo = c("A", "B"), ano = 2024, casos = c(2, 4))
denominadores <- data.frame(
  municipio = c("A", "B"), ano = 2024, habitantes = c(1000, 2000)
)
juntar_populacao(
  eventos, denominadores,
  por = c(codigo = "municipio", ano = "ano"),
  coluna_populacao = "habitantes"
)

datasus documentation built on Oct. 7, 2026, 1:07 a.m.