Отчёт о воспроизводимости исследования

Отчёт о воспроизводимости исследования

Воспроизводимость не появляется сама: её нужно описать. Отчёт фиксирует, откуда взялись данные, каким кодом и в каком окружении получен результат. Без него повторный запуск превращается в переписку с авторами. Ниже — что включить.

Зачем отчёт

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

Что описать

Источник данных и версию, шаги обработки, код, окружение, параметры, ожидаемые результаты. Укажите, что запускается вручную. Не ограничивайтесь фразой «анализ проведён в программе».

Какие артефакты

Файлы данных или ссылки на них, код, список версий библиотек, инструкцию запуска, ключевые выходные таблицы. Храните вместе. Укажите, что закрыто по этическим причинам.

Инструкция запуска

Пошагово: что установить, что открыть, что запустить, сколько ждать. Проверьте на чистом компьютере. Укажите типичные ошибки. Это самый полезный раздел.

Где хранить

В репозитории проекта или архиве с постоянным идентификатором. Укажите лицензию и условия доступа. Сделайте резервную копию. Не храните только на личном диске.

Версии

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

Как проверить

Попросите коллегу пройти инструкцию с нуля. Запишите, где он застрял. Исправьте. Повторите. Один успешный повторный запуск лучше десяти обещаний.

Что делать с закрытыми данными

Опишите, как получить доступ и кому он предоставляется. Дайте синтетический пример или схему. Укажите ограничения. Не обещайте открытость, которую не можете обеспечить.

Типичные ошибки

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

Как описать в статье

Раздел о доступности материалов: где данные, где код, как запросить. Коротко, со ссылками. Укажите, что доступно сразу, а что по запросу.

Срок хранения

Уточните требования журнала и учреждения. Обычно несколько лет после публикации. Укажите ответственного. Не удаляйте материалы после сдачи статьи.

Права и лицензии

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

Этика

Удалите личные данные. Проверьте, нет ли идентификаторов в именах файлов. Уточните согласие на публикацию. При сомнении закройте доступ.

Поддержка

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

Проверка

Через полгода попробуйте повторить анализ по своему отчёту. Если не получилось, дополните. Это лучший способ проверить качество.

Как начать

Начните отчёт до окончания анализа, а не после. Так вы не забудете шаги и параметры. Ведите черновик по ходу. В конце останется проверить и дополнить.

Что считать результатом

Перечислите ключевые таблицы и графики, которые должны появиться после запуска. Укажите ожидаемые числа или диапазоны. Это позволяет проверить, что анализ прошёл полностью.

Как описать данные

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

Как описать код

Структура папок, назначение файлов, порядок запуска. Укажите, что запускается вручную. Дайте комментарии к неочевидным шагам. Не оставляйте мёртвых файлов.

Как описать окружение

Операционная система, версии библиотек, настройки. Укажите, где взять список. Проверьте, что он актуален. Обновляйте при изменениях.

Как поступить с долгими расчётами

Опишите время выполнения и требования к памяти. Укажите, можно ли запустить на ноутбуке. Предложите вариант с меньшей выборкой для проверки.

Как проверить на другом компьютере

Попросите коллегу с другой системой пройти инструкцию. Запишите затруднения. Исправьте. Это выявит скрытые зависимости от вашей среды.

Как поддерживать

Назначьте ответственного. Укажите, как сообщать об ошибках. Обновляйте при изменении данных. Отвечайте на запросы. Отчёт без поддержки быстро устаревает.

Как поступить при невозможности открыть данные

Опишите процедуру запроса: к кому, в каком виде, на какой срок. Дайте шаблон. Укажите, что потребуется соглашение. Не обещайте мгновенный доступ.

Как связать со статьёй

Добавьте ссылку в раздел о материалах. Убедитесь, что ссылка работает. Проверьте её перед публикацией и через месяц. Битые ссылки сводят усилия к нулю.

Как поступить с большими файлами

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

Чек-лист

• Данные описаны.
• Код доступен.
• Версии зафиксированы.
• Инструкция проверена.
• Ключевые числа указаны.
• Условия доступа описаны.
• Ответственный назначен.

Частые вопросы

Обязателен ли отчёт?

Всё чаще да; полезен в любом случае.

Что приложить?

Данные или ссылку, код, версии, инструкцию.

Что важнее всего?

Инструкция, проверенная другим человеком.

Пример

Коллега полгода не мог повторить расчёт: в статье не было ни версии данных, ни списка библиотек, а код хранился в переписке. После подготовки отчёта и проверки запуска новым человеком повтор занял полчаса.

Итог

Отчёт о воспроизводимости — это данные, код, версии и инструкция, проверенная на практике.