How should users cite SasView and parallel projects

[krzywon]

There has been a lot of discussion recently on how to cite sasview. This has led to a number of questions in relation to DOI generation, citiation, and what projects should have their own DOI. This discussion combines the different aspects into a single location.

The main question we are trying to answer with this discussion is how should users cite SasView, sasmodels, sasdata, and any future separate packages that were used in the process of publishing their data?

The current status of proposals and outstanding questions for each item:

• Should users cite a SasView paper, a DOI, both, or something else?
  • Currently, we generate a DOI for each release, using Zenodo. This DOI is specific to a SasView release, but is partly linked to sasdata and sasmodels.
  • A paper has been in the works for many years, but is yet to be submitted.
  • The main take away from most discussions is related to FAIR principles, and users wanting to cite the specific point in the software they were using to get the results they published. This suggestes either a DOI for a specific release, or the SHA for the head commit of the software they used.
  • None of this precludes users from citing any eventual paper, but the DOI for each release is important.
• Should there be separate citation methods for sasview, sasmodels, and sasdata, for cases where the user did not use sasview?
  • SasModels is used by many external packages, not just sasview, and sasdata could easily have a similar usage in the future.
  • There could be intermediate releases for each package that aren't a part of the sasview release cycle.
  • If we are able to automate the DOI generation, creating separate DOIs costs us mostly nothing, so it makes sense to do so.
• For 'authorship' of SasView, how should the list be formulated, and what order should those authors be listed in?
  • Our current system is out lined in https://github.com/SasView/sasview/wiki/contribution_acknowledgments, but that wiki is missing one important aspect - order of authors.
  • Currently, all authors are listed alphabetically by last name in the Zenodo record, but the widget in SasView shows Doucet. et. al.
  • The latest suggestion for authorship is the put the release manage as the first author, and keep all other authors listed in alphabetical order.
  • Other suggestions have included; list only the people who directly contributed to the latest release as authors and all other people listed under the 'contributors' list; or list the direct contibutors first before all other authors.
• If we use DOIs, how often should these be generated - should we have one for the entire project, one for each separate package, one for each final release, or should we have create new DOIs for each alpha/beta/rc release as well?
  • https://zenodo.org/communities/sasview-analysis/records?q=&l=list&p=1&s=10&sort=newest
  • We have a project DOI for sasview, and currently generate a DOI for each release using a manual process. If we move to automated DOI generation, this will create new DOIs for each alpha/beta/rc release automatically.
  • Citing SasView when sasmodels or sasdata was used does not seem appropriate, especially if there is no DOI for an intermediate release of either, e.g. SasView releases v19.6.1 using sasmodels v3.9.2, and sasview v19.6.2 uses sasmodels v3.9.9, how should a user cite sasmodels versions 3.9.3 through 3.9.8?
  • Create DOIs for each parallel package is still open for debate.

A previous discussion on authorship: https://github.com/orgs/SasView/discussions/3475#discussioncomment-13597883

[butlerpd]

There is a lot to unpack here. I think my vote would be to proceed in a stepwise fashion:

1. create an ADR based on the current agreement outlined on the wiki
2. Make the suggestion about order of authorship a proposed change to that ADR and eventually merge the conclusion into that ADR
3. Make the question of DOI's per package a separate issue and potentially a separate ADR
   a. get a group to study the different options and their implication - including authorships and implications of various choices
   b. Make one or two alternate proposal along with the pros and cons of each approach
   c. After broader discussion, create a proposed ADR for this, or, if too intertwined with authorship considerations, another change to the original ADR above though in that case the name may need changing?

[krzywon]

Notes from technical meeting:

• Separate packages should each have their own DOIs
• For the sasview wheel, how do we know what versions of dependencies are used? Will likely be different for each dependency and each user.

[lucas-wilkins]

Citation recommendation

Cite the latest zenodo DOI.

Authorship order:

We can add an organisation as an author on Zenodo, say "SasView Community", make that first author, then everyone else in alphabetical order.

Don't really have an opinion about whether active contributors should go before others or not.

DOI

There's a potential to have linked sequential DOIs for revisions, I think I said I would investigate how this works (just sent some emails to out FAIR team now).

[lucas-wilkins]

Regarding the discussion today, in which I summarised a discussion with the STFC FAIR team.

• Regarding what releases should have a DOI - that seems to be unambiguous - every version should have a unique DOI, and people should cite the right one.

• DOIs can be linked between versions, one of two ways, using the IsNewVersionOf/IsPreviousVersionOf or Obseletes/IsObseletedBy in the relationship specified by the RelatedItem tag.

• Further details about DOIs as @wpotrzebowski requested...
  The DOI metadata xml schema file is available here:
  https://schema.datacite.org/meta/kernel-4.6/metadata.xsd
  and a use friendly overview of it is here:
  https://datacite-metadata-schema.readthedocs.io/en/4.6/properties/overview/
  Information regarding the citation field specifically: https://datacite-metadata-schema.readthedocs.io/en/4.6/introduction/citation/ In this, it's unclear whether or not the creator for the citation has to be named in the creators list, in any case, creators that are organisations are possible https://datacite-metadata-schema.readthedocs.io/en/4.6/properties/creator/ shows an example of this.

• The ways of defining contributions remain limited to very paper-oriented types

I will speak to our FAIR team about participating in any meeting we have about this

[krzywon]

From a discussion during the Dec. 12 technical meeting:

• Parallel projects should have there own, unique, DOI for each release.
• Using the SasView GUI - only cite sasview
• Scripting or including a package in external projects - cite all packages used
• All project DOIs should be listed under the purview of SasView, in the SasView Zenodo community: https://zenodo.org/communities/sasview-analysis/records?q=&l=list&p=1&s=10
• Separate projects should not have their own Zenodo community