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

Este artigo apresenta o *eyeris*, um pacote R de código aberto que oferece um framework modular, transparente e reprodutível para o pré-processamento de dados de pupilometria, preenchendo a lacuna de padronização na área ao adotar princípios FAIR e fornecer relatórios interativos de controle de qualidade.

O essencial

Imagine que os olhos são janelas para a mente. Há muito tempo, os cientistas sabem que o tamanho da nossa pupila (aquela parte preta no centro do olho) muda não só com a luz, mas também quando estamos pensando, estressados, cansados ou muito focados. É como se a pupila fosse um "termômetro" invisível que mede o quanto nosso cérebro está trabalhando.

No entanto, medir essas mudanças é complicado. Os dados brutos que vêm das câmeras que rastreiam os olhos são como um rio cheio de pedras, folhas e sujeira. Antes de poder estudar a água, você precisa limpá-la.

Aqui é onde entra o eyeris.

O Problema: Um Quebra-Cabeça Sem Instruções

Antes deste trabalho, cada cientista que estudava as pupilas tinha que inventar sua própria maneira de limpar os dados. Era como se cada cozinheiro no mundo tivesse uma receita diferente para fazer o mesmo bolo: um usava 3 ovos, outro 4; um misturava rápido, outro devagar. O resultado? Ninguém sabia se o bolo do vizinho era bom ou ruim, e era difícil comparar os resultados.

Além disso, muitos cientistas não são programadores experts. Eles sabiam muito sobre psicologia, mas não sabiam como escrever o código complexo para limpar os dados corretamente. Isso levava a erros, resultados confusos e dificuldade em repetir os experimentos (reprodutibilidade).

A Solução: O "eyeris" (O Olho de Águia)

Os autores criaram o eyeris (que soa como "iris", a parte colorida do olho, mas também lembra "águia", que tem uma visão muito aguçada). Pense no eyeris como um robô chef de cozinha ou um filtro de água superinteligente pronto para uso.

Aqui está como ele funciona, usando analogias simples:

1. A "Caixa de Vidro" (Glassbox):
   Muitos programas de computador são "caixas pretas": você joga os dados dentro e espera um resultado mágico, sem saber o que aconteceu lá dentro. O eyeris é uma caixa de vidro. Você vê exatamente cada passo que o robô dá. Ele mostra: "Agora estou removendo o piscar de olhos", "Agora estou limpando um erro de leitura", "Agora estou suavizando o sinal". Isso gera confiança.

2. O Passo a Passo Obrigatório (Mas Flexível):
   O eyeris segue uma receita padrão que os cientistas concordaram ser a melhor:

   • Remover o "Piscar": Quando você pisca, a câmera perde o sinal. O eyeris preenche esses buracos de forma inteligente, como um restaurador de fotos que preenche partes faltantes de uma imagem antiga.
   • Cortar os "Picos": Às vezes, a cabeça se move e a pupila parece pular de tamanho. O eyeris identifica esses picos estranhos e os remove.
   • Suavizar o Som: O sinal tem muito ruído (como estática no rádio). O eyeris aplica um filtro que deixa apenas a música (o sinal real do cérebro), removendo a estática.
   • Normalizar: Como os olhos de cada pessoa são diferentes (alguns têm pupilas maiores, outros menores), o eyeris ajusta tudo para uma escala comum, como se todos os alunos de uma turma fossem comparados pela nota relativa, e não pela altura absoluta.

3. O Relatório de Qualidade (O "Check-up"):
   Após processar os dados, o eyeris não apenas entrega o resultado, mas gera um relatório interativo e colorido. É como um laudo médico detalhado que mostra, passo a passo, como os dados estavam antes e depois da limpeza. Isso permite que o cientista veja se algo deu errado em um único teste e decida se deve descartá-lo, sem precisar jogar fora todo o experimento.

4. Organização de Arquivos (BIDS):
   O eyeris organiza todos os arquivos de forma padronizada, como se fosse uma biblioteca onde cada livro tem seu lugar exato na prateleira. Isso facilita que qualquer pessoa, em qualquer lugar do mundo, pegue os dados e entenda o que foi feito.

Por que isso é importante?

O eyeris é como ter um manual de instruções universal para estudar a mente através dos olhos.

• Para iniciantes: É fácil de usar. Basta clicar e rodar.
• Para experts: É flexível. Eles podem mudar os parâmetros se quiserem.
• Para a ciência: Garante que todos estejam falando a mesma língua. Se um cientista no Brasil e outro no Japão usarem o eyeris, eles saberão que estão comparando "maçãs com maçãs", e não "maçãs com laranjas".

Em resumo, o eyeris transforma um processo bagunçado e cheio de erros em algo limpo, transparente e confiável, permitindo que os cientistas se concentrem no que realmente importa: descobrir como nossa mente funciona, em vez de perder tempo limpando dados.

Resumo técnico

Resumo Técnico: eyeris – Um Framework de Pré-processamento de Pupilometria em R

1. O Problema

A pupilometria (medição do tamanho da pupila) é uma ferramenta não invasiva crucial para investigar processos cognitivos e autonômicos, como atenção, esforço mental, estresse e estados emocionais, além de servir como um indicador indireto da atividade neuromoduladora do locus coeruleus-noradrenérgico (LC-NA).

Apesar da sua utilidade, a pesquisa em pupilometria enfrenta uma lacuna crítica: a falta de um framework de pré-processamento padronizado, robusto e reprodutível.

• Falta de Padronização: Diferente de outras modalidades de neuroimagem (como fMRI com fMRIPrep ou EEG com EEGLAB e MNE-Python), não existe um fluxo de trabalho consensual para pupilometria.
• Risco de Viés: A ausência de diretrizes prescritas leva ao "jardim de caminhos que se bifurcam" (garden of forking paths), onde pequenas decisões arbitrárias no pré-processamento (ex: filtragem, tratamento de artefatos) podem alterar drasticamente os resultados e levar a falsos positivos.
• Ferramentas Existentes Insuficientes: Pacotes atuais muitas vezes são rígidos, não seguem princípios FAIR (Findability, Accessibility, Interoperability, Reusability), carecem de relatórios de qualidade de dados interativos ou exigem que os pesquisadores escrevam scripts complexos do zero, aumentando o risco de erros de programação e falta de transparência.

2. Metodologia: O Pacote eyeris

Os autores desenvolveram o eyeris, um pacote de software de código aberto em R, projetado para ser intuitivo, modular, performático e extensível. A metodologia central baseia-se em um pipeline de "caixa de vidro" (glass-box), em contraste com abordagens de "caixa preta".

Principais Componentes e Funcionalidades:

• Função de Entrada Principal (glassbox()):

  • Oferece um pipeline de pré-processamento completo e prescritivo, executando etapas em uma ordem específica e crítica para evitar modificações indesejadas nos dados.
  • Opera em dois modos: Interativo (permite ao usuário visualizar e ajustar parâmetros passo a passo) e Headless (automatizado para grandes conjuntos de dados em clusters de computação).
  • Permite a sobrescrita de parâmetros padrão, mantendo a transparência.

• Sequência de Pré-processamento Prescrita:

  1. Carregamento (load_asc): Parseia arquivos .asc do EyeLink, lidando automaticamente com múltiplos blocos e dados binoculares.
  2. Remoção de Piscadas (deblink): Remove artefatos de piscadas preenchendo com NA e estendendo a área de exclusão (padrão: 50ms) para cobrir artefatos de oclusão parcial.
  3. Remoção de Transientes (detransient): Identifica picos não fisiológicos (movimentos bruscos, perda de rastreamento) usando um limiar baseado na Desvio Absoluto Mediano (MAD) da velocidade da pupila.
  4. Interpolação (interpolate): Preenche os dados ausentes (de piscadas e transientes) usando interpolação linear, adequada para a dinâmica lenta da pupila.
  5. Filtragem (lpfilt): Aplica um filtro Butterworth de baixa frequência (corte de passagem em 4 Hz) para suavizar ruído de alta frequência.
  6. Redução de Amostragem (downsample) ou Binning (bin): Reduz a frequência de amostragem preservando a dinâmica temporal, com filtros anti-aliasing automáticos.
  7. Detrending (detrend): Opcional. Remove tendências lineares lentas (efeito "tempo na tarefa"), mas é desativado por padrão para preservar níveis de tônus arousal.
  8. Padronização (zscore): Normaliza os dados (média 0, desvio padrão 1) para permitir a comparação entre sujeitos e sessões, focando na dinâmica relativa em vez do tamanho absoluto.

• Extração de Épocas e Metadados (epoch):

  • Inspirado no EEGLAB, permite a extração flexível de épocas baseadas em mensagens de eventos.
  • Suporta expressões regulares e sintaxe de chaves (ex: PROBE_{trial}_{stimulus}) para extrair automaticamente metadados das strings de eventos para o dataframe final.

• Armazenamento e Visualização:

  • Relatórios Interativos: Gera automaticamente relatórios HTML com gráficos diagnósticos para cada etapa do pipeline, permitindo controle de qualidade (QC) nível de tentativa.
  • Estrutura BIDS-like: Organiza os dados derivados em uma estrutura de diretórios padronizada, facilitando o compartilhamento.
  • Banco de Dados Integrado: Utiliza DuckDB para armazenar dados pré-processados em um único arquivo (.eyerisdb), permitindo consultas SQL eficientes e gerenciamento escalável de grandes conjuntos de dados sem a sobrecarga de milhares de arquivos CSV.

3. Contribuições Chave

1. Padronização Prescritiva: Oferece um fluxo de trabalho "opinionado" (prescritivo) que reduz a variabilidade analítica e o risco de erros, estabelecendo melhores práticas para a comunidade.
2. Transparência Total ("Glass-Box"): Ao contrário de ferramentas que escondem o processamento, o eyeris expõe cada passo, parâmetro e sua consequência visual, permitindo que pesquisadores novatos e experientes inspecionem e validem os dados.
3. Escalabilidade e FAIR: A integração com DuckDB e a estrutura BIDS-like tornam o gerenciamento de grandes estudos (centenas de participantes) viável e alinhado com os princípios de Ciência Aberta e FAIR.
4. Extensibilidade: O design modular permite que desenvolvedores criem funções personalizadas que se integram nativamente ao pipeline, mantendo a rastreabilidade e a compatibilidade.

4. Resultados e Funcionalidades Demonstradas

O artigo demonstra que o eyeris permite transformar dados brutos de pupilometria em dados prontos para análise estatística com apenas três linhas de código (usando glassbox()).

• Diagnóstico Automatizado: Os relatórios gerados capturam a proveniência dos dados (histórico de processamento), permitindo que pesquisadores identifiquem e removam tentativas ruins sem excluir participantes inteiros, aumentando o poder estatístico.
• Flexibilidade de Metadados: A capacidade de extrair metadados complexos diretamente das strings de eventos do rastreador simplifica a vinculação de dados fisiológicos a comportamentais.
• Gerenciamento de Dados: A solução de banco de dados resolve gargalos de I/O (entrada/saída) comuns em estudos de grande escala, permitindo consultas rápidas e exportação em formatos eficientes (Parquet).

5. Significado e Impacto

O eyeris preenche uma lacuna crítica na neurociência cognitiva, elevando o padrão de reprodutibilidade na pesquisa de pupilometria para um nível comparável ao de outras modalidades de neuroimagem.

• Reprodutibilidade: Ao fornecer um pipeline transparente e padronizado, reduz a ambiguidade nas análises e facilita a replicação de estudos.
• Acessibilidade: Democratiza o pré-processamento de alta qualidade, permitindo que pesquisadores sem profundo conhecimento em engenharia de software possam realizar análises rigorosas.
• Futuro da Pesquisa: Ao integrar controle de qualidade visual, armazenamento escalável e conformidade com FAIR, o eyeris posiciona a pupilometria como uma ferramenta mais robusta para investigar mecanismos cognitivos, envelhecimento e doenças neurodegenerativas (como Alzheimer, através da via LC-NA).

Em suma, o eyeris não é apenas uma ferramenta de software, mas uma iniciativa metodológica para consolidar as melhores práticas de processamento de sinais em pupilometria, promovendo ciência mais aberta, transparente e confiável.