Primeros pasos con Climasus4r

Introducción

Tutorial Introductorio — Este tutorial presenta una guía práctica para comenzar a utilizar el paquete climasus4r. El objetivo es demostrar el flujo básico de trabajo, desde la instalación del paquete hasta la creación de series temporales a partir de datos de salud del DATASUS, integrando información de salud, clima y medio ambiente.

El Sistema Único de Salud (SUS) pone a disposición grandes bases de datos públicas, como SIM, SIH, SINAN, CNES, SINASC. Sin embargo, estos datos generalmente requieren etapas de importación, limpieza, estandarización y agregación antes de poder ser utilizados en análisis epidemiológicos.

El paquete climasus4r fue desarrollado para automatizar y estandarizar este proceso, permitiendo análisis reproducibles, rápidos y escalables en estudios de clima, ambiente y salud pública.

🎯 Lo que aprenderá

📦

Instalación

Instalar el paquete climasus4r de forma rápida y eficiente

⚡

Importación Optimizada

Importar datos del DATASUS con caché y procesamiento paralelo

🧹

Limpieza y Estandarización

Corregir la codificación y estandarizar variables

🔍

Filtrado

Filtrar por causas de defunción y variables demográficas

📊

Agregación Temporal

Crear series temporales diarias, mensuales y anuales

💾

Exportación e Importación

Guardar y cargar datos con metadatos completos

📋 El Flujo de Trabajo de `climasus4r`

El análisis de datos con climasus4r sigue un pipeline lógico y secuencial, donde el resultado de una función es la entrada de la siguiente. Este diseño, inspirado en el tidyverse, hace que el código sea más legible y fácil de mantener.

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

Cada función ejecuta una etapa específica del procesamiento, como importación, limpieza, estandarización, filtrado y agregación de los datos. Al final de este pipeline, los datos estarán organizados y listos para análisis epidemiológicos o construcción de series temporales.

1. Instalación

El paquete climasus4r está disponible en GitHub y puede instalarse de dos formas. Recomendamos la Opción 1 para la mayoría de los usuarios.

Si aún no tiene el paquete remotes instalado, ejecute el código a continuación:

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

Opción 1: Instalación vía GitHub (Recomendado)

Esta es la forma más rápida de obtener la versión más reciente:

# Instalar o actualizar el paquete directamente desde GitHub
remotes::install_github("ByMaxAnjos/climasus4r", upgrade = "never")

Actualizaciones: climasus4r está en desarrollo activo. Para actualizar, basta con ejecutar el comando anterior nuevamente. R sobrescribirá la versión antigua automáticamente. Después de la actualización, se recomienda reiniciar la sesión (Menú: Session > Restart R).

Opción 2: Instalación vía Archivo Local (.zip)

Esta opción se recomienda para entornos con inestabilidad de conexión, restricciones de red o uso en capacitaciones con múltiples usuarios.

Descargar el paquete: Haga clic AQUÍ para descargar el .zip
Extraer el archivo: Extraiga el contenido en una carpeta de fácil acceso (ej.: Descargas o Escritorio)
Instalar localmente:

# IMPORTANTE: Cambie la ruta a continuación por el lugar donde guardó el paquete
remotes::install_local(
  "C:/Ruta/Para/Su/Carpeta/climasus4r-master",
  upgrade = "never"
)

2. Cargando el Paquete

Después de la instalación, cargue el paquete siempre que inicie una nueva sesión en R:

library(climasus4r)

3. Importación de Datos con `sus_data_import()`

La primera etapa del flujo consiste en la importación de los datos. La función sus_data_import() automatiza la descarga y lectura de los microdatos del DATASUS.

El DATASUS posee diversos sistemas de información. En este tutorial, utilizaremos el SIM-DO (mortalidad) como ejemplo.

Ejemplo Básico

Vamos a importar datos de mortalidad de los estados de Rondônia ("RO") y Amazonas ("AM") para los años 2016 a 2017:

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

head(df_raw)

¿Qué sucedió? La función sus_data_import() realizó automáticamente: 1. Descarga: Descargó los archivos .DBC del FTP del DATASUS 2. Descompresión: Extrajo los archivos contenidos en los .DBC 3. Lectura: Leyó todos los archivos en un único data.frame 4. Metadatos: Añadió información sobre el origen de los datos

Optimizando la Importación: Caché y Procesamiento Paralelo

Usando Caché para Evitar Re-descargas

Por defecto (use_cache = TRUE), la función guarda una copia de los datos descargados. En la próxima ejecución con los mismos parámetros, los datos se leerán directamente de la caché.

df_custom_cache <- sus_data_import(
  system = "SIM-DO",
  year = 2018,
  uf = "RO",
  use_cache = TRUE,
  cache_dir = "~/.climasus4r_cache/data",
  lang = "es"
)

Acelerando con Procesamiento Paralelo

# Descargar datos de 3 estados en 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 = "es"
)

¿Cuántos workers usar? Un buen punto de partida es usar el número de núcleos de su procesador menos uno (parallel::detectCores() - 1).

4. Limpieza de Codificación con `sus_data_clean_encoding()`

Los datos del DATASUS frecuentemente vienen con problemas de codificación de caracteres. La función sus_data_clean_encoding() resuelve esto convirtiendo todas las columnas de texto a UTF-8.

# Corregir la codificación de caracteres
df_clean <- sus_data_clean_encoding(df_raw, lang = "es")

head(df_clean)

5. Estandarización de Datos con `sus_data_standardize()`

Esta etapa es crucial para la consistencia del análisis. La función realiza:

Renombra columnas con nombres estandarizados (ej.: CAUSABAS → underlying_cause_of_death)
Convierte columnas a los tipos de datos correctos
Crea nuevas variables útiles como rangos de edad

df_std <- sus_data_standardize(df_clean, lang = "es")

head(df_std)

Objeto climasus_df: A partir de este punto, nuestro data.frame posee una clase especial que permite el flujo continuo de metadatos entre las funciones.

6. Creación de Variables con `sus_data_create_variables()`

Antes de filtrar, frecuentemente queremos crear variables derivadas. La función sus_data_create_variables() permite crear:

Rangos de edad: Grupos personalizados o estándar IBGE
Variables de calendario: Día de la semana, mes, estación del año
Otras variables: Década de nacimiento, etc.

df_vars <- sus_data_create_variables(
  df_std,
  create_age_groups = TRUE,
  create_calendar_vars = TRUE,
  lang = "es"
)

head(df_vars)

Nuevas columnas creadas: - faixa_etaria_ibge: Grupos etarios de 5 años (estándar IBGE) - dia_da_semana: Lunes a Domingo - mes_nome: Nombre del mes - estacao: Estación del año - semana_do_ano: Número de la semana

7. Filtrado por Causa de Defunción con `sus_data_filter_cid()`

Vamos a filtrar los datos para seleccionar solo defunciones por enfermedades respiratorias y enfermedades cardiovasculares.

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

head(df_cid)

Explorando los Grupos de Enfermedades Disponibles

# Abrir interfaz interactiva de exploración
sus_data_cid_select(lang = "es")

Grupos de enfermedades comúnmente usados: - respiratory (enfermedades respiratorias) - cardiovascular (enfermedades cardiovasculares) - neoplasms (neoplasias/cáncer) - diabetes (diabetes mellitus) - infectious (enfermedades infecciosas)

8. Filtrado por Variables Demográficas con `sus_data_filter_demographics()`

Vamos a refinar el filtro para un subgrupo demográfico específico:

Sexo: Femenino
Edad: Entre 20 y 59 años
Raza/Color: Negra o Parda

df_demo <- sus_data_filter_demographics(
  df_cid,
  sex = "Feminino",
  age_range = c(20, 59),
  race = c("Preta", "Parda"),
  lang = "es"
)

head(df_demo)

Idioma: Cuando lang = "pt", use los valores en portugués: "Feminino", "Masculino", "Preta", "Parda", etc.

9. Agregación Temporal con `sus_data_aggregate()`

Finalmente, vamos a agregar los registros para crear series temporales.

Agregación Mensual

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

head(df_monthly)

Agregación Diaria

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

head(df_daily)

10. Exportación de Datos con `sus_data_export()`

Formatos Soportados

Formato	Extensión	Uso Recomendado
RDS	`.rds`	Formato nativo de R
Parquet	`.parquet`	Gran volumen, interoperabilidad
CSV	`.csv`	Universal, para compartir
GeoParquet	`.geoparquet`	Datos espaciales optimizados
Shapefile	`.shp`	GIS tradicional

Ejemplos de Exportación

# Exportar en CSV con metadatos
sus_data_export(
  df_monthly,
  file_path = "obitos_mensais_resumo_cardio.csv",
  format = "csv",
  include_metadata = TRUE,
  lang = "es"
)

# Exportar en Parquet (más eficiente)
sus_data_export(
  df_monthly,
  file_path = "obitos_mensais_resumo_cardio.parquet",
  format = "parquet",
  include_metadata = TRUE,
  lang = "es"
)

Exportación con Metadatos 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 = "Su Nombre",
    project = "Estudio Clima y Salud"
  ),
  lang = "es"
)

11. Importación de Datos con `sus_data_read()`

Lectura de Archivo Único

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

# Acceder a los metadatos
sus_meta(df_lido, print_history = TRUE)

Lectura en Lote (Múltiples Archivos)

# Leer todos los archivos CSV de una carpeta
df_diretorio <- sus_data_read(
  path = "resultados_analises/",
  format = "csv",
  lang = "es"
)

Lectura con Procesamiento Paralelo

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

🎉 Conclusión

¡Felicitaciones! Ha completado el flujo de trabajo básico de climasus4r. En pocos pasos, fue capaz de:

Descargar e importar datos brutos del DATASUS de forma optimizada
Limpiar, estandarizar y enriquecer los datos con nuevas variables
Filtrar por criterios epidemiológicos y demográficos
Crear series temporales listas para el análisis
Exportar e importar datos con metadatos completos

📚 Próximos Pasos

Pruebe otros sistemas (system = "SIH" para hospitalizaciones)
Pruebe diferentes estados y años
Explore diferentes grupos de enfermedades
Combine con datos climáticos para análisis de impacto
Consulte la documentación completa: github.com/ByMaxAnjos/climasus4r

🌲 ¿Tiene comentarios o sugerencias?

¿Tiene alguna idea de mejora o encontró algún error? Haga clic en el botón de abajo para abrir un nuevo issue en GitHub y compartir sus sugerencias directamente con nosotros.

Abrir issue en GitHub

Max Anjos

17 October, 2026