Skip to contents

Construindo Pipelines Analíticos Reprodutíveis com o Climasus4r

Source: vignettes/tutorial_estudos_casos.Rmd
tutorial_estudos_casos.Rmd

Introdução

Sobre este Tutorial — Este tutorial apresenta quatro estudos de caso práticos que demonstram como utilizar o pacote climasus4r para construir pipelines analíticos reprodutíveis (RAPs) em estudos epidemiológicos. Cada estudo de caso representa um pipeline completo e executável, cobrindo todas as etapas da análise: desde a obtenção e preparação dos dados, passando pela padronização e agregação temporal, até a geração de bases prontas para análise estatística.

Enquanto o tutorial introdutório apresenta as funções do pacote de forma individual, este guia mostra como combiná-las em fluxos de trabalho integrados, semelhantes aos utilizados em pesquisas reais em saúde pública e epidemiologia ambiental.

🎯 Neste tutorial, você aprenderá

👶

Mortalidade Infantil

Análise de doenças respiratórias pediátricas com filtros demográficos precisos

Pipeline 1

🦟

Sazonalidade da Dengue

Uso do SINAN para investigar padrões sazonais de doenças infecciosas

Pipeline 2

❤️

Cardiovascular em Idosos

Foco em grupo de risco com agregação por semana epidemiológica

Pipeline 3

🌡️

Ondas de Calor

Agregação em pentads para estudos de eventos climáticos extremos

Pipeline 4

📋 1. Operador Pipe: Conceito e Uso

Antes de apresentarmos os pipelines, é fundamental entender o operador pipe (%>% ou |>), que é a espinha dorsal de todo o código que você verá neste tutorial. O pipe é uma forma elegante de encadear operações em R, tornando o código mais legível, intuitivo e fácil de manter.

1.1. O Que É o Pipe?

O operador pipe (%>%), do pacote magrittr, permite passar o resultado de uma expressão como argumento para a próxima expressão. Em português, podemos ler o pipe como “então” ou “e então”.

❌ Sem pipe (forma tradicional):

# Forma tradicional - difícil de ler
resultado <- aggregate(
  filter(
    standardize(
      clean_encoding(dados)
    ),
    idade > 18
  ),
  by = "mes"
)

✅ Com pipe (forma legível):

# Forma com pipe - fácil de seguir
resultado <- dados %>%
  clean_encoding() %>%
  standardize() %>%
  filter(idade > 18) %>%
  aggregate(by = "mes")

Dica de Leitura: Leia o código com pipe como uma frase: “Pegue os dados, então limpe a codificação, então padronize, então filtre por idade, então agregue por mês.”

1.2. Por Que Usar Pipes?

Benefícios Principais: 1. Legibilidade: O código segue o fluxo natural dos dados, de cima para baixo 2. Menor risco de erros: Evita objetos intermediários desnecessários 3. Facilidade de manutenção: É simples adicionar, remover ou reordenar etapas 4. Depuração facilitada: Você pode verificar o resultado de cada etapa facilmente

🏗️ 2. Pipelines Analíticos Reprodutíveis (RAPs)

Agora que você entende o operador pipe, vamos discutir o conceito fundamental por trás de toda a estrutura do climasus4r: os Pipelines Analíticos Reprodutíveis (em inglês, Reproducible Analytical Pipelines ou RAPs).

2.1. O Que São RAPs?

Um Pipeline Analítico Reprodutível é um conjunto de processos automatizados que transformam dados brutos em informações utilizáveis, de forma que o processo completo possa ser repetido identicamente por qualquer pessoa, a qualquer momento, com os mesmos resultados.

Definição: Um RAP é como uma “receita” documentada e automatizada que transforma dados crus em análises finais, onde cada passo é registrado, testável e reprodutível.

2.2. Por Que RAPs São Importantes?

Problemas que os RAPs Resolvem: 1. João baixa os dados do DATASUS manualmente 2. Maria abre no Excel e faz algumas limpezas 3. Carlos recebe o Excel, adiciona algumas fórmulas 4. Ana recebe o arquivo de Carlos e gera um gráfico 5. Resultado: 4 versões diferentes, impossível reproduzir

Os RAPs Garantem: - Reprodutibilidade: Resultados consistentes a qualquer momento - Transparência: Qualquer pessoa pode verificar cada passo - Eficiência: Uma vez criado, pode ser reutilizado - Colaboração: Múltiplos pesquisadores no mesmo código - Versionamento: Controle de mudanças ao longo do tempo

2.3. O Fluxo RAP do climasus4r

Etapa RAP Função climasus4r O que faz
1. Extração sus_data_import() Baixa dados do DATASUS
2. Transformação sus_data_clean_encoding() Limpa caracteres
3. Transformação sus_data_standardize() Padroniza colunas
4. Enriquecimento sus_create_variables() Cria novas variáveis
5. Filtragem sus_data_filter_cid() Filtra por doença
6. Filtragem sus_data_filter_demographics() Filtra por perfil
7. Análise sus_data_aggregate() Agrega por tempo
8. Exportação sus_data_export() Salva com metadados

🔬 3. Pipeline 1: Análise de Doenças Respiratórias Pediátricas

Objetivo: Investigar a mortalidade por doenças respiratórias em crianças menores de 2 anos nos três estados mais populosos do Sudeste (SP, RJ, MG), entre 2022 e 2023, e analisar a tendência mensal por faixa etária pediátrica.

3.1. Código do Pipeline 

# Carregar pacotes
library(climasus4r)
library(dplyr)

# --- Pipeline Completo ---
df_resp_ped <- sus_data_import(
  uf = c("SP", "RJ", "MG"),
  year = 2022:2023,
  system = "SIM-DO",
  parallel = TRUE,  # Acelerar download
  lang = "pt"
) %>%
  sus_data_clean_encoding(lang = "pt") %>%
  sus_data_standardize(lang = "pt") %>%
  sus_data_filter_cid(disease_group = "respiratory", lang = "pt") %>%
  sus_create_variables(
    create_age_groups = TRUE,
    age_breaks = c(0, 1, 5, Inf), # <1, 1-4, 5+
    age_labels = c("< 1 ano", "1-4 anos", "5+ anos"),
    lang = "pt"
  ) %>%
  sus_data_filter_demographics(
    age_range = c(0, 5), # Apenas crianças < 5 anos
    lang = "pt"
  ) %>%
  sus_data_aggregate(
    time_unit = "month",
    group_by = "age_group", # Agrupar por faixa etária
    lang = "pt"
  )

# Salvar os resultados
sus_data_export(
  df_resp_ped,
  file_path = "respiratorias_pediatricas_sudeste_2022_2023.csv",
  format = "csv",
  include_metadata = TRUE,
  lang = "pt"
)

head(df_resp_ped)

3.2. Explicação Passo a Passo

  1. sus_data_import: Baixamos dados de mortalidade de SP, RJ e MG para 2 anos com paralelismo
  2. sus_data_clean_encoding e sus_data_standardize: Limpeza e padronização
  3. sus_data_filter_cid: Filtro para doenças respiratórias
  4. sus_create_variables: Criação de faixas etárias pediátricas personalizadas
  5. sus_data_filter_demographics: Filtro para crianças < 5 anos
  6. sus_data_aggregate: Agregação mensal por faixa etária

🦟 4. Pipeline 2: Análise de Sazonalidade da Dengue

Objetivo: Analisar o padrão sazonal dos casos de dengue no estado do Amazonas entre 2015 e 2020, agregando os dados por estação do ano para identificar picos de incidência.

4.1. Código do Pipeline 

# Carregar pacotes
library(climasus4r)
library(dplyr)

# --- Pipeline Completo ---
df_dengue <- sus_data_import(
  uf = "AM",
  year = 2015:2020,
  system = "SINAN-DENGUE",
  parallel = TRUE,
  lang = "pt"
) %>%
  sus_data_clean_encoding(lang = "pt") %>%
  sus_data_standardize(lang = "pt") %>%
  sus_create_variables(
    create_calendar_vars = TRUE, # Essencial para criar "estacao"
    lang = "pt"
  ) %>%
  sus_data_aggregate(
    time_unit = "season",  # Agregação por estação do ano
    lang = "pt"
  )

# Salvar os resultados
sus_data_export(
  df_dengue,
  file_path = "dengue_sazonal_amazonas_2015_2020.csv",
  format = "csv",
  include_metadata = TRUE,
  lang = "pt"
)

head(df_dengue)

4.2. Explicação Passo a Passo

  1. sus_data_import: Baixamos dados de casos de dengue para o Amazonas
  2. sus_create_variables: create_calendar_vars = TRUE cria a coluna estacao
  3. sus_data_aggregate: Agregação direta por time_unit = "season"

❤️ 5. Pipeline 3: Análise de Mortalidade Cardiovascular em Idosos

Objetivo: Avaliar a mortalidade por doenças cardiovasculares em idosos (65+ anos) no estado de São Paulo, de 2020 a 2023, agregando os óbitos por semana epidemiológica e faixa etária de idosos.

5.1. Código do Pipeline 

# Carregar pacotes
library(climasus4r)
library(dplyr)

# --- Pipeline Completo ---
df_cardio_idosos <- sus_data_import(
  uf = "SP",
  year = 2020:2023,
  system = "SIM-DO",
  lang = "pt"
) %>%
  sus_data_clean_encoding(lang = "pt") %>%
  sus_data_standardize(lang = "pt") %>%
  sus_data_filter_cid(disease_group = "cardiovascular", lang = "pt") %>%
  sus_create_variables(
    create_age_groups = TRUE,
    age_breaks = c(0, 65, 75, 85, Inf),
    age_labels = c("< 65", "65-74", "75-84", "85+"),
    lang = "pt"
  ) %>%
  sus_data_filter_demographics(
    age_range = c(65, Inf),  # Apenas idosos
    lang = "pt"
  ) %>%
  sus_data_aggregate(
    time_unit = "week",
    group_by = "age_group",
    lang = "pt"
  )

# Salvar os resultados em formato otimizado
sus_data_export(
  df_cardio_idosos,
  file_path = "cardio_idosos_sp_2020_2023.parquet",
  format = "parquet",
  include_metadata = TRUE,
  lang = "pt"
)

head(df_cardio_idosos)

5.2. Explicação Passo a Passo

  1. Importação e filtros: Foco em óbitos cardiovasculares em idosos
  2. sus_data_aggregate: Agregação por semana epidemiológica e faixa etária
  3. Exportação: Formato .parquet para eficiência em grandes volumes

🌡️ 6. Pipeline 4: Análise de Ondas de Calor

Objetivo: Preparar dados de mortalidade por causas relacionadas ao calor nos estados do Amazonas e Rondônia para o ano de 2023, agregando os dados em “pentads” (intervalos de 5 dias) para estudos de efeitos cumulativos de ondas de calor.

6.1. Código do Pipeline 

# Carregar pacotes
library(climasus4r)
library(dplyr)

# --- Pipeline Completo ---
df_calor <- sus_data_import(
  uf = c("AM", "RO"),
  year = 2023,
  system = "SIM-DO",
  parallel = TRUE,
  lang = "pt"
) %>%
  sus_data_clean_encoding(lang = "pt") %>%
  sus_data_standardize(lang = "pt") %>%
  sus_data_filter_cid(disease_group = "heat_related", lang = "pt") %>%
  sus_create_variables(
    create_age_groups = TRUE,
    lang = "pt"
  ) %>%
  sus_data_aggregate(
    time_unit = "5 days",  # Agregação em Pentads (intervalos de 5 dias)
    lang = "pt"
  )

# Salvar os resultados
sus_data_export(
  df_calor,
  file_path = "ondas_calor_pentads_am_ro_2023.csv",
  format = "csv",
  include_metadata = TRUE,
  lang = "pt"
)

head(df_calor)

6.2. Explicação Passo a Passo

  1. Importação: Dados de mortalidade para AM e RO em 2023
  2. sus_data_filter_cid: Filtro para grupo "heat_related" (insolação, calor excessivo)
  3. sus_data_aggregate: time_unit = "5 days" cria janelas consecutivas de 5 dias
  4. Aplicação: Essencial para estudos de ondas de calor com efeitos cumulativos

🎉 Conclusão

Estes quatro pipelines demonstram como o climasus4r pode ser adaptado para uma ampla gama de questões de pesquisa em saúde pública e ambiental. Ao dominar a combinação dessas funções com o operador pipe, você pode construir análises complexas de forma rápida, legível e reprodutível.

📚 Resumo dos Pipelines

Pipeline Sistema Agregação Foco
1. Respiratório Pediátrico SIM-DO Mensal Crianças < 5 anos
2. Dengue Sazonal SINAN-DENGUE Estação Padrões sazonais
3. Cardiovascular Idosos SIM-DO Semanal Idosos 65+
4. Ondas de Calor SIM-DO 5 dias Eventos extremos

💡 Próximos Passos

  1. Modifique os pipelines: Mude estados, anos, grupos de doenças
  2. Experimente agregações: Teste diferentes time_unit (day, week, month, season)
  3. Adicione group_by: Agrupe por múltiplas variáveis
  4. Combine com dados climáticos: Integre dados meteorológicos para análises de impacto

Recursos Adicionais: - Explore a documentação com ?sus_data_import - Visite o repositório GitHub - Pratique o operador pipe em seus próprios projetos

🌲 Tem feedback ou sugestões?

Você tem alguma ideia de melhoria ou encontrou algum erro? Clique no botão abaixo para abrir uma nova issue no GitHub e compartilhar suas sugestões diretamente conosco.

Abrir issue no GitHub