It’s your software! Get it cited the way you want!

Though not the only reasons your software might not be cited, here are four common ones for lack of citations:

• •

  You haven’t listed a preferred citation method, so others don’t know that you expect your code to be cited when used, or don’t know how to cite it

• •

  Your preferred citation information is hard to find; see previous point as to why this is bad

• •

  Your preferred citation isn’t a trackable citation method; indexers cannot match the reference with the citation artifact you listed

• •

  Your software isn’t being used in research by others

Most software repos (e.g., GitHub, Bitbucket, GitLab) and web sites do not list a preferred citation method! As of October 31, 2022, only 45% of the codes registered with the ASCL specify how that software should be cited, as Figure 1 shows. This is despite the ASCL’s repeated requests, made in email, on social media, and in presentations (such as this one!), that software authors clearly and explicitly list how their software should be cited, and make this information very easy to find. Most software sites do not include this important information!

Use of software in research can be acknowledged and cited in numerous ways, but they are not all equal. A footnote or mention in an acknowledgement or software section of an article is useful information for the reader of that article, but is not a formal citation and cannot be tracked by indexers such as ADS and Clarivate’s Web of Science. Indexers track and count only resources that appear in a bibliography or reference section of a paper; in other words, there must be a formal citation, just as is done when citing a research article, for the software for that citation to be tracked (Allen et al. 2017). Not only must the citation appear in the bibliography, but it has to include certain correctly-formatted information for indexers to find it (again, just as is done for citing research articles), and the indexer has to be able to match that information with something it has already ingested (Henneken et al. 2017). This is why ADS, for example, indexes so many different journals: it uses information it has already ingested to track and match up information in newly-ingested articles. It cannot count what it is unable to match up, such as a citation to an article in a sports medicine journal. Table 1 lists different ways of acknowledging software use in astronomy research documents and whether indexers such as ADS can track and count this use as a citation; in the case of conference proceedings, this assumes the proceedings are formally published, and in all cases, this assumes that the bibliographic references are formatted correctly.

If you want your research software used and cited by others, you can take concrete steps to help others find, understand, use, and properly acknowledge the contribution your computational method made to their research. These steps include:

• •

  Put your code online for download

• •

  Assign your software a open license so others know how they can use your code

• •

  Register your software with the Astrophysics Source Code Library (ascl.net) so others can find your software

• •

  Provide a good README on your code site that explains why your software is useful

• •

  Choose a trackable citation method and make your citation preference clearly visible and easy to find

• •

  Cite your software when YOU use it

When deciding how you want your software cited, best practice per the FORCE11 Software Citation guidelines (Smith et al. 2016) is to cite the software directly, rather than an article. That said, these principles also recognize the value of citing a research paper that may provide additional information about the software and support citing an article in addition to citing the software itself. Choose a trackable artifact as the citation method, such as the ASCL ID, Zeonodo DOI and, if you wish, a research article bibcode or DOI.

Other steps you can take, too, that are more work (but very useful!) include providing a good tutorial on how someone new to your code can get started it using it, providing examples and documentation for your software, advertising it through events such as ADASS and other conferences, and creating a short video to demonstrate how your software enables research.

Software metadata — information about the software itself, such as its title, URL for download, who authored it, and how it should be cited — can be rendered in various ways. Two useful standard formats for representing the software metadata needed for citation are codemeta.json (Jones et al. 2017) and CITATION.cff (Druskat et al. 2021). The Codemeta standard uses a JSON file; this is machine-readable and is easy to reuse. These files can contain not only information needed to cite the software, but additional information useful to software archives, repositories, indexers, and journals. In contrast, CITATION.cff is contained in a YAML file; this is easy for humans to create and read, and contains only the information needed for citation.

The ASCL can be used to generate codemeta.json metadata files, and as of this writing, it is expected that GitHub will also soon supply information and support for creating these files as well. To generate a codemeta.json file for an ASCL entry, add /codemeta.json to an ASCL entry’s URL (i.e., https://ascl.net/1911.024/codemeta.json).

GitHub offers instructions on creating and using CITATION.cff (see https://tinyurl.com/y8r659h5). If you use this method, please make sure your CITATION.cff does NOT specify the GitHub link as the citation method, as indexers cannot track and count GitHub URLs as citations. The ASCL can also create a CITATION.cff from an ASCL entry; the method is very similar to that listed in the paragraph above: add /CITATION.cff to an ASCL entry’s URL (i.e., https://ascl.net/1911.024/CITATION.cff).

Metadata files in these formats that are generated from an ASCL entry are intended to be a starting point; these files should be edited as needed by the software author to accurately represent the software and the preferred citation. Once a metadata file is created, it should be added to the root directory of your repo, as shown in Figure 2, so others can easily find it.