Update citation details in docs and add CITATION.cff file

[matt-graham]

Resolves #225 and resolves #217

Updates the citation BibTeX details in various places in documentation to reflected published and accepted version of JCP article and also adds a CITATION.cff file with this citation data.

The default behaviour of CITATION.cff is to list the citation metadata for the software itself however there is a preferred-citation field for adding details of another artefact that should be cited in preference first. I've added JCP article details to this field and some basic metadata for software to main fields. For now I've just listed @CosmoMatt and @jasonmcewen as authors on the software. An alternative would be to list all contributors for example.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 93.28%. Comparing base (543dfca) to head (a1f400d).
Report is 10 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #236   +/-   ##
=======================================
  Coverage   93.28%   93.28%           
=======================================
  Files          29       29           
  Lines        3170     3170           
=======================================
  Hits         2957     2957           
  Misses        213      213           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[jasonmcewen]

I'm not actively using this so no need to cite. If anything would be better to cite my website (www.jasonmcewen.org)

[matt-graham]

I've added your website here and in preferred citation (and also Matt's). Unless you have a strong preference of not including ORCiD I would say better to include it as it helps with having research outputs automatically indexed - for example if we start having releases archived on Zenodo using the Zenodo GitHub integration then your ORCiD will be automatically pulled from the CITATION.cff file and added to the metadata for the archive on Zenodo. As your ORCiD is linked to your UCL profile / entry on RPS this means any archive on Zenodo can then also be automatically synced to your RPS profile.

[jasonmcewen]

Ok, fine to keep the ORCiD then.

[jasonmcewen]

Thanks a lot @matt-graham . Great to have this set up. Good to specify the paper as the preferred citation.

In terms of code authors, we should certainly extend this beyond @CosmoMatt and I. We should certainly include you, @ASKabalan and others that have made core contributions. We could also extend this to "all-contributors". What do you think best?

[jasonmcewen]

@matt-graham While we're updating citation details, I just saw in the readme, in a couple of places we have:

Price & McEwen, in prep.).

This should also be updated to a hyperlink like in the opening sentence. Could you correct that while you're at it?

[matt-graham]

@matt-graham While we're updating citation details, I just saw in the readme, in a couple of places we have:

Price & McEwen, in prep.).

This should also be updated to a hyperlink like in the opening sentence. Could you correct that while you're at it?

These in text citations are now updated to Price & McEwen 2024 (switched to publication date rather than pre-print date) and links added (I've stuck with arXiv link rather than linking to published article from an ease of access perspective).

[matt-graham]

Thanks a lot @matt-graham . Great to have this set up. Good to specify the paper as the preferred citation.

In terms of code authors, we should certainly extend this beyond @CosmoMatt and I. We should certainly include you, @ASKabalan and others that have made core contributions. We could also extend this to "all-contributors". What do you think best?

I would say either sticking to just you and @CosmoMatt or extending to all contributors (or possibly those having made commits to main / listed with code contributions in all-contributors entry) would probably be the simplest in the long run.

If we decide to include only a subset of contributors, my experience is it is difficult to decide how to do this consistently / fairly and creates issues with both having to make a manual decision every time someone new contributes whether to include as an author and also means we need to remember to keep CITATION.cff up to date. If we use existing all-contributors data then I think we could hook in to this to open PRs to have contributors added to CITATION.cff automatically or at least have a check that the details in .all-contributorsrc and CITATION.cff are consistent (we do something similar on another project I'm involved in).

[CosmoMatt]

@matt-graham imo we should just include all contributors here. It is the most straightforward solution and highlights everyone's contributions to the code. But I'm ultimately happy with whatever people prefer!

[jasonmcewen]

Yep agreed, let's include all-contributors in the citation authors.

[jasonmcewen]

Have approved this so you can merge at your convenience.

We can either set up the auto-population of the citation file from all contributors now or consider it in as a separate PR.