독자가 결과를 생성하는 코드와 결과를 명확하게 일치시킬 수 있도록 종이 코드를 작성하는 가장 유용한 방법은 무엇입니까?

나는 재현 가능한 논문을 작성하고 있는데,이 논문은 파이썬 스크립트에 의해 생성 된 계산 결과를 가지고 있습니다 (유사한 MATLAB 스크립트는 거의 동일한 결과를 생성합니다). 나는 독자들이 논문의 계산과 코드의 계산을 일치시킬 수 있다면 독자가 이해하기 쉽다고 생각합니다. 이 연구는 추상적 인 형식주의를 제안하고, 논문의 예는이 형식주의를 독자들 (많은 엔지니어가 될 것)에게보다 구체적으로 만들어 주어야한다. 코드는 아마도 계산을 수행하는 방법에 대한 가장 자세한 기록 일 것이므로 명확하게 검토하면 검토 과정에서 도움이 될 수 있습니다.

코드와 계산 결과 (그림, 방정식) 사이의 일치 성을보다 명확하게 만드는 방법에 대한 제안이 있습니까?

예를 들어, 논문의 다양한 단계를 구현하는 코드 라인에서 방정식 번호를 인용 할 수 있다고 생각했습니다 (코드와 LaTeX 간의 상호 참조를 할 수 있다면 놀라운 일이지만 수동으로 라벨링하는 것은 좋습니다) 다양한 예제와 그림에 해당하는 함수를 작성할 수 있습니다.

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

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

코드가 크고 엔지니어링에 사용 된 여러 가지 수학적 방법이 실제로 어떻게 동일한 지 설명하지 않으려는 경우 코드를 명확하게 만드는 데 크게 신경 쓰지 않을 것입니다. 종이와 작은 코드 기반으로,이 연습에서 가치가있는 것처럼 보입니다.

1. Noweb 에서 전체 논문을 작성하는 것을 고려할 수 있습니다 . 설정하는 것은 약간 지루하지만 코드와 LaTeX 형식의 텍스트, 방정식 및 그림을 혼합하는 매우 강력한 방법입니다. 긴 프로그램의 경우 코드를 기사보다 더 많은 책으로 만드는 경향이 있지만 짧은 프로그램의 경우 꽤 잘 작동 할 수 있습니다.

2. 멀리 가고 싶지 않다면 LaTeX를 사용하여 코드 목록의 주석 섹션을 형식화하는 것이 여전히 간단해야합니다. listings패키지에는이 떨어져 당겨 도움이 될 수 있습니다. 다음은 간단한 예입니다.

\ documentclass {article}
\ usepackage {amsmath}
\ usepackage {listings}
\ begin {문서}
\ begin {식}
  \ label {eq : one}
  도끼 = b
\ end {식}
\ begin {lstlisting} [escapechar = \ %]
  # 방정식 % ~ \ eqref {eq : one} %에 대한 주석
  데프 f (a) :
    a + 1을 반환
\ end {lstlisting}
\ end {문서}

몇 가지 추가 조작을 통해 참조 된 방정식 번호를 방정식 나열에 사용하는 고정 폭 글꼴로 표시 할 수 있습니다.

Bill이 언급 한 noweb 접근 방식은 문맹 프로그래밍 이라는 용어로 과학적 출판이 아닌 문서 코드의 원래 정신에서 크게 진화 했으며 현재는 많은 풍미가 있습니다 (처음에는 cweb의 일반화라고 생각합니다). 이는 doxygen다양한 언어 별 버전 텍, HTML 및 기타 형식의 문서를 생성 할 수 있습니다.

요컨대, noweb은 코드가 실제로 실행될 때 "재생 가능한 연구"논문을 제공하기 위해 "Sweave"라는 제목으로 R커뮤니티 (원래 S커뮤니티, 따라서 이름)에서 얼마 동안 개발되었습니다. 라텍스 파일이 컴파일되고 선택적으로 표시됩니다. Sweave로 많은 학술 논문이 작성되었습니다 (모든 R 저널을 포함하지만 생물 통계학 저널과 재현 가능한 논문에 대한 정책 참조).

Sweave는 여전히 기본 R 설치의 일부이지만 다음과 같이 대체됩니다. 현재 언어에 구애받지 않는 knitr 파이썬 코드에 대한 선택을 가능하게합니다. Knitr은 LaTeX 또는 markdown으로의 작성을 지원하여 구문 강조, 캐싱, 소스 라텍스에서 코드의 외부화 및 이러한 종류의 작업에 필요한 기타 여러 가지 기능을 지원합니다.

파이썬에는 HTML, 아마도 LaTeX로 렌더링 할 수있는 비슷한 ipython 노트북 과 같은 자체 솔루션이 있지만 이것에 대해서는 덜 알고 있습니다.

볼만한 가치가있는 또 다른 프로젝트는 dexyit , 라텍스 HTML과 매우 잘 작동 다른 언어에 독립적 프로그램. 과학 논문을 작성하는 것보다 코드를 문서화하는 데 더 많은 예제가 있지만 LaTeX에서 작업하는 것은 간단합니다.

모두 knitr와 dexyit외부 파이썬 스크립트를 가리키는하고 코드 읽기를 포함, 라텍스 설명 정확히 할 것입니다. 이 접근 방식에 익숙하지는 않지만 DocBook 및 XML에서도 비슷한 작업을 수행 할 수 있습니다.

LaTeX 패키지 발행은 (Pygments 기준) 매우 광범위한 신택스 하이라이팅을 제공하며, 양방향 상호 참조 할 수 있습니다. 코드 부분 (부호가있는 부분)에서 LaTeX로 빠져 나갈 수 있으며 본문에서 코드 줄을 참조 할 수 있습니다. 또한 목록 목록과 같은 "목록 목록"을 생성하고 전체 목록을 참조 할 수 있도록 목록 환경을 제공합니다. 아래의 LaTeX MWE 및 LuaLaTeX의 출력을 참조하십시오 (코드를 판단하지 마십시오 :-)).

다른 옵션은 LaTeX 소스를 컴파일하는 동안 계산을 실행할 수있는 동일한 작성자 / 유지 업체의 PythonTeX 를 사용 하는 것이므로 종이와 코드 결과는 항상 함께 생성되므로 항상 일관성이 있습니다. 여기 에서 PythonTeX 갤러리를 참조 하십시오.

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

org-mode 의 Literate Programming 기능을 사용하십시오 .

대부분의 조직 모드 사용자는 기본 제공 프로젝트 / 시간 관리 기능 또는 문서 를 유지 관리하기 쉬운 텍스트 파일 에서 자주 사용되는 여러 파일 형식 (예 : PDF) 으로 문서를 내보내는 기능에만 집중하는 경향이 있습니다.

그러나 org-mode의 가장 큰 특징은 오픈 소스 커뮤니티에서 매달 더 많은 언어를 추가하여 30 개 이상의 언어로 문맹 프로그램을 만들 수 있다는 것입니다.

다음은 Ruby와 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

찬성

• R, Python, Ruby, Perl, C, C ++, Java, Clojure, Javascript, Common Lisp, Shell, SQL 등 30 개가 넘는 프로그래밍 언어 지원

• 할 수있는 능력:

  • SRC블록 결과를 출력 및 / 또는 값으로 캡처 합니다.
  • SRC블록 결과를 코드, 목록, 표, 라텍스, HTML로 형식화
  • SRC블록 변수에 외부 및 내부 데이터를 모두 사용하십시오 .
  • 명명 된 SRC블록 의 출력을 SRC변수 로 블록으로 사용하십시오.
  • 블록 noweb안에 구문을 사용하십시오 SRC.

    전문가 팁 :noweb 구문을 사용 하여 다음을 수행 할 수 있습니다 .

    • 명명 된 SRC블록 에서 코드를 삽입하십시오 ( 예 : func-of-x-and-y다른 SRC블록 안에) .

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

    • 명명 된 SRC블록 의 결과를 삽입합니다 ( 예 : func-of-x-and-y다른 SRC블록 안에)

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

    • SRC가독성을 위해 이름이 지정된 블록을 조직 모드 파일 어디에나 배치하고 :tangle헤더를 사용 하거나 외부 소스 파일로 코드를 내 보냅니다.

• 오픈 소스 프로젝트 – 맥주처럼 자유롭고 자유 롭습니다.

• 텍스트 파일 형식은 git과 같은 버전 제어 소프트웨어에서 잘 작동합니다.
• 이 답변이 오래 걸리기 때문에 들어 가지 않을 다른 기능의 Ooodles.

단점

• 조직 모드를 사용하도록 gnu emacs를 설치하고 구성해야합니다.

  참고 : 대부분의 경우 gnu emacs를 읽은 후이 답변 읽기를 중단했습니다. 남은 용감한 영혼을 위해 좋아하는 텍스트 편집기를 사용하고 명령 행에서 조직 모드 파일을 처리하기 위해 emacs를 호출하면됩니다.

• 필요한 모든 프로그래밍 소프트웨어를 설치하고 구성해야합니다.

• PDF를 만들려면 LaTeX 유틸리티를 설치하고 구성해야합니다.
• 로 조직 모드도 알고있다 ipython notebooks또는 Sweave당신은 아마 글을 읽고 프로그래밍 기능이 2008 년에 추가에도 불구하고 많은 직업 게시물로 표시되지 않습니다 그래서.
• 조직 모드 마크 업 구문 학습
• 조직 모드에서 작동하는 다른 멋진 도구를 최대한 활용하려면 gnu emacs 또는 spacemacs 사용 방법을 잠재적으로 학습하십시오.

전체 공개 : 저는 Atom 편집 기용 org-mode 패키지 의 기본 관리자입니다 .

---

이 답변의 코드는 다음을 사용하여 확인되었습니다.
emacs 버전 : GNU Emacs 25.2.1
org-mode 버전 : 9.1.2