Що було б найкориснішим способом написання коду для паперу, щоб читачі могли чітко співставити результати з кодом, який їх генерує?


14

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

Чи є хтось із пропозицій, як зробити чіткіше відповідність між кодом та результатами обчислень (цифри, рівняння)?

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

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

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

Якби код був великим, і я не намагався пояснити, як купу різних математичних методів, що використовуються в техніці, насправді були однаковими, я, мабуть, не настільки б переймався тим, щоб зробити код зрозумілим, але зважаючи на абстрактний характер папір та невелика база коду, здається, що в цій вправі може бути значення.


1
Ви можете розмістити і код, і цифри на Figshare . Кожен отримає ідентифікатор, подібний до DOI, на який можна звернутися, де це необхідно.
Девід Кетчесон

Програмне забезпечення вимагає постійного обслуговування. Роботи публікуються і на цю дату вони ставлять камінням. Мета чудова, але вона ніколи не спрацює. (Буду радий, що я виявився невірним. Кожен, хто знайде папір старше 5 років, пов’язане з цим програмне забезпечення все ще працює, може викликати мене. Для себе я ніколи не знайшов жодного коду, пов'язаного з папером, який насправді працює, крім "Документи з описом рамки", як-от
біла газета

Відповіді:


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

  2. Якщо ви не хочете йти так далеко, все-таки слід досить просто відформатувати розділи коментарів у списках кодів за допомогою LaTeX. listingsПакет може допомогти вам здійснити це. Ось короткий приклад:

\ documentclass {article}
\ usepackage {amsmath}
\ usepackage {листи}
\ start {документ}
\ початок {рівняння}
  \ label {eq: one}
  Ax = b
\ end {рівняння}
\ start {lstlisting} [escapechar = \%]
  # Коментар із посиланням на рівняння% ~ \ eqref {eq: one}%
  def f (a):
    повернути + 1
\ end {lstlisting}
\ end {документ}

З деякими додатковими маніпуляціями ви повинні мати змогу отримати свої посилані номери рівнянь, які відображатимуться в шрифті монопростіру, який він використовує для перерахування рівняння.


1
Навколишнє середовище lstlisting фактично також дозволяє вказати мову програмування, і вона непогано кольорові коди / стилі кодує різні елементи кожної мови.
Вольфганг Бангерт

Так, я не є великим прихильником його гарненького друку, але Вольфганг має рацію.
Білл Барт

5

Новеб-підхід, згаданий Біллом, розвинувся зовсім небагато, і в його оригінальному дусі документування коду (а не наукової публікації) під терміном грамотного програмування, і зараз він має багато ароматів (я гадаю, що Новеб був спочатку узагальненням веб-сайту), які doxygenта різні мовні версії можуть створювати документацію в TeX, HTML та інших форматах.

До речі, noweb протягом певного часу розроблявся у Rспільноті (ну спочатку Sспільнота, звідси і назва) під назвою "Sweave" з метою надання документа "відтворюваного дослідження", де код насправді працює, коли файл латексу компілюється (і необов'язково відображається також). Досить багато наукових праць написано у Sweave (включаючи, я вважаю, весь журнал R; але дивіться також журнал біостатистики та його політику щодо відтворюваних паперів).

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

У Python є власні рішення, подібні до ноутбуків ipython , які можуть надавати HTML, можливо, LaTeX, але я про це знаю менше.

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

І те, knitrі інше dexyitбуде робити саме те, що ви описуєте в LaTeX, включаючи вказівку на зовнішній скрипт пітона та читання в коді. Подібні речі можна досягти в DocBook і XML, хоча я менш знайомий з цим підходом.


3

Пакет Латекс карбувалися забезпечує дуже широку підсвічування синтаксису (на основі 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}

введіть тут опис зображення


0

Використовуйте функціональність грамотного програмування в org-режимі .

Більшість користувачів OR-режиму схильні орієнтуватися виключно на вбудовану функцію управління проектом / часом або на можливість експорту документів у кілька популярних форматів файлів, наприклад, PDF , з легких для обслуговування текстових файлів.

Однак найкращою особливістю орга-режиму є можливість створювати грамотні програми більш ніж 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

Плюси

  • Підтримка понад 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блоки в будь-якому файлі в органічному режимі, щоб читати, і використовуйте :tangleзаголовок або експортний код у файли зовнішнього джерела.

  • Проект з відкритим кодом - і безкоштовно, і пиво, і безкоштовно.

  • Формат текстового файлу відмінно працює з програмним забезпеченням для управління версіями, наприклад, git.
  • Інші функції, в які я не буду входити, оскільки ця відповідь стає тривалою.

Мінуси

  • Потрібно встановити gnu emacs та налаштувати для використання org-mode.

    Примітка: Більшість з вас перестали читати цю відповідь після того, як ви прочитали gnu emacs. Для відважних душ, які залишилися, ви можете скористатися улюбленим текстовим редактором і просто зателефонувати emacs, щоб обробити файли org-mode з командного рядка.

  • Потрібно встановити та налаштувати все необхідне програмне забезпечення.

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

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


Код у цій відповіді було підтверджено, використовуючи:
версію emacs: GNU Emacs 25.2.1 в
орг-режимі: 9.1.2

Використовуючи наш веб-сайт, ви визнаєте, що прочитали та зрозуміли наші Політику щодо файлів cookie та Політику конфіденційності.
Licensed under cc by-sa 3.0 with attribution required.