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

[krzywon]

Here is the ADR proposal for citing SasView-related projects (Gemini was used to generate the outline, but I modified it to include information not given within this discussion).

Citing SasView and Parallel Projects

Preamble

To ensure that SasView and its associated parallel projects (such as sasmodels and sasdata) are cited correctly and consistently in academic publications, a standardized framework for DOI generation and authorship is required. This framework aims to adhere to FAIR principles, allowing researchers to cite the specific version of the software used to produce their results.

Proposal

SasView will implement an automated, version-specific citation system where every release (including sub-packages) receives a unique Digital Object Identifier (DOI). Authorship for these records will follow a structured order to recognize both the release leadership and the broader community.

Citation Guidelines for Users

• GUI Users: End users of the SasView application should cite the specific SasView release and its corresponding DOI.
• Scripting & Integration: Users who utilize individual packages (e.g., sasmodels or sasdata) within their own scripts or external projects should cite the specific sub-packages used.
• Version Specificity: Users are encouraged to cite the exact version used to ensure reproducibility, rather than a general project citation.

DOI Generation & Management

• Automatic Generation: DOIs should be automatically generated for every final release using Zenodo. Optionally, at the discretion of the release manager, alpha, beta, release candidate, and post release versions may also have unique identifiers generated.
• Package Independence: Parallel projects (sasmodels, sasdata) should maintain their own unique DOIs to allow for independent citation when used outside of the SasView GUI.
• Centralized Community: All project-related DOIs must be listed under the "SasView Analysis" Zenodo community to ensure discoverability.

Authorship & Attribution

• Author Order: The Release Manager should be listed as the first author, with all other contributors listed alphabetically by last name.
• Contributor Recognition: The project will maintain an immutable list of people who have made what is deemed a ‘significant contribution to the SasView project’, along with the affiliation of all persons. The affiliation will be where the person was when they made their last contribution to the project, regardless of where they may be now.
• Widget Integration: The citation information displayed within the SasView "Cite/Acknowledge" widget should match the metadata provided in the DOI record. The citation information for individual projects should be available from the help file.

Implementation Steps

• Create a formal ADR based on current wiki agreements regarding acknowledgment.
• Automate the Zenodo DOI generation process within the CI/CD pipeline for all repositories.
• Include the citation information within the scriptable help file for all repositories.
• Update the "New Developer Guide" to include instructions on how authorship is handled for new releases.

[smk78]

Could we add 'and Reviewers' to 'Citation Guidelines for Users'?

[wpotrzebowski]

I've asked SciLifeLab Open Science team to provide feedback, which they kindly did.

Here is a summarized version of the feedback

• Overall, this looks great and covers the key citing/citability requirements: clear contributor/author + affiliation info, the specific version/commit/date used, and a unique machine-actionable PID.
• The remaining piece is ensuring these details are surfaced to users in a very clear, easy-to-find way
• The SciLifeLab guidelines prefer citing via a paper DOI or RRID when available, but a Zenodo DOI is absolutely fine.
• Great that you’re thinking about different user types (GUI users vs sub-package users). It may also help to explicitly cover “downstream developers” / code reuse guidance. If a paper exists, one useful split is: cite the service via the paper DOI and the code via the Zenodo DOI (leading to distinct cases: service use vs code reuse, across GUI and sub-packages).
• Automating DOI generation and exposing citation info in the help file is excellent—also consider adding it to the README, since that’s often where people look first (especially for reuse).
• Make sure the version is easily visible for GUI users (e.g., header/footer/about dialog).

[krzywon]

README - Visibility for users.

[krzywon]

From todays biweekly call: In the implementation stage, we need to clarify how users will find the references. This should be in the readme file for each repo, with the latest DOI, how to cite individual projects, and when certain packages should be cited.

[butlerpd]

My only note would be that there is some overlap between the "current wiki agreement" which is to become a formal ADR as part of the implementation stated in this ADR, and this ADR itself. In particular regarding immutability and affiliation. both are in agreement generally but the former (wiki agreement) allows a tad of wiggle room that this does not seem to?

For example, the wiki document suggests that the list can be changed if true errors are found but that the default is "immutable" unless under broad discussion it is agreed that something is clearly an error. I can live with the more rigid statement but thought it important to flag up.

[krzywon]

Discussion from our biweekly call: immutable - is this correct? The contributor list can be modified, but only with good reason, based on the original rules.

[krzywon]

This has been approved and @krzywon will write up the final ADR.