Что было бы наиболее полезным способом написания кода для статьи, чтобы читатели могли четко сопоставить результаты с кодом, который их генерирует?

Я пишу воспроизводимую статью, и в ней есть результаты вычислений, которые генерируются скриптом Python (аналогичный скрипт MATLAB генерирует почти идентичные результаты). Я чувствую, что статья будет легче понять читателям, если они смогут сопоставить вычисления в статье с вычислениями в коде. В работе предлагается абстрактный формализм, и примеры в статье должны сделать этот формализм более конкретным для читателей (многие из которых будут инженерами); код, вероятно, будет самой подробной записью о том, как выполнять расчеты, и разъяснение может помочь нам в процессе проверки.

Есть ли у кого-нибудь предложения о том, как сделать более понятным соответствие между кодом и результатами вычислений (рисунками, уравнениями)?

Например, я думал, что когда дело доходит до строк кода, реализующих различные шаги в статье, я мог бы приводить числа уравнений (было бы удивительно, если бы я мог перекрестно ссылаться между кодом и LaTeX, но маркировка их вручную - это хорошо) и я мог бы написать функции, соответствующие различным примерам и рисункам, таким как

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

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

Если бы код был большим, и я не пытался объяснить, как куча различных математических методов, используемых в разработке, были на самом деле одинаковыми, я бы, наверное, не стал бы сильно беспокоиться о том, чтобы сделать код понятным, но учитывая абстрактный характер бумага и небольшая база кода, кажется, что в этом упражнении может быть что-то полезное.

1. Вы можете написать всю статью в Новебе . Это немного утомительно, но очень мощный способ смешать код и текст в формате LaTeX, уравнения и цифры. Для длинных программ он имеет тенденцию превращать ваш код в книгу, а не в статью, но для коротких программ это может сработать довольно хорошо.

2. Если вы не хотите заходить так далеко, все же должно быть достаточно просто отформатировать секции комментариев ваших списков кода с использованием LaTeX. listingsПакет может помочь вам осуществить это. Вот короткий пример:

\ Documentclass {статья}
\ Usepackage {amsmath}
\ usepackage {} объявлений
\ Начать {документ}
\ {Начинают уравнение}
  \ Метка {эк: один}
  Ах = Ь
\ Конец {} уравнение
\ {Начинают lstlisting} [escapechar = \%]
  # Комментарий со ссылкой на уравнение% ~ \ eqref {eq: one}%
  def f (a):
    вернуть + 1
\ Конец {lstlisting}
\ Конец {документ}

С некоторыми дополнительными манипуляциями вы должны быть в состоянии заставить номера ваших ссылочных уравнений появляться в моноширинном шрифте, который он использует для перечисления уравнения.

Подход noweb, упомянутый Биллом, эволюционировал совсем немного, как в своем первоначальном духе документирования кода (а не научной публикации) под термином « грамотное программирование», так и сейчас он имеет много разновидностей (я думаю, что noweb изначально был обобщением cweb), какие doxygenи различные языковые версии могут генерировать документацию в TeX, HTML и других форматах.

К вашему сведению, noweb был разработан в течение некоторого времени в Rсообществе (ну, первоначально это Sсообщество, отсюда и название) под названием «Sweave» с целью предоставить документ «Воспроизводимые исследования», где код фактически запускается, когда латексный файл скомпилирован (и при желании также отображается). В Sweave написано довольно много научных работ (включая, я полагаю, весь R-журнал; см. Также журнал биостатистики и его политику в отношении воспроизводимых статей).

Хотя Sweave по-прежнему является частью любой базовой установки R, его заменяет knitr, который теперь не зависит от языка , что делает его возможным выбором для вашего кода Python. Knitr поддерживает запись в LaTeX или уценке, поддерживает подсветку синтаксиса, кэширование, экстернализацию кода из исходного латекса и многие другие желательные функции для такого рода работы.

У Python есть свои собственные решения, похожие на ноутбуки ipython , которые могут отображать в HTML, возможно, в LaTeX, но я об этом знаю меньше.

Другой проект, безусловно, заслуживающий внимания, это dexyit , еще одна не зависящая от языка программа, которая прекрасно работает с LaTeX и HTML. Хотя в документации больше примеров, чем в написании научных работ, работа в LaTeX должна быть простой.

И то, knitrи другое dexyitбудет делать именно то, что вы описываете в LaTeX, включая указание на внешний скрипт на python и чтение в коде. Подобные вещи могут быть выполнены в DocBook и XML, хотя я менее знаком с этим подходом.

Пакет Латекс чеканились обеспечивает очень широкую подсветку синтаксиса (на основе Pygments) и позволяет перекрестных ссылок в обоих направлениях. Вы можете перейти в LaTeX из части кода (отчеканенной части) и можете ссылаться в основном тексте на строки кода. Кроме того, он предоставляет среду списков, так что вы можете создать «список списков» (например, список таблиц) и позволяет ссылаться на все списки. Смотрите LaTeX MWE и его вывод с LuaLaTeX ниже (не судите код :-)).

Другой вариант - использовать PythonTeX от того же автора / сопровождающего, который позволяет выполнять вычисления при компиляции исходного кода LaTeX, поэтому результаты на бумаге и в коде всегда генерируются вместе и, следовательно, всегда связны. Смотрите галерею 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 .

Большинство пользователей режима org стремятся сосредоточиться исключительно на встроенных функциях управления проектами / временем или на возможности экспортировать документы в несколько популярных форматов файлов, например 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

Pros

• Поддержка более 30 языков программирования , включая R, Python, Ruby, Perl, C, C ++, Java, Clojure, Javascript, Common Lisp, Shell, SQL, ...

• Способность к:

  • Захват 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блоки в любое место файла org-mode для удобства чтения и используйте :tangleзаголовок или код экспорта во внешние исходные файлы.

• Проект с открытым исходным кодом - как бесплатный, как пиво, так и бесплатный.

• Формат текстового файла прекрасно работает с программным обеспечением для контроля версий, таким как git.
• Лакомство других функций, в которые я не буду вдаваться, потому что этот ответ становится длинным.

Cons

• Необходимо установить и настроить gnu emacs для использования org-mode.

  Примечание. Большинство из вас перестали читать этот ответ после прочтения gnu emacs. Для оставшихся храбрых душ вы можете использовать ваш любимый текстовый редактор и просто вызывать emacs для обработки файлов режима org из командной строки.

• Необходимо установить и настроить все необходимое программное обеспечение для программирования.

• Нужно установить и настроить утилиты LaTeX, если вы хотите создавать PDF-файлы.
• Режим org не так хорошо известен, как ipython notebooksи Sweaveвы, вероятно, не увидите столько сообщений о вакансиях, даже если в 2008 году была добавлена ​​функция Literate Programming.
• Изучение синтаксиса разметки в режиме орг.
• Потенциально узнаете, как использовать gnu emacs или spacemacs, если хотите получить максимальную отдачу от других крутых инструментов, работающих с org-mode.

Полное раскрытие: Я основной хранитель орг-режим пакета для редактора Atom.

---

Код в этом ответе был проверен с использованием:
emacs version: GNU Emacs 25.2.1
org-mode version: 9.1.2