Okuyucuların sonuçları onları üreten kodla açıkça eşleştirebilmeleri için bir makaleye kod yazmanın en yararlı yolu nedir?

Tekrarlanabilir bir kağıt yazıyorum ve kağıt bir Python komut dosyası (benzer bir MATLAB komut dosyası neredeyse aynı sonuçları üretir) tarafından oluşturulan hesaplama sonuçları vardır. Kağıdın içindeki hesaplamaları koddaki hesaplarla eşleştirebilseler, makalenin okuyucular için daha kolay anlaşılabileceğini hissediyorum. Çalışma soyut bir formalizm öneriyor ve makaledeki örneklerin bu formalizmi okuyucular için (birçoğu mühendis olacak) daha somut hale getirmesi gerekiyor; kod muhtemelen hesaplamaların nasıl yapılacağına dair en ayrıntılı kayıt olacaktır ve bunu netleştirmek, inceleme sürecinde bize yardımcı olabilir.

Kod ve hesaplama sonuçları (rakamlar, denklemler) arasındaki yazışmanın nasıl daha net hale getirileceğine dair herhangi bir öneriniz var mı?

Örneğin, kağıttaki çeşitli adımları uygulayan kod satırlarına gelince, denklem numaralarını gösterebileceğimi düşünüyordum (kod ve LaTeX arasında referansı geçebilirsem harika olurdu, ancak bunları elle etiketleme gayet iyi olurdu) ve çeşitli örneklere ve şekillere karşılık gelen fonksiyonlar yazabilirim, örneğin

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

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

Kod büyükse ve mühendislikte kullanılan farklı matematiksel yöntemlerin aslında nasıl aynı olduğunu açıklamaya çalışmasaydım, muhtemelen kodu açık hale getirmekle çok fazla uğraşmazdım, ancak kağıt ve küçük kod tabanı, bu alıştırmada değer olabilir gibi görünüyor.

1. Tüm makaleyi Noweb'de yazmayı düşünebilirsiniz . Kurulumu biraz yorucu, ancak kodu ve LaTeX biçimli metni, denklemleri ve şekilleri karıştırmanın çok güçlü bir yolu. Uzun programlar için, kodunuzu bir makaleden daha çok bir kitaba dönüştürme eğilimindedir, ancak kısa programlar için oldukça iyi sonuç verebilir.

2. Bu kadar ileri gitmek istemiyorsanız, kod listelerinizin yorum bölümlerini LaTeX kullanarak biçimlendirmek yine de makul olacaktır. listingsPaketi, yalnızca bu kapalı çekin yardımcı olabilir. Kısa bir örnek:

\ Documentclass {makale}
\ Usepackage {amsmath}
\ Usepackage {listeleri}
{Document} başlayacak \
{Denklem} başlayacak \
  \ Etiketi {eşdeğer: Bir}
  Ax = b
\ Ucu {denklem}
başlamak \ {lstlisting} [EscapeChar = \%]
  #% ~ \ Eqref {eq: one}% Denklemine referansla yorum yapma
  def f (a):
    + 1 döndür
\ Son {lstlisting}
\ Ucu {belge}

Bazı ek manipülasyonlarda, referans verilen denklem numaralarınızı denklemi listelemek için kullandığı tek aralıklı yazı tipinde görünmesini sağlayabilirsiniz.

Bill'in bahsettiği noweb yaklaşımı, hem okuryazar programlama terimi altında kodun (bilimsel yayın yerine) orijinal ruhsalında oldukça gelişti ve şimdi birçok lezzetle geliyor (sanırım noweb başlangıçta cweb'in genelleştirilmesiydi), hangi doxygenve çeşitli dile özgü sürümler TeX, HTML ve diğer biçimlerde belgeler oluşturabilir.

Daha da önemlisi, noweb, kodun gerçekte ne zaman çalıştırıldığı bir "tekrarlanabilir araştırma" belgesi sunmak amacıyla "Sweave" başlığı altında Rtoplulukta bir süre (aslında başlangıçta Stopluluk, dolayısıyla adı) geliştirilmiştir. lateks dosyası derlenir (ve isteğe bağlı olarak da görüntülenir). Sweave'de oldukça fazla akademik makale yazılmıştır (inanıyorum, tüm R-dergisi dahil; ancak aynı zamanda biyoistatistik dergisi ve bunun tekrarlanabilir kağıtlar politikasıdır).

Sweave hala herhangi bir temel R kurulumunun bir parçası olsa da, artık dil agnostik olan knitr ile değiştiriliyor ve bu da onu python kodunuz için olası bir seçenek haline getiriyor. Knitr, LaTeX veya işaretlemede yazmayı destekler, sözdizimi vurgulamayı, önbelleğe almayı, kodun kaynak lateksinden dışsallaştırılmasını ve bu tür işler için istenen diğer birçok özelliği destekler.

Python, HTML'ye, belki LaTeX'e dönüştürebilen ipython defterlerine benzer kendi çözümlerine sahiptir , ancak bu konuda daha az şey biliyorum.

Kesinlikle bir göz atmaya değer başka bir proje , LaTeX ve HTML ile çok güzel çalışan bir başka dil-agnostik program olan dexyit . Kod belgelemede bilimsel makale yazmaktan daha fazla örneği olsa da, LaTeX'te çalışmak doğrudan doğruya olmalıdır.

Her ikisi de knitrve dexyitharici python betiğine işaret etmek ve kodda okumak da dahil olmak üzere LaTeX'te tam olarak tarif ettiğiniz şeyi yapacak. Benzer şeyler DocBook ve XML'de de yapılabilir, ancak bu yaklaşıma daha az aşinayım.

Latex paketi basılmış (Pygments göre) çok geniş bir dizim sağlar ve her iki yönde çapraz referans verir. LaTeX'e kod kısmından (darp edilen kısım) kaçabilir ve ana metninizde kod satırlarına başvurabilirsiniz. Bunun da ötesinde, bir "liste listesi" (tablo listesi gibi) oluşturabilmeniz için bir liste ortamı sağlar ve tüm listelere referans vermeyi sağlar. Bkz. LaTeX MWE ve çıktısı aşağıdaki LuaLaTeX ile (kodu yargılamayın :-)).

Başka bir seçenek de , LaTeX kaynağını derlerken hesaplamaların yapılmasına izin veren aynı yazarın / koruyucunun PythonTeX'in kullanılmasıdır , bu nedenle kağıt ve kod sonuçları her zaman birlikte üretilir ve bu nedenle her zaman tutarlıdır. Burada PythonTeX galerisine bakın .

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

Kuruluş kipinin Literatürel Programlama İşlevselliğini kullanın .

Kuruluş modu kullanıcılarının çoğu, yerleşik proje / zaman yönetimi işlevselliğine veya belgeleri bakımı kolay metin dosyalarından PDF gibi çok sayıda popüler dosya biçimine dışa aktarma özelliğine odaklanma eğilimindedir .

Bununla birlikte, org modunun en iyi özelliği, açık kaynak topluluğu tarafından her ay daha fazla dille 30'dan fazla dilde okuryazar programlar oluşturma yeteneğidir.

Ruby ve Python kullanan önemsiz kod örnekleri aşağıdadır:

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

Artıları

• R, Python, Ruby, Perl, C, C ++, Java, Clojure, Javascript, Common Lisp, Shell, SQL, dahil 30'dan fazla programlama dili desteği ...

• Şunları yapabilme:

  • SRCBlok sonuçlarını çıktı ve / veya değer olarak yakalayın .
  • SRCBlok sonuçlarını kod, listeler, tablo, lateks, html olarak biçimlendirme
  • SRCBlok değişkenleri için hem harici hem de dahili verileri kullanın .
  • Değişken olarak adlandırılmış SRCblokların çıktılarını bloklar halinde kullanın SRC.
  • Blokların nowebiçinde sözdizimi kullanın SRC.

    Profesyonel İpucu:noweb Sözdizimini aşağıdakileri yapmak için kullanabilirsiniz :

    • adlandırılmış bir SRCbloktan, örneğin func-of-x-and-ybaşka bir SRCblok içine kod ekleyin .

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

    • adlandırılmış bir SRCbloğun sonuçlarını , örneğin func-of-x-and-ybaşka bir SRCbloğun içine ekleyin

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

    • SRCOkunabilirlik için adlandırılmış blokları kuruluş modu dosyasında herhangi bir yere yerleştirin ve :tangledış kaynak dosyalarına üstbilgi veya dışa aktarma kodu kullanın .

• Açık kaynaklı proje - hem birada hem de özgürlükte özgür.

• Metin dosyası biçimi git gibi sürüm kontrol yazılımlarıyla harika çalışır.
• İçine girmeyeceğim diğer özelliklerin ooodles çünkü bu cevap uzun sürüyor.

Eksileri

• Kuruluş kipini kullanmak için gnu emac'lerin yüklü ve yapılandırılmış olması gerekir.

  Not: Birçoğunuz gnu emacs'ı okuduktan sonra bu cevabı okumayı bıraktınız. Kalan cesur ruhlar için, en sevdiğiniz metin düzenleyicisini kullanabilir ve yalnızca komut kipinden kuruluş modu dosyalarınızı işlemek için emacs'ı çağırabilirsiniz.

• İhtiyacınız olan tüm programlama yazılımlarını kurmanız ve yapılandırmanız gerekir.

• PDF oluşturmak istiyorsanız LaTeX yardımcı programlarını yüklemeniz ve yapılandırmanız gerekir.
• olarak org-mod kadar iyi biliyorsun değil ipython notebooksya Sweavemuhtemelen Okur Programlama işlevselliği 2008 yılında eklenmiştir rağmen birçok iş ilanları olarak görmez böylece.
• Kuruluş kipi biçimlendirme sözdizimini öğrenme
• Org modu ile çalışan diğer havalı araçlardan en iyi şekilde yararlanmak istiyorsanız, gnu emacs veya spacemac'ların nasıl kullanılacağını potansiyel olarak öğrenme.

Tam açıklama: Atom editörünün kuruluş modu paketinin ana koruyucusuyum.

---

Bu
yanıttaki kod aşağıdakiler kullanılarak doğrulandı: emacs sürüm: GNU Emacs 25.2.1
org-mode sürüm: 9.1.2