Authors: Daina Bouquin, Gus Muench, Kelle Cruz, Daniel Chivvis, Edwin Henneken
Daina (@dainabouquin) is the Head Librarian at the Center for Astrophysics, Daniel is a Digital Projects Assistant at the CfA’s Library, and Edwin is part of the ADS team at the CfA. Gus (@AAS_Publishing) works for AAS Journals as a Data Editor. Kelle Cruz (@kellecruz) is the editor-in-chief of AstroBetter. This post started as a project at the AAS233 Hack Together Day. It ended up being extremely difficult to write and took many telecons to complete!
People trying to cite software may be doing so in ways that do not meaningfully give credit to authors or establish pathways to access the software itself. If software is not cited properly, the authors will not fully benefit from the citation. In this post, we provide some basic citation instructions, a few examples of common use cases, and some questions you should consider when citing software. This post is not comprehensive but hopefully helpful for the most common use cases. Additionally, the landscape around software citation is evolving quickly and most of the currently available resources (e.g., Zenodo, ADS, AAS Journals) do not consistently provide citation information that is formatted in the way we recommend below. As a result, authors will often need to make some edits and do some digging in order for software to be cited as meaningfully as possible.
All of the below examples are also available in a companion overleaf document.
In text
What are you linking to?
One major distinguishing characteristic that impacts how software can be cited is whether or not the software has a resolvable identifier (e.g., DOI) or only a URL (e.g., GitHub). DOIs are minted by organizations dedicated to the long-term preservation of your code (e.g., Zenodo). Citing a software DOI helps prevent link rot and makes it clear your citation is to software rather than a paper. So, in general, when the software you want to cite has both a DOI and a URL, cite the DOI. You can also footnote the URL, but this is not necessary if you cite the DOI.
Example 1:
In this example, we show how to refer to software used to generate results presented in a paper. The version of the software used to obtain the results should be archived in Zenodo or some other DOI-minting archival repository. We are also showing how to point to the in-development software online.
The software is available on GitHub1 under a <OSI approved license> and version <semver> is archived in Zenodo (Cruz et al. 2019).
1. Eudoxus codebase: http://github.com/kelle/eudoxus
\footnote{\texttt{Eudoxus} codebase: \url{http://github.com/kelle/eudoxus}.}
Example 2:
In this example, we show how to refer to the various scripts and/or data which were used to generate results and figures presented in a paper and are not under active development. The scripts should be archived in Zenodo or some other DOI-minting archival repository.
The scripts and data used to perform the analysis and generate this manuscript are available on GitHub2 and archived in Zenodo (Cruz et al. 2019).
2. Supplementary materials: http://github.com/kelle/eudoxus-supp
\footnote{Supplementary materials: \url{http://github.com/kelle/eudoxus-supp}.}
What if there is no DOI?
If the software does not have a DOI, refer to a URL that links directly to the software itself whenever possible. Citing the code itself, as opposed to the documentation or a package website, is extremely important. Be sure to note what version of the software you used, a release date if there is no version number available, or the date of the latest commit hash of the code you used (the commit hash is a 40 character string).
If you are citing software that does not have a DOI, look for citation metadata in README files and other documentation associated with the software. Ideally, the software authors will have created a distinct file to specify citation information and made that file available with their source code (e.g., CITATION.cff, CodeMeta.json).
Example 3:
In this example, we show how to refer to and cite software which has versioned releases, but does not have a DOI. The example software package also does not have an explicitly defined preferred citation. In this situation, the author of the paper must determine which URL is most appropriate to cite. The BibTeX for this entry is discussed in the following section.
Version 1.0 of Oenopides3 was used to do a portion of the analysis presented in this paper (Oenopides Project, 2014).
3. Oenopides website: https://bitbucket.org/oenopides
\footnote{\texttt{Oenopides} website: \url{http://bitbucket.com/oenopides}.}
Example 4:
In this example, we show how to refer to and cite software which does not have a DOI or versioned releases.
Aglaonice4 (accessed on 2014 December 14) was used to do a portion of the analysis.
4. Aglaonice as of 2014 December 14: http://github.com/user/aglaonice/tree/12ao345oeu678
\footnote{\texttt{Aglaonice} as of 2014 December 14: \url{http://github.com/user/project/tree/12ao345oeu678}.}
What if the preferred citation provided by the software authors does not directly link to the software itself?
If the authors want you to cite a paper, cite the paper in addition to a DOI or a URL that points directly to the version of the software you used.
Example 5:
Hypsicles was developed for <specific scope and purpose> (Muench et al. 2014). Version 1.2 of Hypsicles was used to analyze our results and is archived in Zenodo (Bouquin et al. 2019).
Software section
Fundamental software which is used by many packages can be cited in the software section of AAS Journals. The BibTeX entries for these packages are provided on the wiki: Software.bib.
Example 1:
Software: 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}}
References section
The references section of a paper serves as a list of formal citations that point to all of the in-text citations used throughout that paper. This means that, although footnotes and acknowledgments may be useful, they are not captured as formal citations in a paper. Simply put, if something isn’t included in the references section, it’s not a citation.
Software citations are similar to other citation types such as books, journals, etc. However, when adding them to references sections, some software-specific information is needed. This includes the Author(s) or Creator(s) of the code in addition to the software package name. The software version (e.g., v.01) and its release date are also important pieces of information to include in the citation. Note that in the case of open source projects, where the Author(s) or Creator(s) are unknown or difficult to determine, using “[Package Name] Project” is entirely appropriate. Similarly, using “[Company Name]” suffices for commercial projects (e.g., “[Knightware]” for the Deep-Sky Planner package).
A unique identifier for a package, such as its DOI, bibcode, or arXiv ID, is one of the most important parts of software citations included in references sections. A URL to the project’s website or digital repository (e.g., GitHub or GitLab) may also be used as an identifier (refer to Example 3 and 4 above).
A @software BibTeX entry type exists, but it is not yet widely adopted. We therefore recommend that unless otherwise specified by your publisher, use the @misc entry type for software.
Example 1:
In this example, we show an entry for software with DOI published by Zenodo. In particular, we’ve added the version, publisher, and keyword fields. “Astronomy software (1855)” is the formal UAT concept that should be entered into the keyword field.
Cruz et al. 2014, “Eudoxus”, v1.0, Zenodo, doi.10.5281/zenodo.12345
@misc{eudoxus_key,
author = {Cruz, Kelle and Bouquin, Daina and Muench, August and Chivvis, Daniel and Henneken, Edwin},
title = {Eudoxus},
month = apr,
year = 2019,
doi = {10.5281/zenodo.12345},
url = {https://doi.org/10.5281/zenodo.12345},
version = {v1.0},
publisher = {Zenodo},
keywords = {Astronomy software (1855)}
}
\bibitem[Cruz et al.(2019)]{eudoxus_key} Cruz, K.\ 2019, “Eudoxus”, v1.0, Zenodo, doi:10.5281/zenodo.12345
Example 2:
In this example, we show an entry for software with no DOI and no version release. The date corresponds to date of code used and the URL corresponds to that hash.
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},
keywords = {Astronomy software (1855)}
}
\bibitem[Aglaonice Project(2014)]{aglaonice_key} Aglaonice Project\ 2014, “Aglaonice”, GitHub, \url{http://github.com/user/aglaonice/tree/12ao345oeu678}
Full paper examples
The papers below can be used as examples for you to follow when structuring your software citations so that ADS can capture them.
Full Paper Example 1:
This JGRA paper has a mix of proper software citations using Zenodo DOIs and software URLs in references:
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
Full Paper Example 2:
This ApJ paper is a nice example of how to mention software at the end of the paper and include Zenodo DOIs in your references:
Berger, Travis A., Andrew W. Howard, and Ann Merchant Boesgaard. 2018. “Identifying Young Kepler Planet Host Stars from Keck-HIRES Spectra of Lithium.” The Astrophysical Journal 855(2): 115. https://ui.adsabs.harvard.edu/#abs/2018ApJ…855..115B/abstract
Asclepias
The ADS can now capture citations to your software when your software is properly cited using Zenodo DOIs. This functionality results from a project funded by the Alfred P. Sloan Foundation called Asclepias. Software citations cannot be captured though unless the community adopts and normalizes standard practices like those outlined in this post.
Still have questions? Please use the comment section below or tweet at @astrobetter or one of the authors and we’ll try to help out the best we can!
“Software citations cannot be captured though unless the community adopts and normalizes standard practices like those outlined in this post.”
Or by other methods not included in the post. Software citations by ASCL ID have been captured in ADS since 2012, as can be seen on the dashboard: https://ascl.net/dashboard
“Ideally, the software authors will have created a distinct file to specify citation information and made that file available with their source code (e.g., CITATION.cff, CodeMeta.json).”
Yes! And the ASCL can help with that; appending “/codemeta.json” to the URL for any accepted ASCL entry produces a codemeta.json file that can be copied and pasted to one’s code site and edited as needed. For example, ascl.net/1202.015/codemeta.json brings up a codemeta.json file for RADMC-3D. Our hope is that code authors find this a good start for adding codemeta.json files to their sites.
We’re working on doing the same for same for CITATION.cff and will have that available soon.
I had expected at least a mention of ASCL, but I see Alice was ahead of me.
FORCE11 just came out with a new document outlining challenges around software citation (https://arxiv.org/abs/1905.08674). One of the issues we have not yet resolved is how to reconcile citations to things like ASCL registry records. (https://danielskatzblog.wordpress.com/2019/03/05/towards-software-non-creator-instigated-identification-nci-and-citation/). This makes it hard to give generalizable recommendations about them. Happy to talk about how we might tackle some of these!
Guidance on citing software by ASCL ID is here: http://ascl.net/home/getwp/351.
We encourage authors to let us know how they want their software cited (and to make this information easy to find on their code sites/repos!); ASCL records report preferred citation information when we know what the preferred citation is.
The issue with the ASCL records is that they don’t capture the preferred way of citation by the authors, and are definitely not updated with changes in those preferences, and it’s not clear how the records can be amended. I have tried to get the references fixed for e.g. astroquery but didn’t succeed. Picking random papers not related to the software authors and refer them in “used in” and “described in” is imo far from being a good solution especially when those are then migrated to to an ADS entry. This highlighting one random paper is especially problematic when there are numerous citations to the zenodo DOIs and/or the package is mentioned in multiple papers. In this specific case there are both a full AJ paper as well as a central Zenodo DOI that resolves always to the latest version, neither of those are linked from the ASCL entry.