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

34

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

Есть ли хороший способ синхронизировать числовые результаты, которые я цитирую в своих статьях, с результатами, сгенерированными моим кодом? (Здесь я предполагаю, что выполнение кода легко и практично делать всякий раз, когда я хочу обновить свою статью.) Эти числовые результаты не обязательно поддаются табличной форме. Иногда у меня есть таблицы в рукописях, но чаще у меня есть параметры моделирования, перечисленные в виде чисел в уравнениях . Примером будет что-то вроде:

y=(y1,,yn)

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

Я предполагаю, что рисунки - более простой случай: всякий раз, когда документ «собирается» (из исходного кода LaTeX, Markdown, RST и т. Д.), Запускайте процесс сборки, выполняя код. Однако, если бы у людей были более точные предложения по синхронизации данных, сгенерированных моими симуляциями, с моей статьей, я бы хотел их услышать.

Джефф Оксберри
источник

Ответы:

14

Как отмечалось в некоторых комментариях, этот подход уже давно разработан в сообществе R на основе Sweaveи в последнее время knitr. Очевидно, что этот подход имеет недостаток, заключающийся в том, что в данный момент он зависит от языка, но имеет то преимущество, что его регулярно используют в научных работах.

Использование Sweave в реальных публикациях

  • Журнал Biostatistics поощряет эти представления, и помещает Kitemark буквы «R» на научных работах , в которых редактор Воспроизводимости удались запустить код и данные и получить эти результаты.
  • По сути, все публикации в R-Journal основаны на Sweave.

Конечно, чаще всего пользователи Sweave / knitr представляют только окончательный результат в большинство журналов, с личной уверенностью, что методы действительно воспроизводят результаты. Кроме того, Sweave часто используется для создания слайдов для профессиональных бесед и т. Д.

Полезные функции

Чтобы быть полезной на практике, такая система должна иметь определенные особенности. С критической массой пользователей, многие из них хорошо разработаны в knitr. Несколько основных моментов:

  • Кэширование. Запись в таком формате, как markdown или latex, который должен быть скомпилирован для просмотра выходных данных, делает невозможным это, включая код, когда результаты не могут быть кэшированы. Умное кэширование на knitrсамом деле делает отладку интенсивного кода намного проще, чем работу в чистом виде R, поскольку нет необходимости повторно запускать успешные фрагменты.

  • Переключить отображение кода. В официальной публикации можно не желать, чтобы какой-либо основной код был виден на выходе. Между тем часто бывает полезно показать (красиво отформатированный, выделенный синтаксисом) код, который дает результаты в выходном формате, когда вы хотите, чтобы читатель точно увидел, что вы печатаете.

  • Сообщество. Возможно, наиболее убедительным преимуществом этого подхода по сравнению с домашним решением является количество людей, знакомых с моделью и пытающихся ее улучшить.

  • На демонстрационных страницах knitr можно найти множество хороших примеров других функций , в том числе инструментов для «облегченной публикации» или публикации в Интернете. Многие из этих функций помогают сделать этот подход более совместимым с общим рабочим процессом, а не чем-то, что нужно делать только при написании рукописи.

Историческая сноска.

Несмотря на то, что корни в «грамотном программировании» Кнута, как следует из названия, акцент делается совсем по-другому, поскольку грамотное программирование фокусируется на соединении программного кода и документации (в сообществе R эту роль играет Roxygen, которая берет свое начало от другой ветви «грамотное дерево программирования»).

Выходя за пределы

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

Другие подходы

  • Может быть, хотите следить за dexy.it
  • В несколько ином подходе: все большее число экономических статей размещают код, связанный с публикациями на http://www.runmycode.org/ , который повторно запускает анализ в облаке и позволяет настраивать входные параметры или настраивать входные данные.
cboettig
источник
Карл, я некоторое время следил за твоим сайтом, и твой подход к knitr был одним из вдохновителей моего вопроса. Я также некоторое время следил за dexy, потому что Зед Шоу использует его для создания исходного кода для своей книги « Как научиться Python трудным путем» (см. Git repo ). Что мне нравится в dexy в отличие от других подходов грамотного программирования, так это то, что код и текст слабо связаны, что позволяет разумно использовать отладчик.
Джефф Оксберри
Джефф, классно, спасибо за комментарии! Анна Нельсон также верит в разделение. Пользователи R могут выполнить развязку в knitr с помощью экстернализации кода или новой spin()функции. Лично я думаю, что жалобы Грега Уилсона на грамотное программирование довольно устарели. У меня был такой же ужасный опыт, который он описывает с noweb, но эта запутанная отладка просто не существует в современных инструментах. Для грамотного CI используйте doxygen. Knitr легче отлаживать, чем R, благодаря кешированию и обработке окружения.
cboettig
20

То, о чем вы просите, - это грандиозный вызов Эльзивье «Исполняемой бумаги» . Хотя многие подходы были опробованы, ни один из них не настолько убедителен, как могли бы предположить авторы. Вот несколько примеров используемых методов.

Проект Madagascar принимает ваш подход, в скрипте make запускаются симуляции, которые производят рисунки и бумагу одновременно.

IPython Notebook предоставляет документ, который можно выполнить по мере того, как вы читаете и создаете рисунки для вашего сердца. (Я видел плагины для слов, Mathematica и множество других решений, используемых таким же образом)

VisTrails использует подход к сервис-ориентированной архитектуре и предоставляет менеджера «Providence» или «Workflow». По сути, вы регистрируете хуки для кода, а затем создаете рабочий процесс или эксперимент, воспроизводящий вашу работу. Он использовался во многих типах кодов, даже в кластерах HPC. При таком подходе у вас будет возможность повторить эксперименты.

Существует множество подобных решений, но я впечатлен этими тремя. Это сложная проблема, и я считаю, что мы на самом деле даже не близки к решению. Мы даже не можем заставить людей выпустить свой код со своими бумагами, как мы можем ожидать, что они воспроизведут результаты = P

aterrel
источник
В аналогичном ключе есть свист , который я не использую, но интригует в концепции.
dmckee
Проект Мадагаскара показался мне интересным, когда я слушал выступление одного из его авторов. Я на самом деле не пытался использовать его, хотя.
Кен
@dmckee: Я знаю людей, которые добились хороших успехов с Sweave и Knitr . Я опасаюсь грамотного подхода к программированию по тем же причинам, которые Грег Уилсон приводит в Software Carpentry : бумага и код слишком тесно связаны, что затрудняет запуск отладчика в коде (и может помешать проверке). текст).
Джефф Оксберри
Я использую Sweave для этой цели, он работает очень хорошо и совместим с Lyx. Орг-режим еще лучше и поддерживает большинство распространенных языков.
Дэвид Лебауэр
13

У меня не было большого успеха в использовании решений этой проблемы других людей. Я обычно просто хочу что-то простое, что работает для меня и выполняет свою работу. С этой целью я обычно пытаюсь написать один скрипт на python, который отвечает за выполнение всех результатов, анализ выходных данных, а также за построение рисунков / таблиц.

Я пишу свои коды для генерации файлов данных, которые содержат результаты в каком-то текстовом формате. Вы можете избежать повторного запуска этих результатов в своем скрипте, сначала проверив наличие выходного файла (например, в python, используя os.path.isfile ()). Если вы хотите перезапустить результаты, просто удалите файлы данных. Если файлы данных существуют, я запускаю парсер этих файлов. Для этого очень полезен модуль python для регулярных выражений (re).

Затем из проанализированного вывода я создаю рисунки или таблицы. Для таблиц в латексе вы можете написать код для генерации таблицы в отдельный файл (я использую расширение .tbl), а затем включить его в свой файл латекса. Для меня они ключом является использование 1 скрипта Python. Если у меня их много, то мне потом интересно, кто из них и что они делают. Если это описание слишком расплывчато, я могу отправить вам несколько примеров.

Натан Кольер
источник
1
Я делаю такие вещи для фигур уже. Тем не менее, в статьях, которые я пишу, таблицы были бы неестественным форматом для представления данных. Часто я действительно просто хочу включить начальное условие в ODE (так, на самом деле, что-то вроде 4-6 чисел, разделенных запятыми) или целую матрицу чисел как часть правой части уравнения. Мне нравится твоя идея для столов. В тех случаях, которые я упомянул, я считаю, что переформатировать их в виде таблиц было бы неестественно, и я хотел бы включить данные в более естественный формат.
Джефф Оксберри
Натан, ты не против опубликовать примеры? Я использую тот же подход, за исключением того, что я фиксирую текстовые файлы в git и использую git для управления результатами. Затем у меня есть скрипты Python для создания графиков / таблиц. У меня есть один сценарий на график или таблицу.
Ондржей Чертик
Вы также можете перенаправить вывод сценария оболочки прямо в latex с помощью команды \input{|"path-to-script.py"}. Я думаю, что вам лучше поместить все параметры в один файл Python (или любой другой язык, который вам нравится) и использовать параметр командной строки для доступа к нему, как \input{|"path-to-script.py param-name"}. В этом случае вы можете включить файл param в другие скрипты для запуска симуляции. Однако это замедляет компиляцию и имеет некоторые другие отрицательные моменты.
Гелий
7

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

Вот пример (на самом деле подготовленный моим соавтором Ароном Ахмадией).

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

Orgmode Emacs в сочетании с Babel достигает этого. Babel может выполнять фрагменты кода из различных языков программирования и сценариев, например, он может открыть файл, содержащий данные моделирования, и поместить его в таблицу в режиме orgmode, который можно экспортировать в LaTeX (и во многие другие форматы). Требуется много времени, чтобы привыкнуть ко всем комбинациям клавиш в orgmode, но после запуска все происходит автоматически.

Роберт
источник
Мне нравится org-mode; Я использую это для контуров. Я не использовал это с Бабелем. Я должен попробовать это.
Джефф Оксберри
Вот отличный обзор с января 2012 г. J. Stat. Программное обеспечение jstatsoft.org/v46/i03/paper
Дэвид Лебауэр
Я написал учебник, в котором показано, как преобразовать шаблон LaTeX из Европейского физического журнала A (EPJ A) в файл в режиме org.
Мелиоратус
4

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

Вы можете шаблонизировать ваши документы с форматированными строками, чтобы они выглядели так

"we observed a %(fractional_improvement)s increase in ..."

Есть сценарии Python, которые выглядят так

results = {"alpha"                  : run_alpha_computation(...),
           "fractional_improvement" : run_fi_computation(...), 
           ...}

А потом сделать что-то вроде этого

for fn in filenames:
    file = open(fn);      s = file.read();       file.close()
    file = open(fn, 'w'); file.write(s%results); file.close()

Затем вы можете обернуть это в Makefile.

MRocklin
источник
Моей первой мыслью, когда я писал этот вопрос, было решение вроде того, которое вы предложили. Первоначально я думал о чем-то более низком, например, о применении макро-препроцессора, но Python, вероятно, является лучшим (и, безусловно, более читабельным) подходом, тогда система сборки может справиться с постепенным восстановлением результатов.
Джефф Оксберри,
На самом деле это просто базовая реализация чего-то вроде страниц сервера Python. Идея автоматически сгенерированного контента уже давно существует в веб-сообществе. Было бы хорошо видеть, что это мигрирует в академию.
MRocklin
Согласовано. Jinja2 может быть использован, чтобы сделать то, что вы предложили. Фактически, это то, что делает dexy , но с кучей классных фильтров, которые также обрабатывают подсветку синтаксиса и другие различные задачи.
Джефф Оксберри,
4

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

\newcommand{\myresults1}{<value>}

Затем вы можете использовать \inputкоманду, чтобы добавить этот файл в ваш документ, и использовать определенные команды для размещения значений.

Aesin
источник
2

Я работаю на Elsevier. Моя компания начала использовать платформу Collage (разработанную в ответ на выполнимый документ Grand Challenge) в журнальных выпусках, чтобы позволить авторам публиковать куски исполняемого кода со своей статьей. Эта функция позволяет читателям воспроизводить результаты, представленные в статье, и повторно использовать опубликованные материалы для своих собственных исследований. Collage поддерживает широкий спектр открытого и закрытого программного обеспечения; Более подробную информацию можно найти в информационном видео здесь и на веб-сайте Collage Authoring Environment .

Хыльке Коерс
источник
Вторая ссылка не на ту вещь.
Дэвид Кетчон
@Hylke Koers: Вы хотели поставить эту ссылку: collage.elsevier.com ?
Пол
@ Пол: я сделал правки; оригинальная вторая ссылка была на Коллаж Google Group. Возможно, лучшая ссылка была бы на сам Collage, но я сосредоточился на том, чтобы (в основном) сохранить благие намерения поста, удаляя части, которые делали его звучащим рекламно. Не стесняйтесь редактировать пост, как считаете нужным.
Джефф Оксберри