Ideas for making Mantid easy to Cite

[robertapplin]

Description: I had a discussion with Martyn and Sarah about contributions made to scientific software and how they are recognised, which is described in this link and its adjoining article https://bssw.io/blog_posts/the-contributions-of-scientific-software-to-scientific-discovery. From our discussion, we identified two things that could potentially provide better recognition for the work done by our software contributors:

1. Try to increase citations of Mantid for publications
2. Try to increase awareness of developer contributions

This issue is meant to focus on number 1 only

One small step towards improving recognition of the work done by our software developers could be to make it as easy as possible for Mantid to be cited in a scientific paper, thereby increasing the likelihood that our work gets cited. This issue will therefore focus on two things:

A. Deploying the Citation File Format in the main Mantid Repo
B. Coming up with designs for a mechanism to easily get a Mantid Citation from within Workbench

[Pasarus]

Check out this, we already have a lot of leg work on this issue with regards to citation: https://github.com/mantidproject/mantid/issues/26159

[mducle]

I'm a bit confused - the linked article is about attribution of contributions to a software project rather than about scientific citation...

Regarding the citation issue, I think Mantid is quite well setup compared with many project in that we have a project DOI and also DOIs for each versioned release. To make it easier to cite, there's the Citation File Format which is now supported by github - it comes up as a link below the readme and license in the "About" section which would generate a citation text for you (also in bibtex format), see e.g. its repo.

Regarding fully attributing all the contributions (including non-code contributions) to Mantid, it's a bit trickier but at least Mantid is a relatively small project so it's a lot easier than say scipy. A few ideas which come to mind:

• Use the list of code contributions to the script repository - this would cover most instrument scientists or "power" users who contribute scripts but don't have the inclination to contribute a PR.
• List all the people who have responded to forum questions
• List all the people who have participated in project management and review boards (Mantid seems to be very good about putting most of these online already).

[robertapplin]

Apologies @mducle , I think this issue could have been explained better. The discussion I had with Martyn and Sarah revolved around the contributions made to scientific software and how they are recognised, which is probably better described in this link and its adjoining article https://bssw.io/blog_posts/the-contributions-of-scientific-software-to-scientific-discovery. From our discussion, we identified two things that could potentially provide better recognition for the work done by our software contributors:

1. Try to increase citations of Mantid for publications
2. Try to increase awareness of developer contributions

I think you mentioned these both in your comment. This issue is meant to focus on number 1 only (which isn't clear from the initial description of this issue).

Regarding the Citation File Format you linked, I think it looks promising and is certainly something that could help with point 1 - so thanks for mentioning that! I will look into how this can be deployed within the Mantid repo.

For Mantid Users who don't look at github, it would be useful to have a similar mechanism for copying a Mantid citation within workbench itself. This issue will therefore focus on two things:

A. Deploying the Citation File Format in the main Mantid Repo B. Coming up with designs for a mechanism to easily get a Mantid Citation from within Workbench

If you have any other ideas or comments then please let me know

[mducle]

Ah right, thanks for the clarification. Anyway, here are some stuff I've seen other codes do:

• Include a "Please Cite" / DOI on initialisation (quite common) and Mantid does this if you do import mantid.simpleapi or otherwise initialise the Framework.
• Include a "Please Cite" / DOI at the end of each command - this is more common in packages that are made of different commands that you just run in a shell and can get quite annoying if we do it e.g. whenever someone runs an algorithm.
• Include a "Please Cite" blurb on the web documentation (very common) and Mantid also already does this.

I guess what I've not seen is something which generates the bibtex entry for you like the github CFF integration, but if you're writing a paper this is not really a blocker on you citing the program or not... (it's really easy to just create a bibtex entry or if you use a bibliographic manager like Zotero they will do it for you). However, this seems to be what you're looking at in your "B" point - it seems to imply adding a button to the workbench or a Python function which when called will generate the correct bibliographic entry? If you're keen on doing this, then it should definitely cover the bibtex and ris machine formats and perhaps also generate text in certain standard styles (e.g. APA, ACM, Harvard).

Now, as for getting people to cite the program... well, I think there's only so much we can do, but from my experience people are generally happy to cite software if they feel they get enough "value-added" out of it. For example, pretty much every paper I've seen from my users have cited Mantid in the "experiment methods" sections when they talk about how the data was collected. This also goes with Horace and SpinW. A counter example is the Vesta drawing program which draws crystal structures - it's basically the de facto standard and everyone uses it but only maybe 10-20% cite it, even though it states in the license that you must cite it if you generate images in a paper using it. I guess this comes down to people thinking that just making a picture doesn't constitute enough "value-added" to cite... for me personally I tend to not to use Vesta because of the license which I think it is a bit coercive...

One final thought on open data / reproducibility - at the moment most people I know just cite the main Mantid DOI, but for reproducibility purposes we should try to encourage people to cite the actual version of Mantid they used (especially since we already have DOIs for each version).

[robertapplin]

Thanks again @mducle for some more good advice. I can see that https://pypi.org/project/cffconvert/ provides some useful conversions that can be used for point B, so we can just take all the citation information we need from the one CFF file - nice!

I agree, the software version should definitely be included in the citations we provide

[robertapplin]

For point "B" above, here is an example mockup design for easily copying a Mantid citation. Ignore the format of the displayed citation as it is just an example

In the Settings, we could have an option to save a custom citation format that they can reuse:

[AnthonyLim23]

The easy citation work that @Pasarus linked should fix the problem of collaborators getting recognition. The documentation for each algorithm has a citations section (currently it is rarely used). When the user asks for the "citations" of a workspace it will look at the algorithm history and pull out the corresponding citations plus the Mantid citation. So all collaborators will need to do is make sure that they provide a citation in the docs.

[stale[bot]]

This issue has been automatically marked as stale because it has not had activity in 6 months. It will be closed in 7 days if no further activity occurs. Allowing issues to close as stale helps us filter out issues which can wait for future development time. All issues closed by stale bot act like normal issues; they can be searched for, commented on or reopened at any point. If you'd like a closed stale issue to be considered, feel free to either re-open the issue directly or contact a developer. To extend the lifetime of an issue please comment below, it helps us see that this is still affecting you and you want it fixed in the near-future. Extending the lifetime of an issue may cause the development team to prioritise it over other issues, which may be closed as stale instead.

[AnthonyLim23]

I would still like to see this done

[stale[bot]]

This issue has been automatically marked as stale because it has not had activity in 6 months. It will be closed in 7 days if no further activity occurs. Allowing issues to close as stale helps us filter out issues which can wait for future development time. All issues closed by stale bot act like normal issues; they can be searched for, commented on or reopened at any point. If you'd like a closed stale issue to be considered, feel free to either re-open the issue directly or contact a developer. To extend the lifetime of an issue please comment below, it helps us see that this is still affecting you and you want it fixed in the near-future. Extending the lifetime of an issue may cause the development team to prioritise it over other issues, which may be closed as stale instead.

[stale[bot]]

This issue has been closed automatically. If this still affects you please re-open this issue with a comment or contact us so we can look into resolving it.