Qual seria a maneira mais útil de escrever código para um artigo, para que os leitores possam combinar claramente os resultados com o código que os gera?

Estou escrevendo um artigo reproduzível, e o artigo tem resultados computacionais gerados por um script Python (um script MATLAB semelhante gera resultados quase idênticos). Eu acho que o artigo seria mais fácil de entender para os leitores se eles pudessem combinar os cálculos no papel com os cálculos no código. O trabalho propõe um formalismo abstrato, e os exemplos no artigo devem tornar esse formalismo mais concreto para os leitores (muitos dos quais serão engenheiros); o código provavelmente será o registro mais detalhado de como executar os cálculos, e deixar claro pode nos ajudar durante o processo de revisão.

Alguém tem alguma sugestão de como tornar mais clara a correspondência entre código e resultados computacionais (figuras, equações)?

Por exemplo, eu estava pensando que quando se tratava de linhas de código implementando várias etapas do artigo, eu poderia citar números de equações (seria incrível se eu pudesse cruzar a referência entre o código e o LaTeX, mas rotulá-los à mão é bom) , e eu poderia escrever funções correspondentes aos vários exemplos e figuras, como

def example_1():
    # Insert code corresponding to first example
    pass

def figure_1():
    # Insert code that generates Figure 1
    pass

Se o código fosse grande e eu não estivesse tentando explicar como vários métodos matemáticos usados ​​na engenharia eram realmente os mesmos, provavelmente não me incomodaria muito em tornar o código claro, mas, dada a natureza abstrata do papel e a pequena base de código, parece que poderia haver valor neste exercício.

1. Você pode escrever o artigo inteiro no Noweb . É um pouco tedioso de configurar, mas é uma maneira muito poderosa de misturar código, texto, equações e figuras no formato LaTeX. Para programas longos, ele tende a transformar seu código em mais um livro do que em um artigo, mas para programas curtos, pode funcionar muito bem.

2. Se você não deseja ir tão longe, ainda deve ser razoavelmente simples formatar as seções de comentários de suas listagens de código usando o LaTeX. O listingspacote pode ajudá-lo a fazer isso. Aqui está um pequeno exemplo:

\ documentclass {article}
\ usepackage {amsmath}
\ usepackage {listagens}
\ begin {document}
\ begin {equation}
  \ label {eq: one}
  Ax = b
\ end {equação}
\ begin {lstlisting} [escapeechar = \%]
  # Comentário com uma referência à Equação% ~ \ eqref {eq: one}%
  def f (a):
    retornar um + 1
\ end {lstlisting}
\ end {document}

Com algumas manipulações adicionais, você deve conseguir que seus números de equações referenciados apareçam na fonte monoespaçada usada para listar a equação.

A abordagem noweb mencionada por Bill evoluiu bastante, tanto em seu espírito original de documentar código (em vez de publicação científica) sob o termo programação alfabetizada e agora vem em vários sabores (acho que noweb foi uma generalização da cweb inicialmente), de que doxygene várias versões específicas de idiomas podem gerar documentação em TeX, HTML e outros formatos.

Mais ao seu ponto, noweb foi desenvolvido há algum tempo na Rcomunidade (bem originalmente a Scomunidade, daí o nome) sob o título "Sweave", com o objetivo de fornecer um documento de "pesquisa reproduzível", onde o código é realmente executado quando o arquivo de látex é compilado (e opcionalmente exibido também). Muitos artigos acadêmicos são escritos em Sweave (incluindo, acredito, todo o periódico R; mas veja também o jornal de bioestatística e sua política sobre artigos reproduzíveis).

Enquanto o Sweave ainda faz parte de qualquer instalação básica do R, ele está sendo substituído pelo knitr, que agora é independente da linguagem , tornando-o uma opção possível para o seu código python. Knitr suporta gravação em LaTeX ou markdown, suportando destaque de sintaxe, armazenamento em cache, externalização do código a partir do látex de origem e muitos outros recursos desejáveis ​​para esse tipo de trabalho.

O Python possui soluções próprias que são similares, notebooks ipython , que podem renderizar para HTML, talvez LaTeX, mas eu sei menos sobre isso.

Outro projeto que definitivamente merece ser visto é o dexyit , outro programa independente de idioma que funciona muito bem com LaTeX e HTML. Embora tenha mais exemplos de documentação de códigos do que de artigos científicos, trabalhar no LaTeX deve ser direto.

Ambos knitre dexyitvai fazer exatamente o que você descreve no LaTeX, incluindo apontando para script python externo e ler no código. Coisas semelhantes podem ser realizadas no DocBook e XML, embora eu esteja menos familiarizado com essa abordagem.

O pacote LaTeX cunhado fornece realce de sintaxe muito extenso (baseado em pigmentos) e permite referências cruzadas em ambas as direções. Você pode escapar para o LaTeX de dentro da parte do código (a parte cunhada) e pode consultar no texto principal as linhas de código. Além disso, ele fornece um ambiente de listagem para que você possa gerar uma "lista de listagens" (como uma lista de tabelas) e permite fazer referência a listagens inteiras. Veja LaTeX MWE e sua saída com LuaLaTeX abaixo (não julgue o código :-)).

Outra opção seria usar o PythonTeX do mesmo autor / mantenedor, o que permite executar os cálculos enquanto compila a fonte do LaTeX; portanto, os resultados de papel e código são sempre gerados juntos e, portanto, sempre coerentes. Veja a galeria do PythonTeX aqui.

\documentclass[a4paper,notitlepage,11pt]{article}

\usepackage{amsmath}
\usepackage{cases}
\usepackage{minted}

\begin{document}

The mathematical definition of the Fibonacci
series is given in~Equations~(\ref{eq:fibdef:init1}--\ref{eq:fibdef:rule})
It can be implemented using either a recursive or iterative algorithm
in Python.

\begin{numcases}{f(n)=}
  \label{eq:fibdef}
    0               & n = 0 \label{eq:fibdef:init1}\\
    1               & n = 1 \label{eq:fibdef:init2}\\
    f(n-1) + f(n-2) & \text{otherwise} \label{eq:fibdef:rule}
\end{numcases}

The algorithms below are an implementation of both variants.
Listing~\ref{alg:fib_recursive} shows the recursive variant (see
line~\ref{alg:fibo_rec:line_rec} in listing~\ref{alg:fib_recursive}) while
listing~\ref{alg:fib_iterative} shows the iterative variant. Both can be
optimized, of course.

\begin{listing}[ht]
  \begin{minted}[linenos, escapeinside=||]{python}
def fibo_rec(N):
    if N == 0:
        result = 1 |[Comment: See case (\ref{eq:fibdef:init1})]|
    elif N == 1:
        result = 1 |[Comment: See case (\ref{eq:fibdef:init2})]|
    else:
        result = fibo_rec(N-1) + fibo_rec(N-2) |\label{alg:fibo_rec:line_rec}[Comment: See case (\ref{eq:fibdef:rule})]|

    return result
  \end{minted}
\caption{Fibonacci recursive}
\label{alg:fib_recursive}
\end{listing}

\begin{listing}[ht]
  \begin{minted}[linenos, escapeinside=||]{python}
def fibo_iter(N):
    if N == 0:
        fib_N = 1
    elif N == 1:
        fib_N = 1
    else:
        fib_Nmin2 = 1
        fib_Nmin1 = 1
        for i in range(2,N+1):
            fib_N = fib_Nmin2 + fib_Nmin1
            fib_Nmin2 = fib_Nmin1
            fib_Nmin1 = fib_N
    return fib_N
  \end{minted}
\caption{Fibonacci iterative}
\label{alg:fib_iterative}
\end{listing}

\end{document}

Use a funcionalidade de programação alfabética do modo organizacional .

A maioria dos usuários do modo organizacional tendem a se concentrar exclusivamente na funcionalidade de gerenciamento de projeto / tempo ou na capacidade de exportar documentos para vários formatos populares de arquivos, como PDF , de arquivos de texto fáceis de manter .

No entanto, a melhor característica do modo organizacional é a capacidade de criar programas alfabetizados em mais de 30 idiomas, com mais idiomas adicionados todos os meses pela comunidade de código aberto.

Abaixo estão exemplos de código triviais usando Ruby e Python:

 #+NAME: trivial-code-ex1
 #+BEGIN_SRC ruby 
   "hello world!"
 #+END_SRC

 #+RESULTS: trivial-code-ex1
 : hello world!


 #+NAME: func-of-x-and-y
 #+BEGIN_SRC python :var x=1 :var y=2 :session
   x + y
 #+END_SRC

 #+RESULTS: func-of-x-and-y
 : 3

Prós

• Suporte para mais de 30 linguagens de programação , incluindo R, Python, Ruby, Perl, C, C ++, Java, Clojure, Javascript, Lisp comum, Shell, SQL, ...

• A habilidade de:

  • Capturar SRC resultados do bloco como saída e / ou valor.
  • Formate os SRC resultados do bloco como código, listas, tabela, látex, html
  • Use dados externos e internos para variáveis ​​de SRCblocos.
  • Use a saída de SRCblocos nomeados em SRCblocos como variáveis.
  • Use nowebsintaxe dentro de SRCblocos.

    Dica profissional: você pode usar a nowebsintaxe para:

    • insira código de um SRCbloco nomeado , por exemplo func-of-x-and-y, dentro de outro SRCbloco.

      #+BEGIN_SRC python :session :noweb yes 
        x=2
        y=3
        "f(x,y) is\n\n <<func-of-x-and-y>> \n\nso f({0},{1}) equals\n\n {2}".format(x,y,<<func-of-x-and-y>>)
      #+END_SRC
      
      #+RESULTS:
      : f(x,y) is
      : 
      :  x + y 
      : 
      : so f(2,3) equals
      : 
      :  5

    • insira os resultados de um SRCbloco nomeado , por exemplo, func-of-x-and-ydentro de outro SRCbloco

      #+BEGIN_SRC python :session :noweb yes 
        "f(x,y) is\n\n <<func-of-x-and-y>> \n\nso f(3,4) equals\n\n <<func-of-x-and-y(x=3,y=4)>>"
      #+END_SRC
      
      #+RESULTS:
      : f(x,y) is
      : 
      :  x + y 
      : 
      : so f(3,4) equals
      : 
      :  7

    • Coloque os SRCblocos nomeados em qualquer lugar do arquivo de modo organizacional para facilitar a leitura e use o :tanglecabeçalho ou exporte o código em arquivos de origem externos.

• Projeto de código aberto - tanto grátis quanto em cerveja e livre como em liberdade.

• O formato de arquivo de texto funciona muito bem com o software de controle de versão como o git.
• Ooodles de outros recursos que não abordarei porque esta resposta está ficando longa.

Contras

• Precisa ter o gnu emacs instalado e configurado para usar o modo organizacional.

  Nota: A maioria de vocês parou de ler esta resposta depois de ler o gnu emacs. Para as almas corajosas que restam, você pode usar seu editor de texto favorito e chamar o emacs para processar seus arquivos de modo organizacional a partir da linha de comando.

• Precisa instalar e configurar todo o software de programação necessário.

• É necessário instalar e configurar os utilitários do LaTeX se você deseja criar PDFs.
• org-mode não é tão bem conhecido como ipython notebooksou Sweaveentão você provavelmente não vai ver como muitas ofertas de trabalho, embora a funcionalidade Alfabetizado programação foi introduzido em 2008.
• Aprendendo a sintaxe de marcação no modo organizacional
• Potencialmente aprendendo a usar o gnu emacs ou spacemacs se quiser tirar o máximo proveito das outras ferramentas legais que funcionam com o modo organizacional.

Divulgação completa: Sou o principal mantenedor do pacote org-mode do editor Atom.

---

O código nesta resposta foi validado usando:
versão emacs: GNU Emacs 25.2.1
versão org-mode: 9.1.2