labapi: a Python object model for the LabArchives electronic lab notebook

No laboratório moderno, a história de um experimento não é mais apenas um registro manuscrito em um livro encadernado em couro. É um registro digital, um arquivo vivo onde cada observação, cada cálculo e cada resultado deve ser arquivado com precisão. Para cientistas dos Institutos Nacionais de Saúde (NIH) e de muitas outras instituições de pesquisa, esse lar digital é um sistema chamado LabArchives. Ele funciona como um caderno eletrônico, um espaço seguro onde os pesquisadores documentam seu trabalho passo a passo, garantindo que a história de uma descoberta seja preservada junto com a própria descoberta. No entanto, surgiu uma lacuna entre a forma como os cientistas trabalham e a forma como esses cadernos digitais são construídos. Embora os pesquisadores dependam cada vez mais de programas de computador automatizados para processar dados — executando cálculos complexos que geram resultados em segundos — eles ainda precisam copiar e colar manualmente esses resultados no caderno por meio de um navegador web. É uma tarefa tediosa e repetitiva que interrompe o fluxo da ciência, forçando um humano a atuar como uma ponte entre um computador rápido e uma página web estática.

Para resolver esse atrito, uma equipe de pesquisadores desenvolveu uma nova ferramenta chamada labapi, uma biblioteca de software projetada para permitir que programas de computador falem a mesma língua que o caderno eletrônico. A conquista central deste trabalho é a criação de uma ponte que traduz os comandos técnicos e planos do sistema subjacente do caderno em uma estrutura que pareça natural para um usuário humano. Em vez de forçar um programa de computador a procurar códigos internos obscuros para encontrar uma página específica, a nova ferramenta permite que o programa navegue pelo caderno usando os mesmos camros familiares que uma pessoa usaria: movendo-se de um caderno, para uma pasta e descendo até uma página específica. Esta ferramenta não apenas move dados; ela entende a hierarquia do caderno, reconhecendo que uma pasta pode conter outras pastas ou páginas, e que as páginas contêm as entradas reais de dados. Ao construir essa estrutura, os autores permitiram que os pesquisadores criassem fluxos de trabalho automatizados que podem escrever seus resultados diretamente no caderno e lê-los de volta mais tarde sem qualquer intervenção humana.

Os desenvolvedores projetaram esta ferramenta com um objetivo específico: fazer com que o caderno digital pareça tão intuitivo quanto a interface web que os cientistas já conhecem. No passado, conectar um programa de computador ao caderno exigia a escrita de código personalizado para traduzir um caminho simples, como "Projeto A/Resultados/Sujeito 1", em uma série complexa de requisições internas. A nova biblioteca lida com essa tradução automaticamente. Ela inclui auxiliares que podem verificar se uma pasta existe e criá-la caso esteja faltando, ou encontrar uma página específica sem precisar conhecer seu ID interno oculto. Essa abordagem segue o princípio de "analisar, não validar" (parse, don't validate), o que significa que o software aceita o caminho conforme o usuário o digita e descobre os detalhes, em vez de forçar o usuário a se conformar a uma estrutura rígida e pré-definida. Essa flexibilidade permite que o software crie novas entradas, como salvar um arquivo de dados complexo como um anexo JSON, que então aparece no caderno com uma visualização formatada que os humanos podem ler facilmente.

O valor prático desta ferramenta já está sendo sentido na pesquisa do mundo real. Os autores a utilizaram para construir duas aplicações específicas que já estão em uso por outros laboratórios. Uma aplicação, chamada muronto, registra automaticamente as saídas de experimentos neurocomportamentais, capturando dados que de outra forma exigiriam entrada manual. Outra, chamada save-my-jupyter, tira instantâneos de notebooks Jupyter — um formato comum de codificação científica — e os deposita diretamente no registro eletrônico. Em uma demonstração das capacidades da ferramenta, os autores mostraram como um fluxo de trabalho poderia pegar dados de cinco sujeitos diferentes, calcular um valor de controle de qualidade para cada um e escrever esses resultados no caderno. O sistema então leu esses valores salvos, resumiu-os em um relatório de coorte e anexou uma figura visual à mesma página. Tudo isso aconteceu automaticamente, com o computador navegando pela estrutura do caderno como se um humano estivesse clicando pelos menus.

Este trabalho aborda uma necessidade específica dentro da comunidade científica, particularmente para instituições que são obrigadas a usar cadernos eletrônicos aprovados para suas pesquisas. Embora outros sistemas para cadernos eletrônicos de laboratório possuam bibliotecas de software oficiais para ajudar na automação, o LabArchives não fornece uma publicamente. Tentativas anteriores de construir uma conexão com o sistema foram incompletas, sem manutenção ou exigiam que os pesquisadores construíssem todo o sistema de navegação do zero. A nova biblioteca preenche essa lacuna, oferecendo uma ferramenta de propósito geral que combina navegação de caminho, manipulação de entradas e transferência de arquivos em um único pacote. Ela é projetada para ser usada por pesquisadores computacionais e desenvolvedores de software que trabalham ao lado de laboratórios experimentais, fornecendo-lhes uma maneira confiável de manter seus registros digitais atualizados.

A ferramenta está agora disponível para qualquer pessoa usar, com seu código-fonte e documentação publicados abertamente. Ela requer uma versão moderna da linguagem de programação Python para rodar e é lançada sob uma licença que permite amplo uso e modificação. Os desenvolvedos incluíram exemplos e testes para ajudar outros a começar, garantindo que o caminho de um arquivo de dados bruto para um registro de laboratório permanente não seja mais uma tarefa manual, mas uma parte contínua do processo científico. Ao remover a barreira entre a análise automatizada e o caderno eletrônico, esta ferramenta permite que os cientistas foquem mais nas perguntas que estão fazendo e menos na mecânica de arquivar suas respostas.