Encouraging citation of software – introducing CITATION files

Summary: Put a plaintext file named CITATION in the root directory of your code, and put information in it about how to cite your software. Go on, do it now – it’ll only take two minutes!

Software is very important in science – but good software takes time and effort that could be used to do other work instead. I believe that it is important to do this work – but to make it worthwhile, people need to get credit for their work, and in academia that means citations. However, it is often very difficult to find out how to cite a piece of software – sometimes it is hidden away somewhere in the manual or on the web-page, but often it requires sending an email to the author asking them how they want it cited. The effort that this requires means that many people don’t bother to cite the software they use, and thus the authors don’t get the credit that they need. We need to change this,so that software – which underlies a huge amount of important scientific work – gets the recognition it deserves.

As with many things relating to software sustainability in science, the R project does this very well: if you want to find out how to cite the R software itself you simply run the command:

In this case the citation was given by the author of the package, in R code, in a file called (surprise, surprise) CITATION inside the package directory. R can even intelligently make up a citation if the author hasn’t provided one (and will intelligently do this far better if you use the person class in your description). Note also that the function provides a nice handy BibTeX entry for those who use LaTeX – making it even easier to use the citation, and thus reducing the effort involved in citing software properly.

I think the R approach is wonderful, but the exact methods are rather specific to R (it is all based around a citEntry object or a bibentry object and the CITATION file contains actual R code). That’s fine for R code, but what about Python code, Ruby code, C code, Perl code and so on… I’d like to suggest a simpler, slightly more flexible approach for use broadly across scientific software:

Create a CITATION file in the root directory of your project and put something in there that tells people how to cite it

In most cases this will probably be some plain-text which gives the citation, and possibly a BibTeX entry for it, but it could be some sort of code (in the language your project uses) which will print out an appropriate citation when run (and, of course, R users should stick to the standard way of writing CITATION files for R packages – this proposal is really for users of other languages). This CITATION file will be one of a number of ALL CAPITALS files in your project’s directory – it will go alongside your README file (you do have one, don’t you?), and your LICENCE file (youmust have one – see my explanation for why)and possibly also your INSTALL file and so on.

I know this approach isn’t perfect (machine-readability of citations is a problem using this method, but then again machine readability of citations is a big problem generally…) but I think it is a start and hopefully it’ll reduce the effort required to cite software, and thus encourage software citation.

14 Comments

Before everybody starts following the simpler approach you proposed, I’d like to point out that CRAN has done this for us. If a package contains a CITATION file, CRAN will convert it to a human-readable page with BibTeX entries, e.g. http://cran.r-project.org/web/packages/knitr/citation.html

I very much agree that software citations should gain more attention, so thanks for the post!

Thanks for the nice blog post. Yes, communicating the recommended citation for any kind of software project is a good idea. If the software runs its own web page, then putting the citation information there is also a good idea. (That’s what CRAN does automatically if CITATION files are provided for R packages.)

Ah that’s great – I didn’t realise CRAN did that. Unfortunately PyPI, CPAN, Rubygems and various other package hosting sites for other languages don’t do that – as far as I am aware at least – so the simpler approach is likely to be useful for other languages (I’ll update the post to make it more explicit that I wasn’t suggesting the simpler approach for R, but for other languages that don’t have the nice citation functionality that R has).

Any thoughts about if an extension is permitted? e.g. CITATION.txt would work far better than just CITATION under windows (double click would automatically open it in a text editor), while CITATION.md or CITATION.rst would look much better on BitBucket or GitHub using markdown or reStructuredText markup. Currently all of the above seem to be used for README files.

[…] use Madagascar in their research and wish to reference it in scientific publications. Following a recommendation of Robin Wilson, a file called CITATION.txt is placed in the top Madagascar directory to provide […]

Hey Robin! So, I’m finally ready to add a CITATION file to my project, but I’m facing the Paradox of Choice: what’s the best way to format it? What have you seen out there? Here are the options I’m contemplating:

– a valid .tex file with some free-form text at the top using @Comment{}, followed by one or more @article/book/whatever.
– a plaintext file with a BibTeX entry at the end, that users would have to manually select and copy-paste. (This is my least-preferred option but the one that you seem to advocate.)
– a plaintext file *referring* to an adjacent .tex file with the bibtex entry. So there would be both a Citation.markdown and Citation.tex.

Great to see you’re going to add a CITATION file 🙂 Of the options you mention, I’ve only ever seen the 2nd one ‘in the wild’ (I did some work with Depsy – http://www.depsy.org – to have a look at how many packages had CITATION files, and what their contents were). Most of them seem to be in plain text format with some explanatory text followed by a BibTeX entry (or, sometimes a formatted citation – which is less good, but still better than nothing).

I understand why this may be your least-preferred option, but I think it gets a good balance between human and computer usage. It is fairly easy to extract a BibTeX entry from a text file automatically (I did this for the packages on Depsy), and it makes it nice and easy for humans to read too.