Skip to contents

Primeiros passos com o Climasus4r

Max Anjos

02 April, 2026

Source: vignettes/tutorial_introducao.Rmd
tutorial_introducao.Rmd

Introdução

Tutorial Introdutório — Este tutorial apresenta um guia prático para começar a utilizar o pacote climasus4r. O objetivo é demonstrar o fluxo básico de trabalho, desde a instalação do pacote até a criação de séries temporais a partir de dados de saúde do DATASUS, integrando informações de saúde, clima e meio ambiente.

O Sistema Único de Saúde (SUS) disponibiliza grandes bases de dados públicos, como SIM, SIH, SINAN, CNES, SINASC. No entanto, esses dados geralmente exigem etapas de importação, limpeza, padronização e agregação antes de poderem ser utilizados em análises epidemiológicas.

O pacote climasus4r foi desenvolvido para automatizar e padronizar esse processo, permitindo análises reprodutíveis, rápidas e escaláveis em estudos de clima, ambiente e saúde pública.

🎯 O que você aprenderá

📦

Instalação

Instalar o pacote climasus4r de forma rápida e eficiente

⚡

Importação Otimizada

Importar dados do DATASUS com cache e processamento paralelo

🧹

Limpeza e Padronização

Corrigir codificação e padronizar variáveis

🔍

Filtragem

Filtrar por causas de óbito e variáveis demográficas

📊

Agregação Temporal

Criar séries temporais diárias, mensais e anuais

💾

Exportação e Importação

Salvar e carregar dados com metadados completos

📋 O Fluxo de Trabalho do climasus4r

A análise de dados com o climasus4r segue um pipeline lógico e sequencial, onde o resultado de uma função é a entrada para a próxima. Este design, inspirado no tidyverse, torna o código mais legível e fácil de manter.

sus_data_import() → sus_data_clean_encoding() → sus_data_standardize() → sus_create_variables() → sus_data_filter_cid() → sus_data_filter_demographics() → sus_data_aggregate()

Cada função executa uma etapa específica do processamento, como importação, limpeza, padronização, filtragem e agregação dos dados. Ao final desse pipeline, os dados estarão organizados e prontos para análises epidemiológicas ou construção de séries temporais.

1. Instalação

O pacote climasus4r está disponível no GitHub e pode ser instalado de duas formas. Recomendamos a Opção 1 para a maioria dos usuários.

Caso você ainda não tenha o pacote remotes instalado, execute o código abaixo:

if (!require("remotes")) { install.packages("remotes")}

Opção 1: Instalação via GitHub (Recomendado)

Esta é a forma mais rápida de obter a versão mais recente:

# Instalar ou atualizar o pacote diretamente do GitHub
remotes::install_github("ByMaxAnjos/climasus4r", upgrade = "never")

Atualizações: O climasus4r está em desenvolvimento ativo. Para atualizar, basta executar o comando acima novamente. O R irá sobrescrever a versão antiga automaticamente. Após a atualização, recomenda-se reiniciar a sessão (Menu: Session > Restart R).

Opção 2: Instalação via Arquivo Local (.zip)

Esta opção é recomendada para ambientes com instabilidade de conexão, restrições de rede ou uso em treinamentos com múltiplos usuários.

  1. Baixar o pacote: Clique AQUI para baixar o .zip
  2. Extrair o arquivo: Extraia o conteúdo em uma pasta de fácil acesso (ex: Downloads ou Desktop)
  3. Instalar localmente:
# IMPORTANTE: Altere o caminho abaixo para o local onde você salvou o pacote
remotes::install_local(
  "C:/Caminho/Para/Sua/Pasta/climasus4r-master", 
  upgrade = "never"
)

2. Carregando o Pacote

Após a instalação, carregue o pacote sempre que iniciar uma nova sessão no R:

library(climasus4r)

3. Importação de Dados com sus_data_import()

A primeira etapa do fluxo consiste na importação dos dados. A função sus_data_import() automatiza o download e a leitura dos microdados do DATASUS.

O DATASUS possui diversos sistemas de informação. Neste tutorial, utilizaremos o SIM-DO (mortalidade) como exemplo.

Exemplo Básico

Vamos importar dados de mortalidade dos estados de Rondônia ("RO") e Amazonas ("AM") para os anos de 2016 a 2017:

df_raw <- sus_data_import(
  system = "SIM-DO",
  year = 2016:2017,
  uf = c("RO", "AM"),
  lang = "pt"
)

head(df_raw)

O que aconteceu? A função sus_data_import() realizou automaticamente: 1. Download: Baixou os arquivos .DBC do FTP do DATASUS 2. Descompactação: Extraiu os arquivos contidos nos .DBC 3. Leitura: Leu todos os arquivos em um único data.frame 4. Metadados: Adicionou informações sobre a origem dos dados

Otimizando a Importação: Cache e Processamento Paralelo

Usando Cache para Evitar Re-downloads

Por padrão (use_cache = TRUE), a função salva uma cópia dos dados baixados. Na próxima execução com os mesmos parâmetros, os dados serão lidos diretamente do cache.

df_custom_cache <- sus_data_import(
  system = "SIM-DO",
  year = 2018,
  uf = "RO",
  use_cache = TRUE,
  cache_dir = "~/.climasus4r_cache/data",
  lang = "pt"
)
Acelerando com Processamento Paralelo 
# Baixar dados de 3 estados em paralelo
df_parallel <- sus_data_import(
  system = "SIM-DO",
  year = 2018:2020,
  uf = c("RO", "PA", "MT"),
  use_cache = TRUE,
  parallel = TRUE,
  workers = 3,
  lang = "pt"
)

Quantos workers usar? Um bom ponto de partida é usar o número de núcleos do seu processador menos um (parallel::detectCores() - 1).

4. Limpeza de Codificação com sus_data_clean_encoding()

Os dados do DATASUS frequentemente vêm com problemas de codificação de caracteres. A função sus_data_clean_encoding() resolve isso convertendo todas as colunas de texto para UTF-8.

# Corrigir a codificação de caracteres
df_clean <- sus_data_clean_encoding(df_raw, lang = "pt")

head(df_clean)

5. Padronização de Dados com sus_data_standardize()

Esta etapa é crucial para a consistência da análise. A função realiza:

  • Renomeia colunas para nomes padronizados (ex: CAUSABAS → underlying_cause_of_death)
  • Converte colunas para os tipos de dados corretos
  • Cria novas variáveis úteis como faixas etárias
df_std <- sus_data_standardize(df_clean, lang = "pt")

head(df_std)

Objeto climasus_df: A partir deste ponto, nosso data.frame possui uma classe especial que permite o fluxo contínuo de metadados entre as funções.

6. Criação de Variáveis com sus_create_variables()

Antes de filtrar, frequentemente queremos criar variáveis derivadas. A função sus_create_variables() permite criar:

  • Faixas etárias: Grupos personalizados ou padrão IBGE
  • Variáveis de calendário: Dia da semana, mês, estação do ano
  • Outras variáveis: Década de nascimento, etc.
df_vars <- sus_create_variables(
  df_std,
  create_age_groups = TRUE,
  create_calendar_vars = TRUE,
  lang = "pt"
)

head(df_vars)

Novas colunas criadas: - faixa_etaria_ibge: Grupos etários de 5 anos (padrão IBGE) - dia_da_semana: Segunda a Domingo - mes_nome: Nome do mês - estacao: Estação do ano - semana_do_ano: Número da semana

7. Filtragem por Causa de Óbito com sus_data_filter_cid()

Vamos filtrar os dados para selecionar apenas óbitos por doenças respiratórias e doenças cardiovasculares.

df_cid <- sus_data_filter_cid(
  df_vars,
  disease_group = c("respiratory", "cardiovascular"),
  lang = "pt"
)

head(df_cid)

Explorando os Grupos de Doenças Disponíveis 

# Abrir interface interativa de exploração
sus_filter_cid_explore(lang = "pt")

Grupos de doenças comumente usados: - respiratory (doenças respiratórias) - cardiovascular (doenças cardiovasculares) - neoplasms (neoplasias/câncer) - diabetes (diabetes mellitus) - infectious (doenças infecciosas)

8. Filtragem por Variáveis Demográficas com sus_data_filter_demographics()

Vamos refinar o filtro para um subgrupo demográfico específico:

  • Sexo: Feminino
  • Idade: Entre 20 e 59 anos
  • Raça/Cor: Preta ou Parda
df_demo <- sus_data_filter_demographics(
  df_cid,
  sex = "Feminino",
  age_range = c(20, 59),
  race = c("Preta", "Parda"),
  lang = "pt"
)

head(df_demo)

Idioma: Quando lang = "pt", use os valores em português: "Feminino", "Masculino", "Preta", "Parda", etc.

9. Agregação Temporal com sus_data_aggregate()

Finalmente, vamos agregar os registros para criar séries temporais.

Agregação Mensal 

df_monthly <- sus_data_aggregate(
  df_demo,
  time_unit = "month",
  lang = "pt"
)

head(df_monthly)

Agregação Diária 

df_daily <- sus_data_aggregate(
  df_demo,
  time_unit = "day",
  lang = "pt"
)

head(df_daily)

10. Exportação de Dados com sus_data_export()

Formatos Suportados

Formato Extensão Uso Recomendado
RDS .rds Formato nativo do R
Parquet .parquet Grande volume, interoperabilidade
CSV .csv Universal, compartilhamento
GeoParquet .geoparquet Dados espaciais otimizados
Shapefile .shp GIS tradicional

Exemplos de Exportação 

# Exportar em CSV com metadados
sus_data_export(
  df_monthly,
  file_path = "obitos_mensais_resumo_cardio.csv",
  format = "csv",
  include_metadata = TRUE,
  lang = "pt"
)
# Exportar em Parquet (mais eficiente)
sus_data_export(
  df_monthly,
  file_path = "obitos_mensais_resumo_cardio.parquet",
  format = "parquet",
  include_metadata = TRUE,
  lang = "pt"
)

Exportação com Metadados Personalizados 

sus_data_export(
  df_monthly,
  file_path = "analise_especifica.csv",
  format = "csv",
  include_metadata = TRUE,
  metadata = list(
    source_system = "SIM-DO",
    states = c("RO", "AM"),
    years = c(2016, 2017),
    disease_groups = c("respiratory", "cardiovascular"),
    author = "Seu Nome",
    project = "Estudo Clima e Saúde"
  ),
  lang = "pt"
)

11. Importação de Dados com sus_data_read()

Leitura de Arquivo Único 

df_lido <- sus_data_read(
  path = "obitos_mensais_resumo_cardio.csv",
  format = "csv",
  read_metadata = TRUE,
  lang = "pt"
)

# Acessar os metadados
climasus_meta(df_lido, print_history = TRUE)

Leitura em Lote (Múltiplos Arquivos) 

# Ler todos os arquivos CSV de uma pasta
df_diretorio <- sus_data_read(
  path = "resultados_analises/",
  format = "csv",
  lang = "pt"
)

Leitura com Processamento Paralelo 

df_paralelo <- sus_data_read(
  path = "pasta_de_dados/",
  format = "parquet",
  parallel = TRUE,
  workers = 4,
  read_metadata = TRUE,
  lang = "pt"
)

🎉 Conclusão

Parabéns! Você completou o fluxo de trabalho básico do climasus4r. Em poucos passos, você foi capaz de:

  • Baixar e importar dados brutos do DATASUS de forma otimizada
  • Limpar, padronizar e enriquecer os dados com novas variáveis
  • Filtrar por critérios epidemiológicos e demográficos
  • Criar séries temporais prontas para análise
  • Exportar e importar dados com metadados completos

📚 Próximos Passos

  1. Experimente outros sistemas (system = "SIH" para hospitalizações)
  2. Teste diferentes estados e anos
  3. Explore diferentes grupos de doenças
  4. Combine com dados climáticos para análises de impacto
  5. Consulte a documentação completa: github.com/ByMaxAnjos/climasus4r

🌲 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