Quelle serait la façon la plus utile d'écrire du code pour un article afin que les lecteurs puissent clairement faire correspondre les résultats au code qui les génère?

J'écris un papier reproductible, et le papier a des résultats de calcul qui sont générés par un script Python (un script MATLAB similaire génère des résultats presque identiques). Je pense que le papier serait plus facile à comprendre pour les lecteurs s'ils pouvaient faire correspondre les calculs dans le papier avec les calculs dans le code. L'ouvrage propose un formalisme abstrait, et les exemples de l'article sont censés rendre ce formalisme plus concret pour les lecteurs (dont beaucoup seront des ingénieurs); le code sera probablement l'enregistrement le plus détaillé de la façon d'effectuer les calculs, et le clarifier pourrait nous aider pendant le processus d'examen.

Quelqu'un a-t-il des suggestions sur la façon de rendre plus claire la correspondance entre le code et les résultats de calcul (figures, équations)?

Par exemple, je pensais que lorsqu'il s'agissait de lignes de code mettant en œuvre diverses étapes du document, je pouvais citer des nombres d'équations (ce serait étonnant si je pouvais croiser les références entre le code et LaTeX, mais les étiqueter à la main est très bien) , et je pourrais écrire des fonctions correspondant aux différents exemples et figures, comme

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

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

Si le code était volumineux et que je n'essayais pas d'expliquer en quoi un tas de méthodes mathématiques différentes utilisées en ingénierie étaient en fait les mêmes, je ne me soucierais probablement pas autant de clarifier le code, mais étant donné la nature abstraite du papier et la petite base de code, il semble que cet exercice puisse être utile.

1. Vous pourriez envisager d'écrire l'intégralité du document dans Noweb . C'est un peu fastidieux à configurer, mais c'est un moyen très puissant de mélanger du code et du texte, des équations et des figures au format LaTeX. Pour les programmes longs, il a tendance à transformer votre code en un livre plutôt qu'en un article, mais pour les programmes courts, cela pourrait très bien fonctionner.

2. Si vous ne voulez pas aller aussi loin, il devrait toujours être assez simple de formater les sections de commentaires de vos listes de codes à l'aide de LaTeX. Le listingspackage peut vous aider à retirer cela. Voici un petit exemple:

\ documentclass {article}
\ usepackage {amsmath}
\ usepackage {listings}
\ begin {document}
\ commencer {équation}
  \ label {eq: one}
  Ax = b
\ end {équation}
\ begin {lstlisting} [escapechar = \%]
  # Commentaire avec une référence à l'équation% ~ \ eqref {eq: one}%
  def f (a):
    retourner un + 1
\ end {lstlisting}
\ end {document}

Avec quelques manipulations supplémentaires, vous devriez pouvoir faire apparaître vos numéros d'équation référencés dans la police à espacement fixe qu'il utilise pour répertorier l'équation.

L'approche noweb mentionnée par Bill a beaucoup évolué, à la fois dans son esprit original de documenter le code (plutôt que dans la publication scientifique) sous le terme de programmation alphabétisée et se décline désormais en plusieurs saveurs (je suppose que noweb était une généralisation de cweb au départ), de lesquelles doxygenet diverses versions spécifiques à une langue peuvent générer de la documentation en TeX, HTML et autres formats.

Plus précisément, noweb a été développé pendant un certain temps dans la Rcommunauté (enfin à l'origine la Scommunauté, d'où le nom) sous le titre "Sweave" dans le but de fournir un document de "recherche reproductible", où le code est réellement exécuté lorsque le fichier latex est compilé (et éventuellement affiché également). Un grand nombre d'articles universitaires sont écrits en Sweave (y compris, je crois, tous les R-journal; mais voir aussi le journal de biostatistique et sa politique sur les articles reproductibles).

Alors que Sweave fait toujours partie de toute installation de base R, il est remplacé par knitr qui est désormais indépendant du langage , ce qui en fait un choix possible pour votre code python. Knitr prend en charge l'écriture dans LaTeX ou le démarquage, prenant en charge la mise en évidence de la syntaxe, la mise en cache, l'externalisation du code à partir du latex source et de nombreuses autres fonctionnalités souhaitables pour ce type de travail.

Python a ses propres solutions similaires, des cahiers ipython , qui peuvent être rendus en HTML, peut-être LaTeX, mais j'en sais moins à ce sujet.

Dexyit , un autre programme indépendant de la langue qui fonctionne très bien avec LaTeX et HTML, vaut vraiment le coup d'œil . Bien qu'il ait plus d'exemples dans la documentation du code que dans la rédaction d'articles scientifiques, travailler dans LaTeX devrait être simple.

Les deux knitret dexyitfera exactement ce que vous décrivez dans le LATEX, y compris en montrant script python externe et la lecture dans le code. Des choses similaires peuvent être accomplies dans DocBook et XML, bien que je connaisse moins bien cette approche.

Le package LaTeX minted fournit une coloration syntaxique très étendue (basée sur Pygments) et permet des références croisées dans les deux directions. Vous pouvez échapper à LaTeX depuis la partie code (la partie frappée) et vous pouvez vous référer dans votre texte principal aux lignes de code. En plus de cela, il fournit un environnement de listes afin que vous puissiez générer une "liste de listes" (comme une liste de tableaux) et permet de référencer des listes entières. Voir LaTeX MWE et sa sortie avec LuaLaTeX ci-dessous (ne jugez pas le code :-)).

Une autre option serait d'utiliser PythonTeX du même auteur / mainteneur qui permet d'exécuter les calculs tout en compilant la source LaTeX, donc les résultats papier et code sont toujours générés ensemble et donc toujours cohérents. Voir la galerie PythonTeX ici.

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

Utilisez la fonctionnalité de programmation littéraire du mode org .

La plupart des utilisateurs en mode org ont tendance à se concentrer exclusivement sur la fonctionnalité intégrée de gestion de projet / temps ou sur la possibilité d'exporter des documents dans plusieurs formats de fichiers populaires, par exemple PDF , à partir de fichiers texte faciles à entretenir .

Cependant, la meilleure caractéristique du mode org est la possibilité de créer des programmes alphabétisés dans plus de 30 langues avec plus de langues ajoutées chaque mois par la communauté open source.

Voici des exemples de code triviaux utilisant Ruby et 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

Avantages

• Prise en charge de plus de 30 langages de programmation , dont R, Python, Ruby, Perl, C, C ++, Java, Clojure, Javascript, Common Lisp, Shell, SQL, ...

• La capacité à:

  • Capturez SRC les résultats des blocs en tant que sortie et / ou valeur.
  • Formater SRC les résultats des blocs en tant que code, listes, table, latex, html
  • Utilisez les données externes et internes pour les variables des SRCblocs.
  • Utilisez la sortie des SRCblocs nommés en SRCblocs en tant que variables.
  • Utilisez la nowebsyntaxe à l'intérieur des SRCblocs.

    Conseil de pro: vous pouvez utiliser la nowebsyntaxe pour:

    • insérer du code à partir d'un SRCbloc nommé , par exemple à l' func-of-x-and-yintérieur d'un autre SRCbloc.

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

    • insérer les résultats d'un SRCbloc nommé , par exemple à l' func-of-x-and-yintérieur d'un autre SRCbloc

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

    • Placez les SRCblocs nommés n'importe où dans un fichier en mode organisation pour plus de lisibilité et utilisez l'en- :tangletête ou exportez le code dans des fichiers source externes.

• Projet open source - à la fois gratuit comme dans la bière et gratuit comme dans la liberté.

• Le format de fichier texte fonctionne très bien avec un logiciel de contrôle de version comme git.
• Des tas d'autres fonctionnalités dans lesquelles je n'entrerai pas car cette réponse devient longue.

Les inconvénients

• Besoin d'avoir gnu emacs installé et configuré pour utiliser le mode org.

  Remarque: La plupart d'entre vous ont arrêté de lire cette réponse après avoir lu gnu emacs. Pour les âmes courageuses qui restent, vous pouvez utiliser votre éditeur de texte préféré et appeler simplement emacs pour traiter vos fichiers en mode organisation à partir de la ligne de commande.

• Besoin d'installer et de configurer tous les logiciels de programmation dont vous avez besoin.

• Besoin d'installer et de configurer les utilitaires LaTeX si vous souhaitez créer des PDF.
• org-mode n'est pas aussi bien connu ipython notebooksouSweave donc vous ne verrez probablement pas autant de offres d'emploi , même si la fonctionnalité de programmation lettrée a été ajouté en 2008.
• Apprentissage de la syntaxe de balisage en mode organisationnel
• Apprendre potentiellement à utiliser des emacs gnu ou des spacemacs si vous voulez tirer le meilleur parti des autres outils sympas qui fonctionnent avec le mode org.

Divulgation complète: je suis le principal mainteneur du package en mode org pour l'éditeur Atom.

---

Le code dans cette réponse a été validé en utilisant:
version emacs: GNU Emacs 25.2.1
version org-mode: 9.1.2