Модуль 4. FAIR4RS, цитирование и артефакты публикации

Принципы FAIR были сформулированы для данных. Перенести их на код напрямую нельзя: как мы видели в модуле 2, ПО – не разновидность данных. Адаптация заняла несколько лет и прошла через три этапа.

Сначала Лампрехт и коллеги поставили вопрос о FAIR для исследовательского ПО и наметили, какие из исходных принципов требуют переосмысления. Затем Кац и коллеги «свежим взглядом» пересмотрели формулировки: они предложили уточнить ряд принципов и добавить новые, отражающие специфику кода – гранулярность объекта, ограниченность истории в системе контроля версий, необходимость признавать вклад участников разработки (контрибьюторов). Наконец, рабочая группа FAIR4RS под руководством Баркера опубликовала итоговый свод – принципы FAIR применительно к исследовательскому ПО (FAIR for Research Software, FAIR4RS).

Суть адаптации в том, что в отношении кода ставятся те же четыре цели, что в случае данных, – находимость, доступность, совместимость, пригодность к повторному использованию, – но достигаются они иначе. Находимость требует идентификатора не только для проекта, но и для каждой версии. Доступность означает, что ПО и его метаданные извлекаются по идентификатору через стандартизированный протокол; исполнимость же относится прежде всего к группе R, где ПО определяется как пригодное и к запуску, и к повторному использованию. Совместимость означает машиночитаемые метаданные о зависимостях и интерфейсах. Пригодность к повторному использованию включает лицензию, документацию, сведения о происхождении кода (provenance) и соответствие стандартам сообщества.

Принципы FAIR4RS с их программной спецификой приведены в таблице.

Таблица. Принципы FAIR4RS и их специфика для программного обеспечения (по Barker et al., 2022)

Находимость (F) требует устойчивой идентификации и регистрации: код нужно не только депонировать, но и зарегистрировать так, чтобы его можно было найти, причем на уровне конкретной версии. Доступность (A) отвечает за извлечение ПО и метаданных по идентификатору через стандартизированный протокол, а не за работоспособность программы: пригодность к запуску отнесена в своде к группе R, которая определяет ПО как usable и reusable – и исполняемое, и пригодное к повторному использованию. Принцип A2 особо подчеркивает, что метаданные должны пережить сам код, ведь код обрушивается чаще, чем устаревают форматы данных. Совместимость (I) требует, чтобы код обменивался данными по принятым в предметной области стандартам (I1) и содержал квалифицированные ссылки на связанные объекты (I2). Пригодность к повторному использованию (R) – самая объемная группа: она охватывает лицензию (R1.1), происхождение кода (R1.2), квалифицированные ссылки на другое ПО, то есть зависимости (R2), и соответствие стандартам сообщества (R3).

Свод FAIR4RS 1.0 приведен полностью. Сами авторы свода подчеркивают, что принципы носят рекомендательный характер: это ориентиры, а не обязательный чек-лист. Третий столбец – возможные операционализации, предлагаемые в курсе; в нормативную формулировку FAIR4RS они не входят и зависят от типа программного объекта, дисциплины, прав и режима доступа. Важно и то, что FAIR-готовность не тождественна открытости: FAIR4RS допускает ограничения доступа там, где они необходимы по правовым, этическим или связанным с безопасностью причинам, при условии, что эти ограничения явно описаны.

Принципы FAIR4RS отвечают на вопрос, как сделать код находимым и пригодным к использованию. Проблема цитирования связана со смежным вопросом: как сослаться на код так, чтобы автор получил признание, а читатель смог найти именно ту версию, с помощью которой получены результаты. Параллельно с FAIR4RS сообщество FORCE11 выработало принципы цитирования ПО. Их шесть: значимость (код следует считать полноценным научным продуктом, достойным цитирования); признание вклада (цитирование закрепляет заслуги авторов и контрибьюторов); уникальная идентификация (через машиночитаемый постоянный идентификатор); устойчивость (идентификатор и метаданные сохраняются, даже если код перестал работать); доступность (по идентификатору можно добраться до самого кода или его метаданных); специфичность (ссылка указывает на конкретную версию).

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

• Concept DOI – общий идентификатор проекта, который всегда приводит на актуальную версию. Он удобен, когда нужно сослаться на программу «вообще».
• Version DOI – идентификатор конкретного релиза. Именно его указывают, когда сообщают, с помощью какой версии получены опубликованные результаты.

Связать платформу разработки с научной инфраструктурой цитирования помогают два связующих формата. Файл CITATION.cff (Citation File Format) помещается в корень репозитория и в человеко- и машиночитаемом виде сообщает, как цитировать код: авторы и их идентификаторы ORCID, название, версия, лицензия. Формат CodeMeta описывает метаданные кода в машиночитаемом виде (JSON-LD) и служит основой для преобразования между схемами DataCite и schema.org. Друскат и коллеги показали, как эти форматы можно собирать автоматически в конвейере непрерывной интеграции (проект HERMES): метаданные извлекаются из репозитория, проверяются, преобразуются и депонируются с присвоением DOI – публикация кода «по нажатию кнопки».

Принцип F4 требует, чтобы метаданные кода были пригодны для поиска и индексирования, – на практике это означает регистрацию кода в доступной инфраструктуре. Здесь полезно различать три рода инфраструктур, которые часто путают:

• Репозиторий хранит сам артефакт и его метаданные и обычно присваивает DOI: Zenodo, Figshare. Это место, откуда код скачивают и на которое ссылаются.
• Архив обеспечивает долгосрочную сохранность исходного кода: Software Heritage сохраняет код и вычисляет идентификатор SWHID (с 2025 года – международный стандарт ISO/IEC 18670) прямо из его содержимого, привязывая ссылку к точному состоянию исходника.
• Реестр индексирует и описывает код, отсылая к месту хранения, и повышает находимость внутри дисциплины: ASCL в астрофизике, swMath в математике, bio.tools и BioContainers в науках о жизни.

Один и тот же программный объект, как правило, попадает во все три: «живой» код развивается на платформе разработки (GitHub, GitLab), снимок релиза депонируется в репозиторий с присвоением DOI, исходник сохраняется в архиве, а запись о нем заносится в реестр дисциплины. Для устойчивой идентификации эти средства дополняют друг друга: DOI отвечает за цитирование и связь версий, SWHID – за сохранность конкретного состояния кода, идентификаторы реестров – за находимость в предметной области.

Чтобы реестры и репозитории были пригодны для курирования, рабочая группа FORCE11 сформулировала девять рекомендуемых практик: публичная политика приема (scope statement); руководство для пользователей; руководство для контрибьюторов; политика авторства; документированная и версионированная схема метаданных (с кросс-конвертацией к CodeMeta и schema.org); условия использования; политика приватности; политика хранения; политика завершения жизненного цикла. Эти девять практик – готовый ориентир для библиотекаря, который настраивает институциональный репозиторий под прием кода.

Принципы FAIR4RS и цитирования задают цели. Чтобы превратить цели в проверяемый перечень, соотнесем их с практическими рекомендациями и сведем в рамку из тринадцати категорий артефактов публикации кода. Рамка предлагается в курсе и не является ни официальным профилем FAIR4RS, ни универсальным обязательным минимумом. Построена она так: взяты практики, которые сквозным образом повторяются в сводах рекомендаций по работе с исследовательским ПО, каждая проверена на то, что ее наличие или отсутствие можно установить по тексту документа или по репозиторию, и близкие практики объединены в одну категорию. Отсюда и разнородность перечня: в нем соседствуют файлы (LICENSE, CITATION.cff), процессы (тестирование, рецензирование), инфраструктура (контроль версий, архив) и способ упаковки (контейнер) – объединяет их не природа, а проверяемость. Этот набор работает и как чек-лист для исследователя, готовящего код, и как кодировочная схема для анализа политик, к которому мы обратимся в модуле 5.

Таблица. Категории практик публикации и сопровождения исследовательского ПО

Столбец «Консенсус» – качественная оценка того, насколько устойчиво практика присутствует в рассмотренных сводах рекомендаций: «высокий» – практика есть в большинстве сводов, «средний» – в нескольких ключевых, «новый» – практика обсуждается, но еще не стала общепринятой нормой в институциональных политиках.

Тринадцать категорий распадаются на три слоя. Первые шесть (LIC–CIT) образуют слой идентификации и лицензирования: они отвечают на вопросы «чье это, где это и как на это сослаться». Следующие четыре (DOC–TEST) – слой воспроизводимости: они обеспечивают возможность понять, установить и проверить код. Последние три (CONT–CONTR) – слой устойчивости: они отвечают за то, чтобы код пережил окружение и оставался открытым для сообщества. Разберем категории по слоям подробнее.

Слой идентификации и лицензирования. Открытая лицензия (LIC) делает код юридически пригодным к использованию: без файла LICENSE действует «все права защищены», и формально код нельзя ни копировать, ни модифицировать. Контроль версий (VCS) фиксирует историю изменений и через публичный хостинг делает код доступным; это фундамент, на котором держатся версионирование и цитирование. Версионирование (VER) присваивает релизам понятные номера и теги, без которых нельзя однозначно сослаться на состояние кода. Постоянный идентификатор (PID) – DOI или SWHID – дает устойчивую ссылку, которая переживает перемещение или удаление репозитория разработки – при условии, что сохраняются сама архивная запись и депонированный объект. Архивирование (ARC) помещает код в долгосрочное хранилище, а не оставляет его на платформе разработки, которую автор может закрыть. Стандарты цитирования (CIT) через файл CITATION.cff сообщают, как ссылаться на код, обеспечивая авторам признание.

Слой воспроизводимости. Документация (DOC) – минимум в виде README – объясняет, что делает код, как его установить и запустить; без нее даже работающий код бесполезен для другого человека. Структурированные метаданные (META) в формате codemeta.json делают описание машиночитаемым и пригодным для обмена между системами. Зависимости (DEP) фиксируют внешние библиотеки и окружение с точными версиями; без этой фиксации код тем вероятнее перестанет запускаться, чем сильнее изменится окружение. Тестирование и непрерывная интеграция (TEST) позволяют убедиться, что код работает как задумано, и автоматически перепроверять это при изменениях.

Слой устойчивости. Контейнеризация (CONT) упаковывает код вместе с окружением, решая проблему несовместимости сред; для сложного предметного ПО это одно из самых действенных средств, хотя и не гарантия: контейнер сам зависит от базовых образов, реестров и архитектуры. Рецензирование кода (REV) добавляет внешнюю экспертную проверку самого ПО – так работают JOSS и rOpenSci. Руководство для контрибьюторов (CONTR) и кодекс поведения открывают проект для сообщества и обеспечивают его жизнь за пределами первоначальной команды.

Почему эти артефакты – не формальность, показывают измерения. Мартин дель Пико и коллеги, рассчитав показатели FAIR-готовности для десятков тысяч программных инструментов в науках о жизни, обнаружили, что менее половины из них указывают лицензию, а систему контроля версий публично использует лишь четверть. Иными словами, даже базовые категории LIC и VCS на практике покрыты далеко не всегда – и именно здесь помощь библиотеки наиболее ощутима.

Перечень из тринадцати категорий можно превратить в измеримые показатели. Мартин дель Пико и коллеги в системе FAIRsoft (на платформе OpenEBench) автоматически вычисляют индикаторы наличия версии, лицензии, описания, ссылок на репозиторий, форматов входов и выходов, тестов и зависимостей. Цех и Пекарич предложили «функции пригодности» (fitness functions) – исполняемые проверки, привязанные к измерениям FAIR: наличие идентификатора и регистрации отвечает за находимость, стандартные протоколы и сохранность – за доступность, стандартные форматы и спецификация окружения – за совместимость, а лицензия, манифесты зависимостей, документация, версионированные релизы и тесты – за пригодность к повторному использованию. Для библиотеки такие проверки удобны как инструмент входного контроля при депонировании: оценка качества становится проверяемой, а не субъективной.

Не все тринадцать категорий одинаково применимы ко всем типам кода. Скрипт из пятидесяти строк не нуждается в контейнере Docker, тогда как зрелая библиотека не обходится без тестов и CI/CD. Соотнесем артефакты со слоями иерархии C1–C4. Эта матрица – продолжение логики триажа из модуля 4: по ней видно, чего разумно требовать, а чего нет, в зависимости от типа объекта.

Таблица. Рекомендуемый уровень артефактов по слоям иерархии

R – практика рекомендуется как обязательная для этого типа, E – желательна, N – не критична. Рекомендации столбца C1–C2 относятся к программным объектам, которые организация разрабатывает или сопровождает. Для внешних компонентов уровня C1 – операционных систем, компиляторов, СУБД – организация обычно не является ни разработчиком, ни правообладателем: для них фиксируются версия, источник, идентификатор и роль в окружении, а курирование самого продукта не предполагается.

Читать матрицу следует по столбцам. Для проектного кода C4 обязательны лицензия, контроль версий, идентификатор снимка версии, архивирование, цитирование и фиксация зависимостей; документация достаточна на уровне README, а контейнеризация, рецензирование и руководство для контрибьюторов, как правило, избыточны. Для предметного ПО C3 поднимается планка документации, тестирования и метаданных. Для инфраструктуры C1–C2 на первый план выходят расширенная документация интерфейсов, обширное тестирование, рецензирование в сообществе и работа с контрибьюторами, тогда как сам идентификатор и архивирование уже обеспечиваются иначе.

Библиотеке, которая только начинает работу с кодом, не нужно сразу внедрять все тринадцать категорий. Разумно опереться на шесть базовых, в отношении которых в литературе сложился наиболее прочный консенсус (столбец «высокий» в таблице): лицензия (LIC), постоянный идентификатор (PID), архивирование (ARC), документация (DOC), контроль версий (VCS) и цитирование (CIT). Эти шесть составляют тот минимум, с которого имеет смысл начинать обучение исследователей и выстраивание сервиса. Освоив их, можно переходить к среднему слою (версионирование, зависимости, тестирование, рецензирование) и далее к практикам устойчивости. Именно по такой траектории – от базового уровня к продвинутому и экспертному – удобно строить и образовательные программы (см. модуль 7).

Резюме

Принципы FAIR были адаптированы к коду в три этапа и образовали свод FAIR4RS: те же четыре цели, что у данных, но достигаемые иначе – с идентификацией версий, разделением доступности и работоспособности, машиночитаемыми метаданными и вниманием к лицензии и происхождению кода. Цитирование ПО (FORCE11) опирается на шесть принципов, среди которых специфичность – ссылка на конкретную использованную версию; двухуровневая схема concept DOI и version DOI – реализация этого требования в Zenodo; связать разработку с научной инфраструктурой помогают CITATION.cff и CodeMeta. Предлагаемая рамка из тринадцати категорий практик операционализирует все это в проверяемый перечень, распадающийся на три слоя – идентификации, воспроизводимости и устойчивости. Артефакты дифференцируются по типам ПО (C1–C4), а начинать разумно с шести базовых категорий.

Ключевые термины

• FAIR4RS – принципы FAIR применительно к исследовательскому ПО.
• Принципы цитирования ПО (FORCE11) – шесть принципов: значимость, признание вклада, уникальная идентификация, устойчивость, доступность, специфичность.
• Concept DOI / version DOI – идентификатор проекта в целом и идентификатор конкретной версии.
• CITATION.cff – машиночитаемый файл цитирования в корне репозитория.
• CodeMeta – схема машиночитаемых метаданных кода (JSON-LD), основа преобразования между схемами метаданных.
• SWHID – идентификатор Software Heritage, вычисляемый из содержимого кода.
• Рамка из тринадцати категорий – предлагаемый перечень практик публикации кода, служащий чек-листом для триажа и кодировочной схемой анализа политик.
• Три слоя артефактов – идентификации и лицензирования; воспроизводимости; устойчивости.

1. Почему принципы FAIR для данных нельзя перенести на код без переработки? Что нового внесли Кац и коллеги?
2. Истолкуйте принцип A2 FAIR4RS. Почему для кода он особенно важен?
3. В каком случае исследователь указывает version DOI, а не concept DOI?
4. Распределите тринадцать категорий по трем слоям. Какие шесть составляют минимум для старта и почему?

1. Возьмите принципы из таблицы FAIR4RS и сопоставьте каждый с одной или несколькими из тринадцати категорий артефактов. Где соответствие однозначно, а где принцип покрывается несколькими категориями?
2. Для трех разных программных объектов (по одному из C2, C3, C4) определите рекомендуемый набор артефактов и кратко обоснуйте различия.
3. Изучите файл CITATION.cff в любом известном открытом проекте и оцените, какие из принципов цитирования FORCE11 в нем реализуются.