¿Cuál sería la forma más útil de escribir código para un artículo para que los lectores puedan hacer coincidir claramente los resultados con el código que los genera?

Estoy escribiendo un documento reproducible, y el documento tiene resultados computacionales generados por un script de Python (un script MATLAB similar genera resultados casi idénticos). Siento que el papel sería más fácil de entender para los lectores si pudieran hacer coincidir los cálculos en el papel con los cálculos en el código. El trabajo propone un formalismo abstracto, y se supone que los ejemplos en el documento hacen este formalismo más concreto para los lectores (muchos de los cuales serán ingenieros); el código probablemente será el registro más detallado de cómo realizar los cálculos, y dejarlo en claro podría ayudarnos durante el proceso de revisión.

¿Alguien tiene alguna sugerencia sobre cómo hacer que la correspondencia entre el código y los resultados computacionales (figuras, ecuaciones) sea más clara?

Por ejemplo, estaba pensando que cuando se trata de líneas de código que implementan varios pasos en el documento, podría citar números de ecuaciones (sería increíble si pudiera hacer referencias cruzadas entre el código y LaTeX, pero etiquetarlos a mano está bien) , y podría escribir funciones correspondientes a los diversos ejemplos y figuras, como

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

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

Si el código fuera grande, y no estuviera tratando de explicar cómo un montón de métodos matemáticos diferentes utilizados en ingeniería eran realmente los mismos, probablemente no me molestaría tanto en aclarar el código, pero dada la naturaleza abstracta del papel y la pequeña base de código, parece que podría haber valor en este ejercicio.

1. Puede considerar escribir todo el artículo en Noweb . Es un poco tedioso configurarlo, pero es una forma muy poderosa de mezclar código y texto, ecuaciones y figuras con formato LaTeX. Para programas largos, tiende a convertir su código en más de un libro que un artículo, pero para programas cortos, podría funcionar bastante bien.

2. Si no quiere llegar tan lejos, aún así debería ser razonablemente sencillo formatear las secciones de comentarios de sus listados de códigos utilizando LaTeX. El listingspaquete puede ayudarlo a lograr esto. Aquí hay un breve ejemplo:

\ documentclass {artículo}
\ usepackage {amsmath}
\ usepackage {listados}
\ begin {document}
\ begin {ecuación}
  \ label {eq: uno}
  Ax = b
\ end {ecuación}
\ begin {lstlisting} [escapechar = \%]
  # Comentario con una referencia a la ecuación% ~ \ eqref {eq: one}%
  def f (a):
    devolver a + 1
\ end {lstlisting}
\ end {documento}

Con algunas manipulaciones adicionales, debería poder obtener sus números de ecuación referenciados para que aparezcan en la fuente monoespacial que utiliza para enumerar la ecuación.

El enfoque noweb mencionado por Bill ha evolucionado bastante, tanto en su espíritu original de documentar código (en lugar de publicación científica) bajo el término programación alfabetizada y ahora viene en muchos sabores (supongo que noweb fue una generalización de cweb inicialmente), de cuál doxygeny varias versiones específicas del idioma pueden generar documentación en TeX, HTML y otros formatos.

Además, noweb se ha desarrollado durante algún tiempo en la Rcomunidad (bueno, originalmente la Scomunidad, de ahí el nombre) bajo el título "Sweave" con el objetivo de proporcionar un documento de "investigación reproducible", donde el código se ejecuta realmente cuando el archivo de látex se compila (y opcionalmente también se muestra). Una gran cantidad de artículos académicos están escritos en Sweave (incluyendo, creo, toda la revista R; pero vea también la revista de bioestadística y su política sobre documentos reproducibles).

Si bien Sweave todavía es parte de cualquier instalación de base R, está siendo reemplazada por knitr, que ahora es independiente del lenguaje , por lo que es una posible opción para su código de Python. Knitr admite la escritura en LaTeX o Markdown, lo que permite resaltar la sintaxis, el almacenamiento en caché, la externalización del código del látex de origen y muchas otras características deseables para este tipo de trabajo.

Python tiene sus propias soluciones que son similares, portátiles de ipython , que pueden renderizar a HTML, tal vez LaTeX, pero sé menos sobre esto.

Otro proyecto que definitivamente vale la pena ver es Dexyit , otro programa independiente del lenguaje que funciona muy bien con LaTeX y HTML. Si bien tiene más ejemplos en la documentación de código que en la redacción de artículos científicos, trabajar en LaTeX debería ser sencillo.

Tanto knitry dexyithará exactamente lo que usted describe en el látex, incluyendo apuntando a un script en Python externa y la lectura en el código. Se pueden lograr cosas similares en DocBook y XML, aunque estoy menos familiarizado con este enfoque.

El paquete LaTeX creado ofrece un resaltado de sintaxis muy extenso (basado en Pygments) y permite referencias cruzadas en ambas direcciones. Puede escapar a LaTeX desde la parte del código (la parte acuñada) y puede hacer referencia en su texto principal a líneas de código. Además de eso, proporciona un entorno de listados para que pueda generar una "lista de listados" (como una lista de tablas) y permite hacer referencia a listados completos. Vea LaTeX MWE y su salida con LuaLaTeX a continuación (no juzgue el código :-)).

Otra opción sería usar PythonTeX del mismo autor / mantenedor que permite ejecutar los cálculos al compilar la fuente LaTeX, por lo tanto, los resultados en papel y en código siempre se generan juntos y, por lo tanto, siempre son coherentes. Vea la galería de PythonTeX aquí.

\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}

Utilice la funcionalidad de programación literaria del modo org .

La mayoría de los usuarios del modo de organización tienden a centrarse exclusivamente en la funcionalidad integrada de gestión de tiempo / proyecto o en la capacidad de exportar documentos a múltiples formatos de archivo populares, por ejemplo , PDF , desde archivos de texto fáciles de mantener .

Sin embargo, la mejor característica del modo org es la capacidad de crear programas alfabetizados en más de 30 idiomas con más idiomas agregados cada mes por la comunidad de código abierto.

A continuación se muestran ejemplos de códigos triviales con Ruby y 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

Pros

• Soporte para más de 30 lenguajes de programación , incluidos R, Python, Ruby, Perl, C, C ++, Java, Clojure, Javascript, Common Lisp, Shell, SQL, ...

• La habilidad para:

  • Capture los SRC resultados del bloque como salida y / o valor.
  • Formatee los SRC resultados del bloque como código, listas, tabla, látex, html
  • Utilice datos tanto externos como internos para variables de SRCbloques.
  • Use la salida de SRCbloques con nombre en SRCbloques como variables.
  • Use la nowebsintaxis dentro de los SRCbloques.

    Consejo profesional: puede usar la nowebsintaxis para:

    • inserte código de un SRCbloque con nombre , por ejemplo func-of-x-and-y, dentro de otro SRCbloque.

      #+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

    • insertar los resultados de un SRCbloque con nombre , por ejemplo, func-of-x-and-ydentro de otro SRCbloque

      #+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 SRCbloques con nombre en cualquier lugar de un archivo de modo de organización para facilitar la lectura y utilice el :tangleencabezado o el código de exportación en archivos de origen externos.

• Proyecto de código abierto, tanto gratis como en cerveza y gratis como en libertad.

• El formato de archivo de texto funciona muy bien con el software de control de versiones como git.
• Ooodles de otras características en las que no entraré porque esta respuesta se está alargando.

Contras

• Necesita tener gnu emacs instalado y configurado para usar el modo org.

  Nota: La mayoría de ustedes dejó de leer esta respuesta después de leer gnu emacs. Para las almas valientes que quedan, puede usar su editor de texto favorito y simplemente llamar a emacs para procesar sus archivos de modo org desde la línea de comandos.

• Necesita instalar y configurar todo el software de programación que necesita.

• Necesita instalar y configurar las utilidades de LaTeX si desea hacer archivos PDF.
• org-mode no es tan conocido como ipython notebooks o Sweavepor lo que probablemente no verá tantas ofertas de trabajo a pesar de que sabe leer y escribir funcionalidad de programación se añadió en 2008.
• Aprendizaje de sintaxis de marcado en modo org
• Potencialmente aprender a usar gnu emacs o spacemacs si desea aprovechar al máximo las otras herramientas geniales que funcionan con el modo org.

Divulgación completa: soy el principal responsable del paquete del modo org para el editor Atom.

---

El código en esta respuesta fue validado usando:
versión de emacs: GNU Emacs 25.2.1
versión del modo org: 9.1.2