Cómo Construir un Paquete en R con Clases R6 (y Por Qué lo Volvería a Hacer)
De scripts dispersos a una arquitectura profesional: La evolución de manageDW. Un análisis detallado sobre cómo la migración a un paquete de R y el uso del sistema de clases R6 transformaron un conjunto de funciones frágiles en un pipeline de datos robusto, escalable y fácil de mantener para el procesamiento de datos del SII.

El Comienzo: Un Commit sin Estructura
El 2 de julio de 2025 hice el primer commit de manageDW. No había casi nada: un .gitignore, un DESCRIPTION básico y la intención declarada de construir un data warehouse con datos del SII. Siete días después, otros tres commits limpiando archivos .Rhistory y .txt que había olvidado ignorar. Eso fue todo el mes de julio.
El trabajo real empezó el 26 de septiembre de 2025: ocho commits en un solo día. ETL que intentaba leer archivos Excel del SII, soporte para el formato .xlsb que usa el SII, una capa de staging, el primer esquema estrella. Funcionaba, pero el código era una colección de funciones sueltas dispersas en scripts. Una función leer_archivo_sii() aquí, otra cargar_fact_empresas() allá, y la conexión a la base de datos se creaba y se cerraba en distintos lugares.
No hubo commits en octubre, noviembre, ni diciembre. Cuatro meses de silencio en el repositorio.
El 24 de enero de 2026, el commit 385aa04 dice: "refactor: Migrar ETL a clase R6 ETLStarSchemaSII v0.1.0". Ese día redesigné todo como un paquete R formal con clases R6 como columna vertebral. Esto es lo que aprendí en el proceso.
¿Por Qué un Paquete y No un Proyecto Suelto?
Un paquete R no es solo para publicar en CRAN. Es una estructura de directorios que te da gratis:
- Documentación automática con roxygen2 (
?ETLStarSchemaSIIfunciona) - Gestión de dependencias en el archivo
DESCRIPTION - Namespace limpio donde no contaminas el entorno global
- Tests reproducibles con testthat
- Build automático (
R CMD checkverifica todo por ti)
::tip
El directorio scripts/ es una adición común fuera del estándar CRAN. Aloja los scripts de orquestación del pipeline (sii_pipeline.R) que usan las clases sin ser parte del paquete instalable.
::
La estructura mínima:
manageDW/
├── R/ # Código fuente
│ ├── ETLStarSchemaSII.R
│ ├── ImputadorVentasSII.R
│ └── DashboardActividadesSII.R
├── man/ # Documentación (generada por roxygen2)
├── scripts/ # Scripts de ejecución (no forman parte del paquete)
├── DESCRIPTION # Metadatos y dependencias
├── NAMESPACE # Exportaciones (generado automáticamente)
└── data-raw/ # Datos fuente (no se instalan)
La clave es que todo lo que va en R/ es código reutilizable. Los scripts en scripts/ son los que ejecutan el pipeline, pero la lógica vive en las clases.
R6: El Sistema de Clases Que R Debería Haber Tenido Desde el Principio
R tiene tres sistemas de clases: S3, S4 y R6. La elección no es trivial.
S3: Simple Pero Frágil
S3 es el sistema de clases por defecto de R. Cuando summary(modelo) produce resultados distintos según si modelo es un lm o un glm, eso es dispatch de S3:
# Definir una clase S3
mi_modelo <- list(coefs = c(1.2, 3.4), r2 = 0.87)
class(mi_modelo) <- "ModeloSimple"
# Método para esa clase
print.ModeloSimple <- function(x, ...) {
cat("R² =", x$r2, "\n")
}
Funciona, pero S3 no tiene encapsulamiento. Cualquiera puede hacer mi_modelo$r2 <- -999 y romper el objeto. S3 carece de constructor formal, métodos privados y protección de estado. Para un proyecto con estado mutable —como una conexión a base de datos que debe abrirse, usarse y cerrarse— S3 es insuficiente.
::warning S3 no previene modificaciones externas. Si pasas un objeto S3 a una función desconocida, no puedes garantizar que los campos internos permanezcan intactos. ::
S4: Formal Pero Burocrático
S4 resuelve el problema de la formalidad con setClass(), setGeneric() y setMethod(). Es lo que usan Bioconductor y muchos paquetes académicos. Pero la cantidad de boilerplate es enorme:
setClass("Pipeline",
representation(
con = "ANY",
data = "data.frame"
)
)
setGeneric("run", function(object, ...) standardGeneric("run"))
setMethod("run", "Pipeline", function(object, ...) {
# implementación
})
Para un sistema orientado a objetos de verdad, con estado mutable y encadenamiento de métodos, S4 es demasiado rígido.
R6: Orientación a Objetos Real
R6 se comporta como el sistema de clases de Python o Java. Tiene constructores, métodos públicos y privados, campos mutables, y los objetos se pasan por referencia (no por copia, como todo lo demás en R):
ETLStarSchemaSII <- R6::R6Class(
classname = "ETLStarSchemaSII",
public = list(
con = NULL, # Conexión a PostgreSQL
dt_list = NULL, # Datos leídos
initialize = function(data_path, db_name) {
self$data_path <- data_path
self$db_name <- db_name
# Conectar automáticamente
self$conectar()
invisible(self)
},
run = function() {
self$extract()
self$validate()
self$transform()
self$load()
invisible(self)
}
),
private = list(
log_timestamped = function(msg) {
message(Sys.time(), " | ", msg)
}
)
)
::note
El método run() devuelve invisible(self). Este patrón permite encadenar métodos: obj$new(...)$run()$show_summary() sin imprimir el objeto intermedio en la consola.
::
Tres características de R6 que resultan decisivas en este proyecto:
1. Paso por referencia. En R normal, f(x) crea una copia de x. Si x es un data.table de 50 millones de filas, eso es un problema. Los objetos R6 se pasan por referencia: cuando el método $load() modifica self$con, el cambio se refleja inmediatamente en el objeto original. Perfecto para gestionar conexiones a base de datos.
2. Métodos privados. La función private$leer_archivo_sii() lee un archivo Excel con lógica compleja (multi-hojas, conversión de formato chileno, regex para extraer metadatos). Ese detalle no debería ser parte de la API pública. Con private = list(...) queda oculto y solo los métodos de la clase pueden usarlo.
3. Finalizer. R6 permite definir un destructor que el garbage collector ejecuta automáticamente cuando el objeto se destruye:
private = list(
finalize = function() {
if (!is.null(self$con)) {
DBI::dbDisconnect(self$con)
message("Conexión cerrada automáticamente")
}
}
)
El finalizer evita conexiones a PostgreSQL abiertas indefinidamente. Ni S3 ni S4 tienen un equivalente.
::important
El finalizer solo corre cuando el garbage collector de R destruye el objeto. Para cerrar la conexión de forma inmediata y determinista, llama etl$desconectar() explícitamente al terminar el pipeline.
::
La Arquitectura de manageDW: Tres Clases, Tres Responsabilidades
El patrón es simple: cada clase R6 resuelve un problema.
| Clase | Responsabilidad | Entrada | Salida |
|---|---|---|---|
ETLStarSchemaSII |
Extracción, transformación y carga | Archivos Excel del SII | Modelo estrella en PostgreSQL |
ImputadorVentasSII |
Imputación Random Forest + IPF con trazabilidad | Conexión a PostgreSQL | Valores imputados + dim_imputado |
DashboardActividadesSII |
Visualización interactiva | Conexión a PostgreSQL | Shiny app dark mode con mapas y series |
Cada clase recibe una conexión DBI y trabaja sobre la base de datos dm_sii. No se pasan data.frames gigantes entre clases; PostgreSQL es la fuente de verdad.
El Pipeline Completo
# scripts/sii_pipeline.R
# 1. ETL: Excel → PostgreSQL
etl <- ETLStarSchemaSII$new(
data_path = here::here("data-raw", "sii"),
db_name = "DM_SII"
)
etl$run()
# 2. Imputación: IPF sobre la base cargada
imp <- ImputadorVentasSII$new(
con = etl$con,
max_iter = 100,
tolerancia = 1e-6,
variables_imputar = c("ventas_uf", "renta_neta_uf")
)
imp$imputar()
# 3. Dashboard: Explorar resultados
dash <- DashboardActividadesSII$new(con = etl$con)
dash$run(port = 8080)
Cinco líneas que encadenan tres sistemas complejos. Eso es lo que una buena abstracción te da.
Patrones Concretos en R6
Constructor con Validación
Un buen initialize() valida sus entradas y deja el objeto en un estado consistente:
initialize = function(con, max_iter = 100, tolerancia = 1e-6,
variables_imputar = c("ventas_uf", "renta_neta_uf")) {
if (is.null(con)) stop("Debe proporcionar una conexión DBI activa")
self$con <- con
self$max_iter <- max_iter
self$tolerancia <- tolerancia
self$variables_imputar <- variables_imputar
private$log_timestamped("ImputadorVentasSII inicializado")
invisible(self)
}
El invisible(self) es un patrón estándar: permite encadenar $new(...)$imputar() sin que el constructor imprima el objeto.
Logging Consistente
Todas las clases comparten un patrón de logging con timestamps:
private = list(
timestamp_inicio = NULL,
log_timestamped = function(msg, indent = 1) {
prefix <- strrep(" ", indent)
elapsed <- round(difftime(Sys.time(), private$timestamp_inicio, units = "secs"), 1)
message(prefix, "[", format(Sys.time(), "%H:%M:%S"), " +", elapsed, "s] ", msg)
},
log_progress = function(current, total, msg) {
pct <- round(100 * current / total)
bar <- paste0("[", strrep("=", pct %/% 5), strrep(" ", 20 - pct %/% 5), "]")
message(" ", bar, " ", pct, "% ", msg)
}
)
Cuando procesas 9 archivos Excel con 19 hojas cada uno, saber en qué paso estás no es un lujo.
Transacciones Atómicas con PostgreSQL
Toda operación de escritura usa dbWithTransaction():
private$cargar_dim_actividad = function() {
DBI::dbWithTransaction(self$con, {
DBI::dbWriteTable(self$con, "tmp_actividad", self$dim_actividad,
temporary = TRUE, overwrite = TRUE)
DBI::dbExecute(self$con, "
INSERT INTO dim_actividad (actividad_cod, nombre, subrubro_cod, ...)
SELECT * FROM tmp_actividad
ON CONFLICT (actividad_cod) DO UPDATE SET
nombre = EXCLUDED.nombre,
subrubro_cod = EXCLUDED.subrubro_cod
")
})
}
Si algo falla a la mitad de la inserción, la transacción hace rollback y la base de datos queda intacta. El patrón tmp_table → INSERT ... ON CONFLICT → DO UPDATE permite reejecutar el pipeline sin duplicar datos.
Documentación con roxygen2
Cada clase y método lleva documentación roxygen2 que se convierte en páginas de ayuda estándar de R:
#' @title ETLStarSchemaSII
#' @description Clase R6 para el proceso ETL de normalización a modelo estrella
#' de datos SII de empresas por actividad económica.
#' @field data_path Ruta del directorio con archivos fuente Excel
#' @field con Conexión activa a PostgreSQL
#' @export
#' @importFrom R6 R6Class
#' @importFrom data.table data.table setDT rbindlist
#' @importFrom DBI dbConnect dbDisconnect dbExecute dbGetQuery
ETLStarSchemaSII <- R6::R6Class(...)
Con devtools::document(), roxygen2 genera los archivos .Rd en man/ y actualiza el NAMESPACE automáticamente. Un usuario puede hacer ?ETLStarSchemaSII y ver la documentación completa.
Lecciones Aprendidas
1. R6 no es para todo. Si tu función toma un vector y devuelve otro vector, un function() simple es mejor. R6 brilla cuando tienes estado que evoluciona: conexiones de base de datos, pipelines con pasos secuenciales, configuración que se comparte entre métodos.
2. Separa la lógica del script. El código en R/ no debería hacer library() ni source(). Las dependencias van en DESCRIPTION y los @import en roxygen2. Los scripts en scripts/ son los que orquestan.
3. El DESCRIPTION es tu contrato. Cada paquete que uses debe estar en Imports::
Imports:
R6,
data.table,
DBI,
RPostgres,
readxl,
stringr,
glue,
here,
dotenv,
shiny,
bslib,
ggplot2,
plotly,
leaflet,
DT,
magrittr,
ranger
ranger se incorporó en v0.3.2 para la inicialización de valores faltantes con Random Forest antes del raking IPF.
Si corres R CMD check y algo no está declarado, el check falla. Es molesto al principio pero te salva de sorpresas en producción.
4. data.table + R6 = velocidad con estructura. data.table es el motor de datos más rápido en R. R6 le pone una capa de organización encima. El ETL procesa 9 archivos Excel con 19 hojas cada uno (171 data.tables) en menos de 2 minutos gracias a rbindlist(), operaciones in-place con :=, y agrupación optimizada con by. El imputador ImputadorVentasSII también usa data.table para las iteraciones IPF sobre ~500.000 celdas de la tabla multidimensional.
Reflexión
El commit 385aa04 del 24 de enero de 2026 no fue solo un refactor técnico. Fue el reconocimiento de que manageDW había crecido más allá de lo que una colección de funciones propias podía sostener.
El código anterior funcionaba. Pero cada vez que quería agregar una variable nueva para imputar, tenía que rastrear dónde se inicializaba la conexión, dónde se cerraba, qué funciones asumían que la conexión estaba abierta. R6 eliminó esos problemas de raíz: la conexión vive en private$con, los métodos del objeto la usan libremente, y finalize() la cierra cuando el objeto se destruye.
El precio fue aprender una API con curva de aprendizaje. El retorno fue un refactor tan limpio que el commit siguiente, e130fea, pudo agregar el fix del formato decimal chileno (un bug crítico donde los puntos como separadores de miles se interpretaban como decimales) sin tocar nada del resto de la arquitectura. Eso es señal de que la separación de responsabilidades funcionó.
Cuatro meses de funciones sueltas. Un día de refactor a R6. El orden tiene sentido: entender el problema primero, luego organizar la solución.
En v0.3.2 el sistema absorbió una nueva dependencia (ranger para Random Forest) y un nuevo paso algorítmico (inicialización con RF antes del raking IPF) sin cambios en ninguna de las otras clases. La separación de responsabilidades funcionó exactamente como se esperaba.
Para Empezar
Si tienes un proyecto de análisis que ya superó el umbral de "un script", estos son los pasos:
# 1. Crear la estructura del paquete
usethis::create_package("miPaquete")
# 2. Agregar dependencias
usethis::use_package("R6")
usethis::use_package("data.table")
# 3. Crear un archivo R6
usethis::use_r("MiClase")
# 4. Documentar y verificar
devtools::document()
devtools::check()
Tu yo del futuro te lo va a agradecer.