Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add SciPy 2018 paper as an additional publication #111

Merged
merged 3 commits into from
Feb 11, 2021

Conversation

bdice
Copy link
Member

@bdice bdice commented Feb 8, 2021

Description

I added our SciPy 2018 paper as an additional publication. I find myself wanting the citation for that paper somewhat often and thought it would be good to add to our docs. I put it in a separate section so that it is not confused with our "preferred citation."

Checklist:

@bdice bdice requested review from a team as code owners February 8, 2021 17:34
@bdice bdice requested review from kidrahahjo, lyrivera, csadorf and vyasr and removed request for a team, kidrahahjo and lyrivera February 8, 2021 17:34
@vyasr
Copy link
Contributor

vyasr commented Feb 8, 2021

Thanks for doing this! One gripe I often have with other tools that have multiple citations (GROMACS in particular comes to mind) is that many provide no guidance as to when different papers should be cited, leaving the reader to guess. I would recommend addressing this by including some view of what we think best practice would be. I don't really know that we've had a discussion of what that is even internally, so now would maybe be a good time to do that.

The JCMS paper predates the "modern" signac-flow API; the decorator syntax, most of the current status view, and Jinja2 templating all come to mind as things that were introduced at the time of this publication that I would guess are used in some form by >90% of current signac users. After this paper was published, we were on a pretty steady pace of adding smaller features for a bit until groups, and now aggregation. We can't do anything about the latter two yet (pending future papers/presentations that include those features), so for now perhaps we add a line like "We strongly recommend that users of the signac-flow workflow package also cite ..."? Would you agree that this is a reasonable division of what should be cited based on current usage? Is this statement too strong? Readers are always free to ignore it, and a statement like this at least makes our position clear on what each paper is about.

@bdice
Copy link
Member Author

bdice commented Feb 9, 2021

@vyasr I think we may have discussed the "preferred citation" before (probably in person, 2-3 years ago) and decided to point to the original paper, but I'm happy to discuss again. I created this PR with that in mind, which is why I put the new citation at the bottom. We may encounter difficulty in convincing users to cite multiple papers, since we already have a recommendation to cite the Zenodo release in addition to the original paper. As another perspective, HOOMD has decided to use the most recent paper as its preferred citation.

@vyasr
Copy link
Contributor

vyasr commented Feb 9, 2021

Yes, I think we did discuss that and I'm still in favor of having the JCMS paper be the preferred citation. I think we should prioritize the SciPy paper over the Zenodo link, though, and I think we should also include some explicit recommendation as to when/why it should be cited. Here's my case:

In practice, most people are just going to use one citation by default, and I think it should be the JCMS one. However, I think we can increase the chances of a second resource being cited if we provide more explanation of when/why it should be cited, and if we choose a more familiar source. People currently aren't citing the Zenodo (you can see on that page that there's only 2 citations, one from Chengyu and one from Rosy's current group, relative to >45 for the JCMS paper), and I suspect that's a combination of not wanting to cite multiple items (what you said) and not wanting/understanding how to cite Zenodo, which is a nontraditional source. From that perspective, I think a conference publication discussing features is a more useful citation to recommend than Zenodo, because

  1. I think it's more likely to be cited because it seems more "real" to non-developers.
  2. Readers of a paper citing signac will gain more from a paper to read than the Zenodo, since to get any information readers will probably end up just Googling signac.
  3. We can more easily justify the citation to users (something like "if you use the following features also cite...", which has precedent in many other packages and seems to result in >0 citations)
  4. There's less concern with the citation being outdated, whereas with Zenodo we discussed uploading separate citations for different releases since that's really what you want to be citing if you're going to use Zenodo (currently it's all just signac 1.0.0, which also ignores the Zenodo DOIs for signac-flow).

@bdice
Copy link
Member Author

bdice commented Feb 9, 2021

@vyasr your argument sounds fine to me. Would you be able to update this PR to address your suggestions?

@vyasr
Copy link
Contributor

vyasr commented Feb 9, 2021

Yes, I can do that.

@vyasr vyasr merged commit d037a30 into master Feb 11, 2021
@vyasr vyasr deleted the additional-publications branch February 11, 2021 20:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants