Apa cara yang paling membantu untuk menulis kode untuk makalah sehingga pembaca dapat dengan jelas mencocokkan hasilnya dengan kode yang menghasilkannya?

Saya sedang menulis makalah yang dapat direproduksi, dan makalah ini memiliki hasil komputasi yang dihasilkan oleh skrip Python (skrip MATLAB serupa menghasilkan hasil yang hampir identik). Saya merasa bahwa makalah ini akan lebih mudah dipahami oleh pembaca jika mereka dapat mencocokkan perhitungan di koran dengan perhitungan dalam kode. Karya ini mengusulkan formalisme abstrak, dan contoh-contoh di koran seharusnya membuat formalisme ini lebih konkret bagi pembaca (banyak dari mereka akan menjadi insinyur); kode mungkin akan menjadi catatan paling rinci tentang cara melakukan perhitungan, dan membuatnya jelas dapat membantu kami selama proses peninjauan.

Adakah yang punya saran tentang bagaimana membuat korespondensi antara kode dan hasil komputasi (angka, persamaan) lebih jelas?

Sebagai contoh, saya berpikir bahwa ketika sampai pada garis kode yang menerapkan berbagai langkah di koran, saya dapat mengutip angka persamaan (akan luar biasa jika saya bisa melintasi referensi antara kode dan LaTeX, tetapi pelabelan tangan mereka baik-baik saja) , dan saya bisa menulis fungsi yang sesuai dengan berbagai contoh dan angka, seperti

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

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

Jika kodenya besar, dan saya tidak mencoba menjelaskan bagaimana sekelompok metode matematika yang berbeda yang digunakan dalam rekayasa sebenarnya sama, saya mungkin tidak akan terlalu repot dengan membuat kode jelas, tetapi mengingat sifat abstrak dari kertas dan basis kode kecil, sepertinya ada nilai dalam latihan ini.

1. Anda mungkin mempertimbangkan untuk menulis seluruh makalah di Noweb . Agak membosankan untuk diatur, tetapi ini adalah cara yang sangat ampuh untuk mencampur kode dan teks, persamaan, dan gambar berformat LaTeX. Untuk program yang panjang, cenderung mengubah kode Anda menjadi lebih dari sebuah buku daripada sebuah artikel, tetapi untuk program pendek, itu mungkin bekerja dengan cukup baik.

2. Jika Anda tidak ingin melangkah sejauh itu, masih cukup mudah untuk memformat bagian komentar dari daftar kode Anda menggunakan LaTeX. The listingspaket dapat membantu Anda melakukan ini. Ini contoh singkatnya:

\ documentclass {article}
\ usepackage {amsmath}
\ usepackage {listing}
\ begin {document}
\ mulai {persamaan}
  \ label {eq: one}
  Axe = b
\ end {persamaan}
\ begin {lstlisting} [escapechar = \%]
  # Komentar dengan referensi ke Persamaan% ~ \ eqref {eq: one}%
  def f (a):
    mengembalikan +1
\ end {lstlisting}
\ end {document}

Dengan beberapa manipulasi tambahan, Anda harus bisa membuat nomor persamaan referensi Anda muncul di font monospace yang digunakan untuk daftar persamaan.

Pendekatan noweb yang disebutkan oleh Bill telah berevolusi sedikit, baik di dalamnya semangat asli mendokumentasikan kode (daripada publikasi ilmiah) di bawah istilah pemrograman melek dan sekarang datang dalam banyak rasa (saya kira noweb adalah generalisasi dari cweb awalnya), dari yang mana doxygendan berbagai versi spesifik bahasa dapat menghasilkan dokumentasi dalam TeX, HTML, dan format lainnya.

Lebih ke titik Anda, noweb telah dikembangkan untuk beberapa waktu di Rkomunitas (awalnya Skomunitas, maka nama) di bawah judul "Sweave" dengan tujuan menyediakan kertas "penelitian direproduksi", di mana kode sebenarnya dijalankan ketika file lateks dikompilasi (dan juga ditampilkan opsional). Cukup banyak makalah akademis yang ditulis dalam Sweave (termasuk, saya percaya, semua R-jurnal; tetapi lihat juga jurnal biostatistik dan kebijakan tentang makalah yang dapat direproduksi).

Walaupun Sweave masih merupakan bagian dari instalasi R dasar apa pun, itu sedang digantikan oleh knitr yang sekarang menjadi bahasa agnostik , menjadikannya pilihan yang mungkin untuk kode python Anda. Knitr mendukung penulisan dalam LaTeX atau penurunan harga, mendukung penyorotan sintaks, caching, eksternalisasi kode dari sumber lateks dan banyak fitur lain yang diinginkan untuk jenis pekerjaan ini.

Python memiliki solusi sendiri yang mirip, notebook ipython , yang dapat di-render ke HTML, mungkin LaTeX, tapi saya kurang tahu tentang ini.

Proyek lain yang pasti patut dilihat adalah dexyit , program agnostik bahasa lain yang bekerja sangat baik dengan LaTeX dan HTML. Meskipun memiliki lebih banyak contoh dalam mendokumentasikan kode daripada menulis makalah ilmiah, bekerja di LaTeX harus langsung.

Keduanya knitrdan dexyitakan melakukan apa yang Anda jelaskan di LaTeX, termasuk menunjuk ke skrip python eksternal dan membaca dalam kode. Hal serupa dapat dicapai dalam DocBook dan XML, meskipun saya kurang terbiasa dengan pendekatan ini.

Paket LaTeX dicetak menyediakan penyorotan sintaksis yang sangat luas (berdasarkan Pygments) dan memungkinkan referensi silang di kedua arah. Anda dapat melarikan diri ke LaTeX dari dalam bagian kode (bagian dicetak) dan Anda dapat merujuk dalam teks utama Anda ke baris kode. Selain itu, ini menyediakan lingkungan daftar sehingga Anda dapat menghasilkan "daftar daftar" (seperti daftar tabel) dan memungkinkan referensi seluruh daftar. Lihat LaTeX MWE dan hasilnya dengan LuaLaTeX di bawah ini (jangan menilai kode :-)).

Opsi lain adalah menggunakan PythonTeX dari penulis / pengelola yang sama yang memungkinkan menjalankan perhitungan sambil mengkompilasi sumber LaTeX, karenanya hasil kertas dan kode selalu dihasilkan bersama dan karenanya selalu koheren. Lihat galeri PythonTeX di sini.

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

Gunakan Fungsi Pemrograman Literate dari mode-org .

Sebagian besar pengguna mode-org cenderung berfokus secara eksklusif pada fungsionalitas manajemen proyek / waktu bawaan atau kemampuan untuk mengekspor dokumen ke berbagai format file populer, misalnya PDF , dari pemeliharaan file teks yang mudah .

Namun, fitur terbaik dari mode-org adalah kemampuan untuk membuat program melek di lebih dari 30 bahasa dengan lebih banyak bahasa ditambahkan setiap bulan oleh komunitas open source.

Berikut adalah contoh kode sepele menggunakan Ruby dan 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

Pro

• Dukungan untuk lebih dari 30 bahasa pemrograman , termasuk R, Python, Ruby, Perl, C, C ++, Java, Clojure, Javascript, Common Lisp, Shell, SQL, ...

• Kemampuan untuk:

  • Tangkap SRC hasil blok sebagai output dan / atau nilai.
  • Memformat SRC hasil blok sebagai kode, daftar, tabel, lateks, html
  • Gunakan data eksternal & internal untuk variabel SRCblok.
  • Gunakan output dari SRCblok bernama ke dalam SRCblok sebagai variabel.
  • Gunakan nowebsintaks di dalam SRCblok.

    Kiat Pro: Anda dapat menggunakan nowebsintaks untuk:

    • masukkan kode dari SRCblok bernama , misalnya func-of-x-and-y, di dalam SRCblok lain .

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

    • masukkan hasil dari SRCblok bernama , misalnya func-of-x-and-ydi dalam SRCblok lain

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

    • Tempatkan SRCblok bernama di mana saja dalam file mode-org untuk keterbacaan dan gunakan :tangleheader atau kode ekspor ke file sumber eksternal.

• Proyek open source - keduanya gratis seperti dalam bir dan gratis seperti dalam kebebasan.

• Format file teks berfungsi baik dengan perangkat lunak kontrol versi seperti git.
• Ooodles dari fitur lain yang tidak akan saya bahas karena jawaban ini semakin panjang.

Cons

• Perlu menginstal dan mengkonfigurasi gnu emacs untuk menggunakan mode-org.

  Catatan: Sebagian besar dari Anda berhenti membaca jawaban ini setelah Anda membaca gnu emacs. Untuk jiwa pemberani yang tersisa, Anda dapat menggunakan editor teks favorit Anda dan panggil emacs untuk memproses file mode-org Anda dari baris perintah.

• Perlu menginstal dan mengkonfigurasi semua perangkat lunak pemrograman yang Anda butuhkan.

• Perlu menginstal dan mengkonfigurasi utilitas LaTeX jika Anda ingin membuat PDF.
• org-mode tidak tahu ipython notebooksatau SweaveAnda mungkin tidak akan melihat banyak lowongan pekerjaan meskipun fungsi Pemrograman Sastra telah ditambahkan pada 2008.
• Mempelajari sintaks markup mode-org
• Berpotensi belajar cara menggunakan gnu emacs atau spacemacs jika ingin memanfaatkan alat keren lain yang berfungsi dengan mode-org.

Pengungkapan penuh: Saya adalah pengelola utama paket mode-org untuk editor Atom.

---

Kode dalam jawaban ini divalidasi menggunakan:
versi emacs: GNU Emacs 25.2.1
versi mode org: 9.1.2