eyeris: A flexible, extensible, and reproducible pupillometry preprocessing framework in R

El artículo presenta *eyeris*, un paquete de código abierto en R que ofrece un marco de preprocesamiento modular, transparente y basado en los principios FAIR para datos de pupilometría, con el objetivo de estandarizar y mejorar la reproducibilidad de esta área de investigación.

Lo esencial

Imagina que tus ojos son como ventanas mágicas que revelan lo que está pasando en tu cerebro. Cuando estás concentrado, emocionado o cansado, tus pupilas cambian de tamaño, como si fueran pequeñas cámaras que se abren y cierran. Los científicos usan estas pequeñas cámaras (un proceso llamado pupilografía) para entender cómo pensamos, sentimos y aprendemos.

Sin embargo, hay un gran problema: las "fotos" que toman estas cámaras suelen venir con mucho "ruido". Imagina que intentas escuchar una canción favorita, pero hay gente gritando, el coche suena y hay estática. Para entender la música, primero tienes que limpiar el audio.

Aquí es donde entra eyeris.

¿Qué es eyeris?

eyeris es como un asistente de cocina de alta tecnología para los científicos que estudian las pupilas. Antes, cada científico tenía que cocinar sus propios ingredientes (limpiar sus propios datos) usando recetas diferentes, lo que hacía que los resultados fueran difíciles de comparar. A veces, uno cocinaba demasiado la comida y otras veces la dejaba cruda.

eyeris es un nuevo "recetario" (un programa de computadora hecho en el lenguaje R) que estandariza todo. Su objetivo es que todos los científicos cocinen de la misma manera, asegurando que el plato final sea delicioso y reproducible.

¿Cómo funciona? (La analogía del taller de restauración)

Imagina que los datos crudos de las pupilas son un cuadro antiguo y sucio que acaba de llegar a un taller de restauración. eyeris es el equipo de expertos que lo limpia paso a paso:

1. Limpiar las manchas (Eliminar parpadeos): Cuando parpadeas, la cámara ve negro por un segundo. eyeris detecta esos momentos de "oscuridad" y los rellena inteligentemente, como si un pintor rellenara un hueco en la tela para que la imagen sea continua.
2. Quitar el polvo (Eliminar errores): A veces, la cámara se confunde y ve un "salto" brusco en el tamaño de la pupila (como un rayo en el cielo). eyeris sabe que eso no es real y lo elimina suavemente.
3. Suavizar la imagen (Filtrar el ruido): La pupila se mueve un poco de forma natural, pero a veces hay temblores. eyeris aplica un "filtro suave" (como un filtro de café) para dejar pasar solo los movimientos importantes y quitar el temblor de fondo.
4. Ajustar el brillo (Normalizar): Cada persona tiene un tamaño de pupila diferente (algunos tienen ojos grandes, otros pequeños). eyeris ajusta el brillo y el contraste de cada persona para que todos se comparen en la misma escala, como si todos usaran la misma unidad de medida.

¿Por qué es tan especial? (La caja de cristal)

La mayoría de los programas antiguos son como cajas negras: metes los datos, sales el resultado, pero no sabes qué pasó por dentro. Si algo sale mal, no sabes por qué.

eyeris es una "caja de cristal".

• Transparencia total: Puedes ver cada paso que da el programa.
• Informes visuales: Al terminar, te entrega un álbum de fotos interactivo (un reporte HTML) que te muestra el "antes y después" de cada participante. Es como tener un detective que te muestra exactamente dónde estaba la suciedad y cómo la limpió.
• Reproducibilidad: Si otro científico quiere usar tus datos, puede ver exactamente qué pasos seguiste y repetir el proceso sin errores.

¿Para qué sirve todo esto?

Gracias a eyeris, la ciencia de las pupilas se vuelve más confiable.

• Para los novatos: Es como tener un GPS. No necesitas ser un experto en programación para limpiar tus datos; el programa te guía paso a paso.
• Para los expertos: Es como tener un taller de herramientas modular. Si quieres inventar una nueva forma de limpiar un tipo específico de "suciedad", puedes añadir tu propia herramienta al programa sin romper el resto.
• Para el futuro: El programa guarda todo en una base de datos organizada (como una biblioteca perfecta), lo que permite manejar miles de experimentos a la vez sin perderse en un montón de papeles.

En resumen

eyeris es el puente entre los datos crudos y desordenados de las pupilas y la ciencia clara y confiable. Transforma el caos en orden, asegurando que cuando los científicos digan "la pupila de esta persona se expandió porque estaba emocionada", todos sepamos que es verdad y que se puede verificar.

Es una herramienta que hace que la ciencia sea más abierta, transparente y fácil de entender, permitiendo que descubramos más secretos de la mente humana a través de la ventana de nuestros ojos.

Resumen técnico

Resumen Técnico: eyeris, un marco de preprocesamiento de pupilarimetría flexible y reproducible en R

1. El Problema

La pupilarimetría (medición del tamaño de la pupila) se ha establecido como una ventana no invasiva crucial para estudiar procesos cognitivos y autonómicos como la atención, la carga cognitiva, el estrés y la actividad del sistema noradrenérgico del locus coeruleus (LC). Sin embargo, a diferencia de otras modalidades de neuroimagen como la fMRI (que cuenta con herramientas estandarizadas como fMRIPrep) o la EEG (con EEGLAB o MNE-Python), la investigación en pupilarimetría carece de un marco de preprocesamiento robusto, estandarizado y reproducible.

Los desafíos actuales incluyen:

• Falta de estandarización: No existe un flujo de trabajo comúnmente aceptado; los pasos de preprocesamiento y sus parámetros varían drásticamente entre estudios.
• Riesgo de "caminos de bifurcación" (Garden of Forking Paths): La flexibilidad excesiva en la elección de métodos de preprocesamiento (filtrado, manejo de artefactos, etc.) sin guías prescriptivas aumenta el riesgo de errores de Tipo I y reduce la reproducibilidad.
• Herramientas existentes insuficientes: Los paquetes actuales a menudo son rígidos, carecen de principios FAIR (Findability, Accessibility, Interoperability, Reusability), no ofrecen informes de control de calidad interactivos o no permiten una comparación transparente entre datos crudos y procesados.
• Gestión de datos: La falta de esquemas de archivo unificados dificulta la gestión de grandes conjuntos de datos y la compartición de datos.

2. Metodología: El paquete R eyeris

Los autores desarrollaron eyeris, un paquete de software de código abierto en R diseñado para llenar este vacío. Su arquitectura se basa en el principio de "caja de cristal" (glass-box), a diferencia de las "cajas negras", permitiendo a los usuarios entender y evaluar cada paso del procesamiento.

Componentes clave del flujo de trabajo:
El núcleo del paquete es la función glassbox(), que ejecuta una secuencia prescrita y transparente de pasos de preprocesamiento, aunque también permite el uso modular de funciones individuales:

1. Carga y análisis (load_asc): Parsea archivos .asc de EyeLink (el estándar en la industria), extrayendo series temporales, eventos y metadatos. Maneja automáticamente múltiples segmentos y datos binoculares.
2. Eliminación de artefactos de parpadeo (deblink): Rellena los periodos de datos faltantes (parpadeos) con valores NA y extiende el periodo de exclusión hacia adelante y atrás (por defecto 50 ms) para eliminar artefactos de occlusión parcial.
3. Eliminación de artefactos transitorios (detransient): Detecta y elimina picos no fisiológicos (causados por inestabilidad del seguimiento o movimiento de la cabeza) utilizando un umbral basado en la Desviación Absoluta Mediana (MAD) de la velocidad de cambio de la pupila.
4. Interpolación lineal (interpolate): Rellena los datos faltantes restantes para recuperar una traza temporal continua, utilizando interpolación lineal adecuada para la dinámica lenta de la pupila.
5. Filtrado de paso bajo (lpfilt): Suaviza la serie temporal aplicando un filtro Butterworth de paso bajo (corte de paso en 4 Hz, corte de parada en 8 Hz) para eliminar ruido de alta frecuencia sin distorsionar la señal fisiológica.
6. Reducción de muestreo (downsample) o Binning (bin): Ofrece opciones para reducir la frecuencia de muestreo manteniendo la dinámica temporal (con filtro anti-aliasing) o promediar en intervalos de tiempo.
7. Eliminación de tendencias (detrend): (Opcional) Elimina derivas lineales lentas, aunque está desactivado por defecto para preservar la activación tónica fisiológicamente significativa.
8. Estandarización Z (zscore): Normaliza los datos (media 0, desviación estándar 1) por bloque/participante para facilitar comparaciones entre sujetos, asumiendo que las variaciones absolutas de tamaño de pupila son menos relevantes que las dinámicas relativas.
9. Epocamiento (epoch): Extrae ensayos basados en mensajes de eventos, con soporte avanzado para la extracción de metadatos incrustados en las cadenas de texto de los eventos (sintaxis de corchetes {}).

Características de Infraestructura:

• Modos de operación: Funciona en modo interactivo (con prompts para validar gráficos en tiempo real) y modo "headless" (automatizado para clusters en la nube).
• Almacenamiento de base de datos: Integra DuckDB para gestionar grandes volúmenes de datos preprocesados en un solo archivo, permitiendo consultas SQL eficientes sin cargar todo en memoria.
• Estructura BIDS-like: Genera una estructura de directorios organizada similar a BIDS (Brain Imaging Data Structure), separando datos crudos de derivados.
• Visualización: Genera automáticamente informes HTML interactivos con gráficos diagnósticos para cada paso, sujeto y ensayo.

3. Contribuciones Clave

• Flujo de trabajo prescriptivo y transparente: A diferencia de las guías conceptuales anteriores, eyeris ofrece una implementación de código lista para usar que reduce la ambigüedad en la toma de decisiones de preprocesamiento.
• Arquitectura modular y extensible: Los usuarios pueden usar el flujo completo (glassbox) o construir pipelines personalizados utilizando funciones modulares, manteniendo la trazabilidad de los pasos.
• Control de calidad (QC) automatizado: La generación de informes HTML interactivos permite a los investigadores inspeccionar visualmente miles de ensayos y detectar anomalías antes del análisis estadístico, algo que rara vez se hace en la literatura actual.
• Escalabilidad: La integración con bases de datos (DuckDB) y formatos eficientes (Parquet) permite manejar estudios a gran escala con cientos o miles de participantes, superando las limitaciones de los archivos CSV tradicionales.
• Principios FAIR: El paquete está diseñado desde su concepción para cumplir con los principios de datos FAIR, facilitando la reutilización y la compartición de datos.

4. Resultados y Funcionalidades Demostradas

El artículo demuestra la capacidad de eyeris para transformar datos crudos de EyeLink en datos derivados listos para el análisis en pocas líneas de código.

• Eficiencia: Se muestra cómo un pipeline completo (desde la carga de datos crudos hasta la exportación de epocas y metadatos) se ejecuta en segundos.
• Diagnóstico: Se ilustran los gráficos interactivos que permiten comparar la señal antes y después de cada paso (ej. eliminación de parpadeos, filtrado), asegurando que los parámetros sean adecuados para cada conjunto de datos.
• Extracción de metadatos: Se demuestra la capacidad de extraer automáticamente variables experimentales (como el tipo de estímulo o el número de ensayo) directamente de las cadenas de mensajes de los eventos del rastreador ocular.
• Gestión de datos: Se valida el uso de la base de datos local para consultar y agregar datos de múltiples sujetos sin necesidad de scripts complejos de fusión de archivos.

5. Significado e Impacto

El lanzamiento de eyeris representa un avance significativo para la psicofisiología y las neurociencias cognitivas:

• Reproducibilidad: Al estandarizar los pasos de preprocesamiento y documentar automáticamente cada decisión y parámetro, el paquete mitiga el problema de los "caminos de bifurcación" y mejora la replicabilidad de los estudios de pupilarimetría.
• Accesibilidad: Democratiza el análisis de datos de alta calidad, permitiendo que investigadores con diferentes niveles de experiencia en programación realicen preprocesamientos robustos sin necesidad de escribir scripts complejos desde cero.
• Estándar de oro: Busca establecer un nuevo estándar para el campo, análogo al que fMRIPrep ha logrado para la resonancia magnética funcional, promoviendo prácticas de ciencia abierta y transparente.
• Futuro: Facilita la integración de la pupilarimetría en estudios multimodales (fMRI, EEG) y grandes estudios longitudinales, asegurando que los datos sean comparables y de alta fidelidad.

En resumen, eyeris no es solo una herramienta de software, sino un marco metodológico diseñado para elevar la calidad, transparencia y reproducibilidad de la investigación en pupilarimetría cognitiva.