Software zitieren#

James Howison und Julia Bullard führten in ihrem 2016 veröffentlichten Artikel Software in the scientific literature folgende Beispiele in absteigender Reputation auf:

zitieren von Veröffentlichungen, die die jeweilige Software beschreiben
zitieren von Bedienungsanleitungen
zitieren der Software-Projekt-Website
Link auf eine Software-Projekt-Website
erwähnen des Software-Namens

Die Situation bleibt für die Autor*innen von Software dennoch unbefriedigend, zumal wenn sie sich von den Autor*innen der Software-Beschreibung unterscheiden. Umgekehrt ist Forschungssoftware leider auch nicht immer gut geeignet um zitiert zu werden. So werden andere eure Software kaum direkt zitieren können, wenn ihr ihnen die Software als Anhang von E-Mails schickt. Auch ein Download-Link ist hier noch nicht wirklich zielführend. Besser stellt ihr einen Persistent Identifier (PID) bereit, um die langfristige Verfügbarkeit eurer Software sicherzustellen. Sowohl Zenodo- als auch das figshare-Repository akzeptieren Quellcode einschließlich Binärdateien und stellen Digital Object Identifier (DOI) hierfür bereit. Gleiches gilt für CiteAs, mit dem sich Zitierinformationen für Software abrufen lassen.

Siehe auch

Should I cite?
How to cite software “correctly”
Daniel S. Katz: Compact identifiers for software: The last missing link in user-oriented software citation?
Neil Chue Hong: How to cite software: current best practice
Recognizing the value of software: a software citation guide
Stephan Druskat, Radovan Bast, Neil Chue Hong, Alexander Konovalov, Andrew Rowley, Raniere Silva: A standard format for CITATION files
Module-5-Open-Research-Software-and-Open-Source
Software Heritage: Save and reference research software
Mining software metadata for 80 M projects and even more
Extensions to schema.org to support structured, semantic, and executable documents
Guide to Citation File Format schema
schema.json

Erstellen eines DOI mit Zenodo#

Zenodo ermöglicht die Archivierung von Software und die Bereitstellung eines DOI für diese Software. Im Folgenden werde ich am Beispiel des Jupyter-Tutorials zeigen, welche Schritte hierzu erforderlich sind:

Wenn ihr noch keinen Account für Zenodo habt, erstellt einen, bevorzugt mit GitHub.
Aktiviert in Upload ‣ New Upload unter Basic information den Button Reserve DOI um einen DOI für euren Upload zu reservieren. Lasst das Formular offen um später eure Software hochladen zu können.
Erstellt oder ändert die CodeMeta- und Citation File Format-Dateien in eurem Software-Verzeichnis.

Bindet den Badge in der README-Datei eurer Software ein:

Markdown:

[![DOI](https://zenodo.org/badge/307380211.svg)](https://zenodo.org/badge/latestdoi/307380211)

reStructedText:

.. image:: https://zenodo.org/badge/307380211.svg
   :target: https://zenodo.org/badge/latestdoi/307380211

Nun wählt das Repository aus, das ihr archivieren wollt:
Überprüft, ob Zenodo einen Webhook in eurem Repository für das Releases-Event erstellt hat:
Erstellt ein neues Release:
Überprüft, ob der DOI korrekt erstellt wurde:

Metadaten-Formate#

Die FORCE11 -Arbeitsgruppe hat ein Paper veröffentlicht, in denen Prinzipien des wissenschaftlichen Software-zitierens dargelegt werden: Arfon Smith, Daniel Katz, Kyle Niemeyer: FORCE11 Software Citation Working Group, 2016. Dabei kristallisieren sich aktuell zwei Projekte für strukturierte Metadaten heraus:

CodeMeta#

CodeMeta ist ein Austauschschema für allgemeine Software-Metadaten und Referenzimplementierung für JSON for Linking Data (JSON-LD).

Dabei wird eine codemeta.json-Datei im Stammverzeichnis des Software-Repository erwartet. Die Datei kann z.B. so aussehen:

{
    "@context": "https://doi.org/10.5063/schema/codemeta-2.0",
    "@type": "SoftwareSourceCode",
    "author": [{
        "@type": "Person",
        "givenName": "Stephan",
        "familyName": "Druskat",
        "@id": "http://orcid.org/0000-0003-4925-7248"
    }],
    "name": "My Research Tool",
    "softwareVersion": "2.0",
    "identifier": "https://doi.org/10.5281/zenodo.1234",
    "datePublished": "2017-12-18",
    "codeRepository": "https://github.com/research-software/my-research-tool"
}

Siehe auch

Citation File Format#

Citation File Format ist ein Schema für Software-Citation-Metadaten in maschinenlesbarem YAML-Format. Dabei sollte eine Datei CITATION.cff im Stammverzeichnis des Software-Repository abgelegt werden. Der Inhalt der Datei kann z.B. so aussehen:

cff-version: "1.1.0"
message: "If you use this tutorial, please cite it as below."
authors:
  -
    family-names: Schiele
    given-names: Veit
    orcid: "https://orcid.org/https://orcid.org/0000-0002-2448-8958"
identifiers:
  -
    type: doi
    value: "10.5281/zenodo.4147287"
keywords:
  - "data-science"
  - jupyter
  - "jupyter-notebooks"
  - "jupyter-kernels"
  - ipython
  - pandas
  - spack
  - pipenv
  - ipywidgets
  - "ipython-widget"
  - dvc
title: "Jupyter tutorial"
version: "0.8.0"
date-released: 2020-10-08
license: "BSD-3-Clause"
repository-code: "https://github.com/veit/jupyter-tutorial"

Ihr könnt einfach das obige Beispiel anpassen um eure eigene CITATION.cff-Datei zu erzeugen oder die Website cffinit verwenden.

Mit cff-validator steht euch eine GitHub-Action zur Verfügung, die CITATION.cff-Dateien mit dem R-Paket V8 überprüft.

Es gibt auch einige Tools zum Workflow von CITATION.cff-Dateien:

cff-converter-python konvertiert CITATION.cff-Dateien in BibTeX, RIS, CodeMeta- und andere Dateiformate
doi2cff erstellt eine CITATION.cff-Datei aus einem Zenodo DOI

Auch GitHub bietet einen Service um die Informationen aus der CITATION.cff-Datei eures GitHub-Repository im APA- und BibTex-Format zu kopieren.

Siehe auch

GitHub Docs: About CITATION files

Wenn ihr einen DOI mit Zenodo registriert, wird die CITATION.cff-Datei aus dem GitHub-Repository ebenfalls verwendet. Auch Zotero interpretiert die Citation File Format-Datei in GitHub-Repositories; Zotero kann jedoch auch ohne Citation File Format-Datei Metainformationen des Repository, wie Unternehmen, Programmiersprache etc., übernehmen.

Git2PROV#

Git2PROV generiert PROV-Daten aus den Informationen eines Git-Repository.

Auf der Kommandozeile kann die Konvertierung einfach ausgeführt werden mit:

$ git2prov git_url [serialization]

Zum Beispiel:

$ git2prov git@github.com:veit/python4datascience.git PROV-JSON

Insgesamt stehen die folgenden Serialisierungsformate zur Verfügung:

PROV-N
PROV-JSON
PROV-O
PROV-XML

Alternativ stellt Git2PROV auch einen Web-Server bereit mit:

$ git2prov-server [port]

Siehe auch

HERMES#

HERMES vereinfacht die Publikation von Forschungssoftware, indem kontinuierlich in Citation File Format, CodeMeta und Git vorhandene Metadaten abegrufen werden. Anschließend werden die Metadaten auch für InvenioRDM und Dataverse passend zusammengestellt. Schließlich werden auch CITATION.cff und codemeta.json für die Publikationsrepositories aktualisiert.

.hermes/ in der .gitignore-Datei hinzufügen
CITATION.cff-Datei mit zusätzlichen Metadaten bereitstellen

Wichtig

Stellt sicher, dass license in der Datei CITATION.cff definiert ist; andernfalls wird eure Veröffentlichung von der Zenodo-Sandbox nicht als Open Access akzeptiert.
HERMES-Workflow konfigurieren

Der HERMES-Workflow wird konfiguriert in der TOML-Datei hermes.toml, wobei jeder Schritt einen eigenen Abschnitt erhält.

Wenn ihr HERMES so konfigurieren wollt, dass die Metadaten aus Git und CITATION.cff verwendet werden und die Ablage in der Zenodo Sandbox, die auf InvenioRDM aufbaut, erfolgen soll, sieht die hermes.toml-Datei folgendermaßen aus:
hermes.toml#
```
# SPDX-FileCopyrightText: 2023 Veit Schiele
#
# SPDX-License-Identifier: BSD-3-Clause

[harvest]
from = [ "git", "cff" ]

[deposit]
mapping = "invenio"
target = "invenio"

[deposit.invenio]
site_url = "https://sandbox.zenodo.org"
access_right = "open"

[postprocess]
execute = [ "config_record_id" ]
```
Zugangstoken für Zenodo Sandbox

Damit GitHub Actions euer Repository in der Zenodo Sandbox veröffentlichen kann, benötigt ihr ein persönliches Zugangstoken. Hierfür müsst ihr euch bei der Zenodo Sandbox anmelden, um dann in eurem Benutzerprofil einen persönliches Zugangstoken mit dem Namen HERMES workflow und den Geltungsbereichen deposit:actions und deposit:write zu erstellen:
Kopiert das neu erstellte Token in ein neues GitHub Secret namens ZENODO_SANDBOX in Ihrem Repository: Settings ‣ Secrets and Variables ‣ Actions ‣ New repository secret:
Konfiguriert die GitHub-Aktion

Das HERMES-Projekt stellt Vorlagen zur kontinuierlichen Integration in einem speziellen Repository bereit: hermes-hmc/ci-templates. Kopiert die Vorlagendatei TEMPLATE_hermes_github_to_zenodo.yml in das Verzeichnis .github/workflows/ eures Repository und benennt sie um, z.B. in hermes_github_to_zenodo.yml.

Anschließend solltet ihr die Datei durchgehen und nach Kommentaren, die mit # ADAPT gekennzeichnet sind, suchen. Passt die Datei an eure Bedürfnisse an.

Schließlich fügt ihr die Workflow-Datei zur Versionskontrolle hinzu und schiebt sie auf den GitHub-Server:
```
$ git add .github/workflows/hermes_github_to_zenodo.yml
$ git commit -m ":construction_worker: GitHub action for automatic publication with HERMES"
$ git push
```
GitHub-Actions sollen Pull Requests in eurem Repository erstellen dürfen

Der HERMES-Workflow wird keine Metadaten ohne eure Zustimmung veröffentlichen. Stattdessen erstellt er einen Pull-Request, damit ihr die hinterlegten Metadaten genehmigen oder ändern könnt. Um dies zu aktivieren, geht in eurem Repository zu Settings ‣ Actions ‣ General und aktiviert im Abschnitt Workflow permissions Allow GitHub Actions to create and approve pull requests.