Was wäre die hilfreichste Methode, um Code für ein Papier zu schreiben, damit die Leser die Ergebnisse eindeutig dem Code zuordnen können, der sie generiert?

Ich schreibe ein reproduzierbares Papier, und das Papier enthält Berechnungsergebnisse, die von einem Python-Skript generiert werden (ein ähnliches MATLAB-Skript generiert nahezu identische Ergebnisse). Ich bin der Meinung, dass das Papier für die Leser leichter zu verstehen wäre, wenn sie die Berechnungen im Papier mit den Berechnungen im Code in Einklang bringen könnten. Die Arbeit schlägt einen abstrakten Formalismus vor, und die Beispiele in der Arbeit sollen diesen Formalismus für die Leser (von denen viele Ingenieure sein werden) konkreter machen. Der Code wird wahrscheinlich die detaillierteste Aufzeichnung der Durchführung der Berechnungen sein, und eine Verdeutlichung könnte uns während des Überprüfungsprozesses helfen.

Hat jemand Vorschläge, wie man die Entsprechung zwischen Code und Rechenergebnissen (Zahlen, Gleichungen) klarer machen kann?

Ich dachte zum Beispiel, wenn es um Codezeilen geht, in denen verschiedene Schritte des Papiers implementiert werden, könnte ich Gleichungsnummern zitieren (es wäre erstaunlich, wenn ich den Code mit LaTeX vergleichen könnte, aber Handkennzeichnung ist in Ordnung). und ich könnte Funktionen schreiben, die den verschiedenen Beispielen und Figuren entsprechen, wie z

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

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

Wenn der Code groß wäre und ich nicht erklären wollte, wie viele verschiedene mathematische Methoden in der Technik tatsächlich gleich waren, würde ich mich wahrscheinlich nicht so sehr darum kümmern, den Code klarer zu machen, sondern angesichts der abstrakten Natur der Papier und die kleine Codebasis scheinen in dieser Übung einen Wert zu haben.

1. Sie könnten erwägen, das gesamte Papier in Noweb zu schreiben . Das Einrichten ist etwas langwierig, aber das Mischen von Code und LaTeX-formatiertem Text, Gleichungen und Zahlen ist eine sehr leistungsstarke Methode. Bei langen Programmen verwandelt sich Ihr Code eher in ein Buch als in einen Artikel. Bei kurzen Programmen kann dies jedoch recht gut funktionieren.

2. Wenn Sie nicht so weit gehen möchten, sollte es dennoch recht einfach sein, die Kommentarbereiche Ihrer Codeauflistungen mit LaTeX zu formatieren. Das listingsPaket kann Ihnen dabei helfen. Hier ist ein kurzes Beispiel:

\ documentclass {article}
\ usepackage {amsmath}
\ usepackage {listings}
\ begin {document}
\ begin {equation}
  \ label {eq: one}
  Axe = b
\ end {equation}
\ begin {lstlisting} [escapechar = \%]
  # Kommentar mit einem Verweis auf Gleichung% ~ \ eqref {eq: one}%
  def f (a):
    gib a + 1 zurück
\ end {lstlisting}
\ end {document}

Mit einigen zusätzlichen Manipulationen sollten Sie in der Lage sein, Ihre referenzierten Gleichungsnummern in der Monospace-Schriftart anzuzeigen, die zum Auflisten der Gleichung verwendet wird.

Der noweb Ansatz von Bill erwähnt hat einiges weiterentwickelt, sowohl in seiner ursprünglichen Geist Code zu dokumentieren ( und nicht als wissenschaftliche Publikation) unter dem Begriff Literarische Programmierung und kommt jetzt in vielen Geschmacksrichtungen (Ich denke , noweb eine Verallgemeinerung von cweb anfangs war), von Welche doxygenund verschiedene sprachspezifische Versionen können Dokumentation in TeX, HTML und anderen Formaten generieren.

Weiter zu Ihrem Punkt, noweb wurde für einige Zeit in der RCommunity (also ursprünglich die SCommunity, daher der Name) unter dem Titel "Sweave" mit dem Ziel entwickelt, ein "reproduzierbares Research" -Papier bereitzustellen, in dem der Code tatsächlich ausgeführt wird, wenn Die Latexdatei wird kompiliert (und optional auch angezeigt). In Sweave ist eine ganze Reihe von wissenschaftlichen Artikeln verfasst (einschließlich meines Erachtens des gesamten R-Journals; siehe aber auch das Journal of Biostatistics und dessen Richtlinien für reproduzierbare Artikel).

Während Sweave immer noch Teil einer Base-R-Installation ist, wird es durch knitr ersetzt, das jetzt sprachunabhängig ist , was es zu einer möglichen Wahl für Ihren Python-Code macht. Knitr unterstützt das Schreiben in LaTeX oder Markdown, das Hervorheben der Syntax, das Zwischenspeichern, das Externalisieren des Codes aus dem Quelllatex und viele andere wünschenswerte Funktionen für diese Art von Arbeit.

Python hat seine eigenen Lösungen, ähnlich wie Ipython-Notizbücher , die in HTML, vielleicht LaTeX, gerendert werden können, aber ich weiß weniger darüber.

Ein anderes Projekt, das definitiv einen Blick wert ist , ist dexyit , ein anderes sprachunabhängiges Programm, das sehr gut mit LaTeX und HTML zusammenarbeitet. Es gibt zwar mehr Beispiele für die Dokumentation von Code als für das Schreiben von wissenschaftlichen Artikeln, die Arbeit in LaTeX sollte jedoch einfach sein.

Beide knitrund dexyitwerden genau das tun, was Sie in LaTeX beschrieben haben, einschließlich Verweisen auf ein externes Python-Skript und Einlesen des Codes. Ähnliche Dinge können in DocBook und XML ausgeführt werden, obwohl ich mit diesem Ansatz weniger vertraut bin.

Das Latex Paket geprägt liefert sehr umfangreiche Syntax - Hervorhebung (basierend auf Pygments) und erlaubt Querverweise in beiden Richtungen. Sie können aus dem Codeteil (dem geprägten Teil) heraus zu LaTeX wechseln und in Ihrem Haupttext auf Codezeilen verweisen. Darüber hinaus bietet es eine Listungsumgebung, mit der Sie eine "Listungsliste" (wie eine Liste von Tabellen) erstellen und auf ganze Listungen verweisen können. Siehe LaTeX MWE und seine Ausgabe mit LuaLaTeX unten (den Code nicht beurteilen :-)).

Eine andere Möglichkeit wäre, PythonTeX vom selben Autor / Betreuer zu verwenden, wodurch die Berechnungen beim Kompilieren der LaTeX-Quelle ausgeführt werden können. Daher werden Papier- und Code-Ergebnisse immer zusammen generiert und sind daher immer kohärent. Sehen Sie sich hier die PythonTeX-Galerie an.

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

Verwenden Sie die Literate Programming Functionality des org-Modus .

Die meisten Benutzer im Organisationsmodus konzentrieren sich in der Regel ausschließlich auf die integrierte Projekt- / Zeitverwaltungsfunktion oder auf die Möglichkeit, Dokumente in mehrere gängige Dateiformate, z. B. PDF, zu exportieren aus einfach zu verwaltenden Textdateien , .

Die beste Funktion von org-mode ist jedoch die Möglichkeit, Lese- und Schreibprogramme in über 30 Sprachen zu erstellen, wobei die Open-Source-Community jeden Monat weitere Sprachen hinzufügt.

Nachfolgend finden Sie einfache Codebeispiele mit Ruby und 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

Vorteile

• Unterstützung für über 30 Programmiersprachen , einschließlich R, Python, Ruby, Perl, C, C ++, Java, Clojure, Javascript, Common Lisp, Shell, SQL, ...

• Die Fähigkeit zu:

  • Erfassung SRC als Ausgabe und / oder Wert erfassen.
  • Format SRC Blockergebnisse als Code, Listen, Tabelle, Latex, HTML
  • Verwenden Sie sowohl externe als auch interne Daten für Variablen von SRC Blöcken.
  • Verwenden Sie die Ausgabe von benannten SRCBlöcken inSRC Blöcken als Variablen.
  • Verwenden Sie die nowebSyntax in SRCBlöcken.

    Pro Tipp: Mit dernoweb Syntax können Sie :

    • Code aus einem benannten SRCBlock einfügen , z. B. func-of-x-and-yin einen anderen SRCBlock.

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

    • füge die Ergebnisse eines benannten SRCBlocks ein, zB func-of-x-and-yin einen anderen SRCBlock

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

    • Platzieren Sie benannte SRCBlöcke zur besseren Lesbarkeit an einer beliebigen Stelle in einer Datei im Organisationsmodus und verwenden Sie den :tangleHeader oder exportieren Sie den Code in externe Quelldateien.

• Open-Source-Projekt - kostenlos wie in Bier und kostenlos wie in Freiheit.

• Das Textdateiformat funktioniert hervorragend mit Versionskontrollsoftware wie git.
• Unmengen anderer Features, auf die ich nicht eingehen werde, weil diese Antwort immer länger wird.

Nachteile

• Es muss Gnu-Emacs installiert und konfiguriert sein, um den Organisationsmodus zu verwenden.

  Hinweis: Die meisten von Ihnen haben aufgehört, diese Antwort zu lesen, nachdem Sie Gnu-Emacs gelesen haben. Für die tapferen Seelen, die noch übrig sind, können Sie Ihren bevorzugten Texteditor verwenden und einfach Emacs aufrufen, um Ihre Dateien im Organisationsmodus über die Befehlszeile zu verarbeiten.

• Es muss die gesamte benötigte Programmiersoftware installiert und konfiguriert werden.

• Zum Erstellen von PDFs müssen LaTeX-Dienstprogramme installiert und konfiguriert werden.
• org-mode ist nicht so gut bekannt wie ipython notebooksorSweave so, Sie werden wahrscheinlich nicht so viele Stellenausschreibungen sehen, obwohl die Literate Programming-Funktionalität 2008 hinzugefügt wurde.
• Erlernen der Markup-Syntax im Organisationsmodus
• Potenziell lernen, wie man Gnu-Emacs oder Spacemacs benutzt, wenn man das Beste aus den anderen coolen Tools herausholen möchte, die mit dem Org-Modus arbeiten.

Vollständige Offenlegung: Ich bin der Hauptbetreuer des org-mode- Pakets für den Atom-Editor.

---

Der Code in dieser Antwort wurde validiert mit:
emacs version: GNU Emacs 25.2.1
org-mode version: 9.1.2