Citer un logiciel d'astronomie: exemples de texte en ligne

0
123

Auteurs: Daina Bouquin, Gus Muench, Kelle Cruz, Daniel Chivvis, Edwin Henneken

Daina (@dainabouquin) est le bibliothécaire en chef du Center for Astrophysics, Daniel est assistant de projets numériques à la bibliothèque du CfA et Edwin fait partie de l'équipe ADS du CfA. Gus (@AAS_Publishing) fonctionne pour AAS Journals en tant qu'éditeur de données. Kelle Cruz (@kellecruz) est le rédacteur en chef d'AstroBetter. Ce poste a commencé comme un projet lors de la journée AAS233 Hack Together. Il s'est avéré extrêmement difficile à écrire et a pris de nombreux télécons pour terminer!

Les personnes qui essaient de citer un logiciel peuvent le faire de manière à ne pas accorder de crédit significatif aux auteurs ou à établir des voies d'accès au logiciel lui-même. Si le logiciel n'est pas cité correctement, les auteurs ne bénéficieront pas pleinement de la citation. Dans cet article, nous fournissons des instructions de citation de base, quelques exemples de cas d'utilisation courants et quelques questions à prendre en compte lorsque vous citez un logiciel. Ce message n'est pas complet mais nous l'espérons utile pour les cas d'utilisation les plus courants. De plus, le paysage autour de la citation des logiciels évolue rapidement et la plupart des ressources actuellement disponibles (par exemple, Zenodo, ADS, AAS Journals) ne fournissent pas systématiquement des informations de citation qui sont formatées de la manière que nous recommandons ci-dessous. En conséquence, les auteurs devront souvent apporter quelques modifications et creuser pour que les logiciels soient cités aussi significativement que possible.

Tous les exemples ci-dessous sont également disponibles dans un document d'accompagnement au verso.

Dans le texte

À quoi faites-vous le lien?

Une caractéristique distinctive majeure qui influe sur la façon dont le logiciel peut être cité est de savoir si le logiciel a ou non un identifiant résolvable (par exemple, DOI) ou seulement une URL (par exemple, GitHub). Les DOI sont créés par des organisations dédiées à la conservation à long terme de votre code (par exemple, Zenodo). Citer un logiciel DOI aide à prévenir la pourriture des liens et indique clairement que votre citation concerne un logiciel plutôt qu'un document. Donc, en général, lorsque le logiciel que vous souhaitez citer a à la fois un DOI et une URL, citez le DOI. Vous pouvez également noter l'URL, mais ce n'est pas nécessaire si vous citez le DOI.

Exemple 1:
Dans cet exemple, nous montrons comment faire référence aux logiciels utilisés pour générer les résultats présentés dans un article. La version du logiciel utilisée pour obtenir les résultats doit être archivée dans Zenodo ou dans un autre référentiel d'archivage DOI-minting. Nous montrons également comment pointer vers le logiciel en développement en ligne.

Le logiciel est disponible sur GitHub1 sous un et version est archivé dans Zenodo (Cruz et al.2019).

1. Eudoxus base de code: http://github.com/kelle/eudoxus

footnote { texttt {Eudoxus} codebase: url {http://github.com/kelle/eudoxus}.}

Exemple 2:
Dans cet exemple, nous montrons comment faire référence aux différents scripts et / ou données qui ont été utilisés pour générer des résultats et des chiffres présentés dans un article et qui ne sont pas en cours de développement actif. Les scripts doivent être archivés dans Zenodo ou dans un autre référentiel d'archivage DOI-minting.

Les scripts et les données utilisés pour effectuer l'analyse et générer ce manuscrit sont disponibles sur GitHub2 et archivé à Zenodo (Cruz et al.2019).

2. Documents supplémentaires: http://github.com/kelle/eudoxus-supp

footnote {Documents supplémentaires: url {http://github.com/kelle/eudoxus-supp}.}

Et s'il n'y a pas de DOI?

Si le logiciel n'a pas de DOI, reportez-vous à une URL qui renvoie directement au logiciel lui-même dans la mesure du possible. Citer le code lui-même, par opposition à la documentation ou à un site Web de package, est extrêmement important. Assurez-vous de noter la version du logiciel que vous avez utilisée, une date de sortie s'il n'y a pas de numéro de version disponible ou la date du dernier hachage de validation du code que vous avez utilisé (le hachage de validation est une chaîne de 40 caractères).

Si vous citez un logiciel qui n'a pas de DOI, recherchez les métadonnées de citation dans les fichiers README et autres documentations associées au logiciel. Idéalement, les auteurs du logiciel auront créé un fichier distinct pour spécifier les informations de citation et rendu ce fichier disponible avec leur code source (par exemple, CITATION.cff, CodeMeta.json).

Exemple 3:
Dans cet exemple, nous montrons comment faire référence à et citer des logiciels qui ont des versions versionnées, mais qui n'ont pas de DOI. L'exemple de progiciel n'a pas non plus de citation préférée explicitement définie. Dans cette situation, l'auteur de l'article doit déterminer l'URL la plus appropriée à citer. Le BibTeX pour cette entrée est abordé dans la section suivante.

Version 1.0 d'Oenopides3 a été utilisé pour faire une partie de l'analyse présentée dans ce document (Oenopides Project, 2014).

3. Site Web d'Oenopides: https://bitbucket.org/oenopides

footnote { texttt {Oenopides} site Web: url {http://bitbucket.com/oenopides}.}

Exemple 4:
Dans cet exemple, nous montrons comment faire référence à et citer des logiciels qui n'ont pas de DOI ou de versions versionnées.

Aglaonice4 (consulté le 14 décembre 2014) a été utilisé pour effectuer une partie de l'analyse.

4. Aglaonice au 14 décembre 2014: http://github.com/user/aglaonice/tree/12ao345oeu678

footnote { texttt {Aglaonice} depuis le 14 décembre 2014: url {http://github.com/user/project/tree/12ao345oeu678}.}

Que se passe-t-il si la citation préférée fournie par les auteurs du logiciel ne fait pas directement le lien avec le logiciel lui-même?

Si les auteurs souhaitent que vous citiez un article, citez l'article en plus d'un DOI ou d'une URL qui pointe directement vers la version du logiciel que vous avez utilisée.

Exemple 5:

Hypsicles a été développé pour (Muench et al. 2014). La version 1.2 d'Hypsicles a été utilisée pour analyser nos résultats et est archivée dans Zenodo (Bouquin et al.2019).

Section logiciel

Les logiciels fondamentaux utilisés par de nombreux packages peuvent être cités dans la section des logiciels des revues AAS. Les entrées BibTeX pour ces packages sont fournies sur le wiki: Software.bib.

Exemple 1:

Logiciel: MOOG (Sneden et al.2012), LMFIT (Newville et al.2014), PyRAF (Science Software Branch at STScI 2012), Astropy (Astropy Collaboration et al.2013, 2018), SciPy (Jones et al.2001), Pandas (McKinney 2010), Matplotlib (Hunter 2007).

software {LMFIT citep {lmfit}, PyRAF citep {pyraf}, Astropy citep {astropy: 2013, astropy: 2018}, SciPy citep {Scipy}, Pandas citep {Pandas}, Matplotlib citep {matplotlib} , Numpy citep {numpy}}

Section Références

La section des références d'un document sert de liste de citations formelles qui pointent vers toutes les citations dans le texte utilisées tout au long de ce document. Cela signifie que, bien que les notes de bas de page et les remerciements puissent être utiles, ils ne sont pas capturés comme des citations formelles dans un document. Autrement dit, si quelque chose n'est pas inclus dans la section des références, ce n'est pas une citation.

Les citations de logiciels sont similaires à d'autres types de citations telles que les livres, les revues, etc. Cependant, lorsque vous les ajoutez aux sections de références, certaines informations spécifiques au logiciel sont nécessaires. Cela inclut le ou les auteurs ou créateurs du code en plus du nom du progiciel. La version du logiciel (par exemple, v.01) et sa date de sortie sont également des informations importantes à inclure dans la citation. Notez que dans le cas de projets open source, où le (s) auteur (s) ou créateur (s) sont inconnus ou difficiles à déterminer, utiliser «(Package Name) Project» est tout à fait approprié. De même, l'utilisation de «(Nom de l'entreprise)» suffit pour les projets commerciaux (par exemple, «(Knightware)» pour le package Deep-Sky Planner).

Un identifiant unique pour un package, tel que son DOI, son code bib ou son ID arXiv, est l'une des parties les plus importantes des citations logicielles incluses dans les sections de références. Une URL vers le site Web ou le référentiel numérique du projet (par exemple, GitHub ou GitLab) peut également être utilisée comme identifiant (reportez-vous aux exemples 3 et 4 ci-dessus).

Il existe un type d'entrée @software BibTeX, mais il n'est pas encore largement adopté. Nous vous recommandons donc, sauf indication contraire de votre éditeur, d'utiliser le type d'entrée @misc pour le logiciel.

Exemple 1:
Dans cet exemple, nous montrons une entrée pour un logiciel avec DOI publié par Zenodo. En particulier, nous avons ajouté les champs version, éditeur et mot clé. «Logiciel d'astronomie (1855)» est le concept UAT formel qui doit être entré dans le champ de mot-clé.

Cruz et al. 2014, «Eudoxus», v1.0, Zenodo, doi.10.5281 / zenodo.12345

@misc {eudoxus_key,
auteur = {Cruz, Kelle et Bouquin, Daina et Muench, August et Chivvis, Daniel et Henneken, Edwin},
title = {Eudoxus},
mois = avril,
année = 2019,
doi = {10.5281 / zenodo.12345},
url = {https://doi.org/10.5281/zenodo.12345},
version = {v1.0},
éditeur = {Zenodo},
mots-clés = {Logiciel d'astronomie (1855)}

}

bibitem (Cruz et al. (2019)) {eudoxus_key} Cruz, K. 2019, «Eudoxus», v1.0, Zenodo, doi: 10.5281 / zenodo.12345

Exemple 2:
Dans cet exemple, nous montrons une entrée pour un logiciel sans DOI et sans version de version. La date correspond à la date du code utilisé et l'URL correspond à ce hachage.

Aglaonice Project 2014, «Aglaonice», http://github.com/user/aglaonice/tree/12ao345oeu678

@misc {aglaonice_key,
author = {{Aglaonice Project}},
title = {Aglaonice},
urldate = {2014-12-01},
url = {http://github.com/user/aglaonice/tree/12ao345oeu678},
mots-clés = {Logiciel d'astronomie (1855)}

}

bibitem (Aglaonice Project (2014)) {aglaonice_key} Aglaonice Project 2014, “Aglaonice”, GitHub, url {http://github.com/user/aglaonice/tree/12ao345oeu678}

Exemples de papier complet

Les articles ci-dessous peuvent être utilisés comme exemples à suivre lors de la structuration de vos citations logicielles afin que ADS puisse les capturer.

Exemple de papier complet 1:
Ce document JGRA contient un mélange de citations logicielles appropriées utilisant des DOI Zenodo et des URL de logiciel dans les références:

Burrell, A. G. et al. 2018. «Snakes on a Spaceship — An Overview of Python in Heliophysics». Journal of Geophysical Research (Space Physics) 123 (12): 10,384. https://ui.adsabs.harvard.edu/#abs/2018JGRA..12310384B/abstract

Exemple de papier complet 2:
Ce document ApJ est un bel exemple de la façon de mentionner les logiciels à la fin du document et d'inclure les DOI Zenodo dans vos références:

Berger, Travis A., Andrew W. Howard et Ann Merchant Boesgaard. 2018. «Identification des jeunes hôtes hôtes de la planète Kepler à partir des spectres de lithium de Keck-HIRES». The Astrophysical Journal 855 (2): 115. https://ui.adsabs.harvard.edu/#abs/2018ApJ…855..115B/ abstrait

Asclepias

L'ADS peut désormais capturer les citations de votre logiciel lorsque votre logiciel est correctement cité à l'aide de Zenodo DOI. Cette fonctionnalité résulte d'un projet financé par la Fondation Alfred P. Sloan appelé Asclepias. Les citations de logiciels ne peuvent pas être capturées, sauf si la communauté adopte et normalise des pratiques standard comme celles décrites dans ce post.

Vous avez encore des questions? Veuillez utiliser la section des commentaires ci-dessous ou tweeter à @astrobetter ou l'un des auteurs et nous essaierons de vous aider du mieux que nous pouvons!