Como garantir que os resultados das minhas simulações e os resultados do meu artigo estejam sempre sincronizados?

Em um dos meus trabalhos, listo alguns resultados numéricos, além de algumas figuras. O que eu gostaria de fazer é garantir que os resultados numéricos no meu artigo sempre estejam de acordo com o código. No momento, apenas copio diretamente os resultados numéricos da minha saída de simulação para o papel, o que é extremamente simples e de baixa tecnologia, mas propenso a erros, porque eu poderia copiar incorretamente os resultados ou esquecer de sincronizar os resultados do papel com o saída de código.

Existe uma boa maneira de manter os resultados numéricos citados em meus artigos em sincronia com os resultados gerados pelo meu código? (Suponho que a execução do código seja fácil e prática sempre que eu quiser atualizar meu artigo.) Esses resultados numéricos não se prestam necessariamente à forma de tabela. Às vezes, tenho tabelas em manuscritos, mas, mais comumente, tenho parâmetros de simulação listados como números em equações . Um exemplo seria algo como:

onde gostaria de substituir os elementos da condição inicial pelos parâmetros reais que utilizo em uma simulação que integra numericamente um sistema de equações diferenciais ordinárias. Usar uma tabela para dados pontuais, como este exemplo, parece um exagero e mais tinta do que o necessário.$\mathbf{y}^{*}$

Presumo que os números sejam um caso mais fácil: sempre que o documento for "construído" (da fonte do LaTeX, Markdown, RST etc.), inicie o processo de criação executando o código. No entanto, se as pessoas tiverem melhores sugestões para manter os números gerados pelas minhas simulações sincronizados com o meu artigo, eu adoraria ouvi-los.

Como alguns comentários sugeriram, essa abordagem foi desenvolvida há muito tempo na comunidade R, desenvolvendo Sweavee mais recentemente knitr. Obviamente, essa abordagem tem a desvantagem de ser específica de idioma no momento, mas a vantagem de ser usada regularmente em trabalhos acadêmicos.

Uso do Sweave em publicações reais

• O Journal of Biostatistics incentiva esses envios e coloca uma letra de pipa "R" em trabalhos acadêmicos nos quais o editor de reprodutibilidade conseguiu executar o código e os dados e obter esses resultados.
• Essencialmente, todas as publicações no R-Journal são construídas no Sweave.

É claro que os usuários Sweave / knitr geralmente enviam apenas o resultado final para a maioria dos periódicos, com a confiança pessoal de que os métodos realmente reproduzem os resultados. Da mesma forma, o sweave é frequentemente usado para criar slides para palestras profissionais, etc.

Funcionalidades úteis

Para ser útil na prática, esse sistema deve ter certos recursos. Com uma massa crítica de usuários, muitos deles são bem desenvolvidos knitr. Alguns destaques:

• Armazenamento em cache. A gravação em um formato como markdown ou latex que deve ser compilado para ver a saída torna isso impossível, incluindo o código quando os resultados não podem ser armazenados em cache. O armazenamento em cache inteligente na knitrverdade torna a depuração de código intensivo muito mais fácil do que trabalhar em puro R, pois não é necessário executar novamente os blocos bem-sucedidos.

• Alterna a exibição do código. Em uma publicação formal, talvez você não queira que nenhum código subjacente seja visível na saída. Enquanto isso, geralmente é valioso mostrar o código (bem formatado, com destaque para sintaxe) que produz os resultados no formato de saída quando você deseja que o leitor veja exatamente o que está digitando.

• Comunidade. Talvez a vantagem mais atraente dessa abordagem em relação a uma solução caseira seja o número de pessoas familiarizadas com o modelo e tentando melhorá-lo.

• Muitos exemplos interessantes de outros recursos podem ser encontrados nas demos das páginas da web do knitr , incluindo ferramentas para "publicação leve" ou compartilhamento na web. Muitos desses recursos ajudam a tornar essa abordagem mais compatível com o fluxo de trabalho geral de alguém, em vez de algo a ser feito apenas ao escrever o manuscrito.

Nota de rodapé histórica.

Embora esteja enraizada na "programação alfabética" de Knuth, como o nome sugere, a ênfase é bem diferente, pois a programação alfabética se concentra na conexão de código e documentação de software (na comunidade R em que o papel é desempenhado Roxygen, que segue suas raízes para um ramo diferente de a "árvore de programação alfabetizada").

Indo além

Em princípio, podemos pedir muito mais a partir de um documento dinâmico, como a capacidade do leitor de alterar as entradas e ver as saídas sem precisar editar e recompilar o documento inteiro, por exemplo, usando uma plataforma on-line interativa. XDynDocs pode ser um passo nessa direção.

Outras abordagens

• Pode querer ficar de olho no dexy.it
• Em uma abordagem um pouco diferente: Um número crescente de documentos econômicos hospeda códigos associados a publicações em http://www.runmycode.org/ , que executarão novamente as análises na nuvem e permitirão parâmetros de entrada personalizados ou dados de entrada personalizados.

O que você está pedindo é o grande desafio da Elsivier do "Documento executável" . Embora muitas abordagens tenham sido tentadas, nenhuma é tão convincente quanto os autores podem sugerir. Aqui estão alguns exemplos de técnicas usadas.

O Projeto Madagascar adota sua abordagem, dentro do script make são executadas as simulações que produzem as figuras e o papel simultaneamente.

O IPython Notebook fornece um documento que você pode executar enquanto lê e produz figuras para o conteúdo do seu coração. (Vi plugins de palavras, Mathematica e várias outras soluções usadas da mesma maneira)

O VisTrails usa uma abordagem de arquitetura orientada a serviços e fornece um gerenciador de "providência" ou "fluxo de trabalho". Basicamente, você registra ganchos no código e cria um fluxo de trabalho ou experimento que reproduz seu trabalho. Ele foi usado em muitos tipos de códigos, mesmo em clusters HPC. Com essa abordagem, você terá uma maneira de reproduzir os experimentos.

Existem toneladas desse tipo de soluções por aí, mas essas três ficaram impressionadas. É um problema difícil e acredito que realmente não estamos nem perto de resolver. Não podemos nem levar as pessoas a liberar seu código com seus papéis, como podemos esperar que elas reproduzam os resultados = P

Não tive muito sucesso ao usar as soluções de outras pessoas para esse problema. Normalmente, eu só quero algo simples que funcione para mim e faça o trabalho. Para esse fim, geralmente tento escrever um script python encarregado de executar todos os resultados, analisar a saída e criar as figuras / tabelas.

Escrevo meus códigos para gerar arquivos de dados que contêm os resultados em algum formato de texto. Você pode evitar executar novamente esses resultados em seu script testando primeiro a existência do arquivo de saída (em python, usando os.path.isfile () por exemplo). Se você deseja executar novamente seus resultados, basta remover os arquivos de dados. Se os arquivos de dados existirem, eu executo um analisador desses arquivos. Para isso, o módulo python para expressões regulares é muito útil (re).

A partir da saída analisada, crio as figuras ou tabelas. Para tabelas em látex, você pode escrever o código para gerar a tabela em um arquivo separado (eu uso uma extensão .tbl) e incluí-la no seu arquivo de látex. A chave para mim é usar um script python. Se tenho muitos, mais tarde me pergunto qual é qual e o que eles fazem. Se essa descrição for muito vaga, posso enviar alguns exemplos.

Ainda mais importante, na minha opinião, é garantir que você possa descobrir como gerar novamente todos os seus resultados a partir do zero em um mês ou um ano (por exemplo, quando os árbitros pedem que você adicione ou modifique algo). Para isso, o que faço é incluir um arquivo de texto com instruções muito detalhadas sobre como reproduzir todos os resultados. É melhor se você testá-las fazendo com que outra pessoa (como um co-autor) as experimente. Eu recomendo que você também forneça essas instruções (e todo o seu código) para árbitros e leitores.

Aqui está um exemplo (realmente preparado por meu co-autor, Aron Ahmadia).

O orgmode do Emacs em combinação com Babel alcança isso. O Babel pode executar trechos de código de várias linguagens de programação e script, por exemplo, ele pode abrir o arquivo que contém os dados da simulação e colocá-lo em uma tabela no modo orgânico, que pode ser exportado para o LaTeX (e muitos outros formatos). Demora um pouco para se acostumar com todos os combos de teclas no modo org, mas, uma vez executado, tudo é automático.

Se executar todo o seu código for barato, você poderá fazer algo de baixa tecnologia, como o seguinte:

Você pode modelar seus documentos com seqüências de caracteres formatadas para que elas se pareçam com isso

"we observed a %(fractional_improvement)s increase in ..."

Tenha scripts python que se parecem com isso

results = {"alpha"                  : run_alpha_computation(...),
           "fractional_improvement" : run_fi_computation(...), 
           ...}

E então faça algo assim

for fn in filenames:
    file = open(fn);      s = file.read();       file.close()
    file = open(fn, 'w'); file.write(s%results); file.close()

Você pode então encerrar isso em um Makefile.

Se você estiver usando o LaTeX, uma solução relativamente de baixa tecnologia é fazer com que seu código cuspa um arquivo (ou use um script para filtrar a saída do código) contendo um monte de linhas como esta:

\newcommand{\myresults1}{<value>}

Em seguida, você pode usar o \inputcomando para adicionar esse arquivo ao seu documento e usar os comandos definidos para colocar os valores.

Eu trabalho para a Elsevier. Minha empresa começou a usar a estrutura Collage (desenvolvida em resposta ao Executable Paper Grand Challenge) em edições de periódicos para permitir que os autores publiquem partes do código executável em seus artigos. Esse recurso facilita a reprodução dos resultados relatados no artigo e a reutilização do material publicado para sua própria pesquisa. O Collage suporta uma ampla variedade de software proprietário e de código aberto; mais informações podem ser encontradas no vídeo informativo aqui e no site do ambiente de criação de colagens .