---
title: "Geography and epidemiological analysis"
author: "Renato Prado Siqueira"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Geography and epidemiological analysis}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
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:

```{r territories}
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:

```{r normalize-codes}
normalizar_codigo_ibge(
  c("500270", "500370"),
  nivel = "municipio",
  formato = "ibge"
)
```

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

```{r validate-codes}
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:

```{r add-geography}
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:

```{r complete-geography, eval=FALSE}
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:

```{r population-join}
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:

```{r vector-rates}
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:

```{r grouped-rates}
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

```{r epi-calendar}
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:

```{r standard-populations}
head(populacao_padrao("oms"))
```

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

```{r age-standardization, eval=FALSE}
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
)
```