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

34

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:

y=(y1,...,yn)

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.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.

Geoff Oxberry
fonte

Respostas:

14

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.
cboettig
fonte
Carl, eu acompanho o seu site há um tempo, e sua abordagem com o knitr foi uma das inspirações para a minha pergunta. Também acompanho o dexy há um tempo, porque Zed Shaw o usa para criar a fonte de seu livro How To Learn Python the Hard Way (consulte o repositório git ). O que eu gosto no dexy, em oposição a outras abordagens de programação alfabética, é que o código e o texto são fracamente acoplados, permitindo o uso sensato de um depurador.
precisa
Geoff, legal, obrigado pelos comentários! Anna Nelson também acredita muito na dissociação. Usuários R podem realizar o desacoplamento no knitr com externalização de código ou a nova spin()função. Pessoalmente, acho que as queixas de Greg Wilson sobre programação alfabetizada são bastante antigas. Eu tive a mesma experiência terrível que ele descreve com o noweb, mas essa depuração complicada simplesmente não existe nas ferramentas modernas. Para IC alfabetizado, use doxygen. Knitr é, se algo mais fácil de depurar do que R, graças ao armazenamento em cache e manipulação de ambiente.
cboettig
20

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

aterrel
fonte
Na mesma linha, há sweave , que não é algo que eu uso, mas é intrigante em conceito.
precisa
O Projeto Madagascar parecia interessante quando ouvi uma palestra de um de seus autores. Na verdade, eu ainda não tentei usá-lo.
Ken
@dmckee: Conheço pessoas que tiveram um bom sucesso com sweave e knitr . Eu desconfio das abordagens de programação alfabetizada pelas mesmas razões que Greg Wilson cita no Software Carpentry : o papel e o código estão muito acoplados, o que dificulta a execução de um depurador no código (e pode atrapalhar a verificação) o texto).
precisa
Eu uso o Sweave para esse fim, ele funciona muito bem e é compatível com o Lyx. O modo organizacional é ainda melhor e suporta os idiomas mais comuns.
David LeBauer
13

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.

Nathan Collier
fonte
1
Eu já faço esse tipo de coisa para figuras. No entanto, nos trabalhos que estou escrevendo, as tabelas seriam um formato não natural para apresentar os dados. Muitas vezes, quero apenas incluir a condição inicial em uma ODE (algo como 4-6 números, espaçados por vírgulas) ou uma matriz inteira de números como parte do lado direito de uma equação. Eu gosto da sua ideia para mesas. Para os casos que mencionei, acho que reformatá-los como tabelas não seria natural e gostaria de incluir os dados em um formato mais natural.
amigos estão dizendo sobre geoff
Nathan, você se importaria de postar exemplos? Eu uso a mesma abordagem, exceto que eu comprometo os arquivos de texto no git e uso o git para gerenciar os resultados. Em seguida, tenho scripts Python para produzir gráficos / tabelas. Eu tenho um script por enredo ou tabela.
Ondřej Čertík
Você também pode canalizar a saída de um script shell diretamente ao látex usando o comando \input{|"path-to-script.py"}. Eu acho melhor você colocar todos os parâmetros em um único arquivo python (ou qualquer que seja o idioma que você mais goste) e usar o parâmetro de linha de comando para acessá-lo dessa maneira \input{|"path-to-script.py param-name"}. Nesse caso, você pode incluir o arquivo param em outros scripts para executar as simulações. No entanto, torna a compilação mais lenta e possui outros pontos negativos.
Helium
7

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).

David Ketcheson
fonte
Já fiz isso antes (para minha própria sanidade) e, felizmente, valeu a pena quando meu consultor me pediu para gerar novamente e verificar novamente os resultados. Desde então, mudei para apenas descarregar o código-fonte de um script que executa tudo em um apêndice dos meus rascunhos para que ele esteja lá, eu sei o que fiz e posso clicar em um botão para obter todos os números e figuras.
precisa
O script não faz nenhuma instalação no momento, porque é apenas um script do MATLAB. Na documentação da função, ele lista dependências em pacotes de terceiros. Esses pacotes de terceiros, por sua vez, possuem documentação clara sobre como instalá-los (e, felizmente, também são ativamente suportados, têm ótimos desenvolvedores e listas de discussão ativas).
precisa
6

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.

Robert
fonte
Eu gosto do modo org; Eu o uso para esboços. Eu não usei com Babel. Vou ter que experimentar.
precisa
Aqui está uma excelente visão geral de janeiro de 2012 J. Stat. Software jstatsoft.org/v46/i03/paper
David LeBauer
Eu escrevi um tutorial que mostra como converter o modelo LaTeX do European Physical Journal A (EPJ A) em um arquivo de modo organizacional.
Melioratus
4

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.

MRocklin
fonte
Meu primeiro pensamento quando escrevi essa pergunta foi uma solução parecida com a que você propôs. Eu estava originalmente pensando em algo de baixa tecnologia, como usar um pré-processador de macro, mas o Python é provavelmente uma abordagem melhor (e certamente mais legível); então, um sistema de construção pode lidar com a regeneração incremental de resultados.
Geoff Oxberry
Realmente esta é apenas uma implementação muito básica de algo como páginas de servidor python. A idéia de conteúdo gerado automaticamente existe na comunidade da web há algum tempo. Seria bom vê-lo migrar para a academia.
21312 MRocklin
Acordado. O Jinja2 pode ser usado para fazer o que você sugeriu. De fato, é isso que o dexy faz, mas com vários filtros legais que também lidam com destaque de sintaxe e outras tarefas diversas.
amigos estão dizendo sobre geoff
4

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.

Aesin
fonte
2

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 .

Hylke Koers
fonte
O segundo link é para a coisa errada.
David Ketcheson
@Hylke Koers: Você quis colocar este link: collage.elsevier.com ?
Paul
@Paul: eu fiz as edições; o segundo link original era para o Grupo Google do Collage. Talvez um link melhor fosse o próprio Collage, mas meu foco era tentar (principalmente) preservar as boas intenções do post e remover as partes que o tornavam promocional. Sinta-se à vontade para editar a postagem como achar melhor.
precisa