DOC: Update citation file with JOSS paper reference #496

Lucia-Fonseca · 2021-09-10T13:04:49Z

Description

This PR updates the citation guidelines to include the JOSS paper and link the rst file to the documentation page. Merging this PR successfully closes #495 .

Checklist

Follow the Contributor Guidelines
Write unit tests
Write documentation strings
Assign someone from your working team to review this pull request
Assign someone from the infrastructure team to review this pull request

Lucia-Fonseca · 2021-09-10T14:08:36Z

This is done. Can anyone check the bib file and the Zenodo reference therein? Thank you!

Lucia-Fonseca · 2021-09-10T14:10:14Z

Docs are failing but it was working fine on my computer

rrjbca · 2021-09-10T14:16:50Z

Docs are failing but it was working fine on my computer

You should add developer/citation under the developer toctree in index.rst. Although I would suggest moving citation.rst into docs/project as this seems more appropriate than docs/developer

Lucia-Fonseca · 2021-09-10T14:37:31Z

The Download BibTeX button is not working. Any ideas? It might be spaces but I cannot make it work consistently

CITATION.rst

Lucia-Fonseca · 2021-09-10T14:51:25Z

Is there a better place for the main.bib file?

Lucia-Fonseca · 2021-09-10T14:58:12Z

Ready for review

rrjbca · 2021-09-10T15:00:06Z

I don't think having a bib file and a download link is a good idea:

The download link doesn't render in GitHub: https://github.com/Lucia-Fonseca/skypy/blob/citation/CITATION.rst
The zenodo reference necessarily points to a single release. We ask people to cite the version they used. Even if we kept it up to date with the most recent release (we won't) it is the wrong reference for people using older versions.

Lucia-Fonseca · 2021-09-10T15:07:53Z

I don't think having a bib file and a download link is a good idea:
Oh, I liked it but yes, it does not render in GitHub.

The download link doesn't render in GitHub: https://github.com/Lucia-Fonseca/skypy/blob/citation/CITATION.rst

The zenodo reference necessarily points to a single release. We ask people to cite the version they used. Even if we kept it up to date with the most recent release (we won't) it is the wrong reference for people using older versions.
True

ntessore · 2021-09-10T16:51:53Z

We could display the JOSS badge somewhere as well:

rrjbca · 2021-09-10T16:53:30Z

We could display the JOSS badge somewhere as well:

It's already on the README. Do you want it in the docs also?

ntessore · 2021-09-10T16:57:59Z

Just an idea, I like that big green box. On the other hand, someone on the CITATION page has already clicked and gone there on purpose, so perhaps not necessary to decorate the page any further.

rrjbca · 2021-09-10T17:06:34Z

It could work, instead of the current text which is a bit wordy and clumsy we could have:

The BibTex entries can be found at the following links:

Lucia-Fonseca · 2021-09-13T08:55:26Z

The badges

do not render well in the docs

CITATION.rst

Lucia-Fonseca · 2021-09-13T09:12:46Z

Ready

itrharrison · 2021-09-13T09:23:39Z

CITATION.rst

 the following acknowledgment:

  This research made use of SkyPy, a Python package for forward modeling
-  astronomical surveys (SkyPy Collaboration, 2020).
+  astronomical surveys (Amara et. al., 2021, SkyPy Collaboration, 202x).


Apologies if I have missed discussions which already address these points.

Are we happy with 'Amara et al' or would another 'SkyPy Collaboration' be the preferred style? I appreciate there are probably reasons for this I have missed!

We could do the work for the user of including the most up to date version year/reference, which I guess would just require changing as part of each new release.

Are we happy with 'Amara et al' or would another 'SkyPy Collaboration' be the preferred style? I appreciate there are probably reasons for this I have missed!

"SkyPy Collaboration" isn't listed as an author on the JOSS paper, their template wouldn't allow it. Are you suggesting that people cite it as SkyPy Collaboration 2021 regardless? Would that work with ADS etc?

We could do the work for the user of including the most up to date version year/reference, which I guess would just require changing as part of each new release.

But then if somebody is using an older version they shouldn't be citing the most up to date version. It might be possible that for each release the published documentation give the corresponding DOI, but only if we can reserve zenodo DOIs before me make the release. As our Zenodo admin could you investigate this?

I am not happy with Amara et al. either, if we could do SkyPy Collaboration and not mess up with ADS I would go for it.

I cannot find anything in the ADS FAQ to answer this...

I don't think it is possible to reserve a zenodo DOI when using the github webhook, so we would have to revert to manual submissions.

Is this something we want to try?
I'd rather have SkyPy Collaboration rather than Amara et al. 2021 but:

Is it worth delaying the release?

Sutieng's paper is ready and they cite Amara et al 2021.

In my opinion, releasing this PR is our single highest priority. The proposed guidelines are adequate and these side issues are unresolved and unnecessarily holding us up. Like it or not, Amara et al 2021 is the correct citation given by both ADS and JOSS. I agree that our citation guidelines should be consistent with ADS in the first instance. I'm also against modifying the ADS entry at the expense of consistency with the entry on the JOSS website. Similarly, reserving a DOI has not been tested with the GitHub webhook and putting the wrong DOI in our citation guidelines could be incredibly harmful. I would suggest trying to reserve a DOI for our next release and if we can demonstrate that it works then integrate reserved DOIs into the citation guidelines for future releases.

I don't disagree necessarily with any of this, but I think it is not fair labeling this a "side issue" or "unnecessary". We agreed pretty early on that all publications would be authored by "SkyPy collaboration" with an alphabetical author list following. Now reneging on this merits at least a discussion, and probably a much more visible one than hidden in this PR somewhere.

Totally agree these are decisions beyond the scope of this PR and review that should be discussed by the collaboration. But the current proposal is at least accurate and waiting for the resolution of that discussion could cost us citations. The guidelines can always be updated in the future.

Agreed, we'd need a conversation with the collaboration and we can also merge this as it is for the sake of the v0.5 release. After all, the issue is not about the author list (which I agree it's not a secondary issue but it is not a GitHub issue either)

CITATION.rst

docs/index.rst

CITATION.rst

rrjbca

I'm happy to approve this PR in it's current state (although possibly check my brief comment r.e. unformatted pull-quote) but will wait for others involved to approve before merging.

Lucia-Fonseca · 2021-11-02T14:14:45Z

After offline conversations, we agree the citation would be Amara et al. 2021 and not the preferred option SkyPy Collaboration 2021 for justified reasons. Therefore, this PR can be merged.

* Update name of default branch to main (#434) * update mailmap (#432) * Write all tables to a single FITS/HDF5 file (#425) * ADR 3: Position sampling and patches of the sky (#422) * BUG: Raise ImportError if optional dependency speclite is not installed (#437) * MAINT: Set NumPy latest supported version to 1.20 #440 * Update status badges (#441) * MAINT: Update Lucia affiliation (#451) * MAINT: add SIT's information (#450) * DOC: Fix contributor guidelines link (#449) Co-authored-by: Richard R <[email protected]> Co-authored-by: Nicolas Tessore <[email protected]> * ENH: Logging for skypy command line script and Pipeline class (#453) * DOC: Describe speclite filters in documentation (#457) * ENH: Config syntax for importing objects (#463) * DOC: List of Features (#456) * DOC: How to construct config files (#454) * DOC: Remove docstring examples (#429) * MAINT: Update Zenodo entry for RPR (#468) * DOC: Readme updates (#460) * DOC: Expanded landing page documentation (#228) * DOC: Inverse transform sampling accuracy warning (#472) * MAINT: Set astropy latest supported version to 4.2 (#483) * DOC: zenodo json members update (#481) * DOC: Ryden04 ellipticity doc missing section (#477) * MAINT: Update numpy and scipy latest supported versions (#488) * BUG: Change invalid ecsv datatype from int to uint16 (#485) * DEV: setuptools==58.0.0 (#493) Co-authored-by: Nicolas Tessore <[email protected]> * Add compatibility workflow badge (#487) * DEV: Enable pip to install pre-releases in the tox dev environments (#491) * TST: Use tmp_path fixture for temporary files in unit tests (#489) * BUG: Move handling of context arguments after handling of .depends keyword (#465) * BLD: Set astropy latest supported version to 4.3 and speclite minversion to 0.14 (#486) * REV: restore setuptools to latest version on readthedocs (#494) * DEV: pyparsing<3.0.0 (#500) * Check new astropy file overwrite error message in logging test (#498) * REV: restore pyparsing to latest version for doc builds (#501) * DOC: Update citation file with JOSS paper reference (#496) * BLD: Set astropy latest supported version to 5.0 (#504) * BLD: Set python latest supported version to 3.10 (#505) * BLD: Set numpy latest supported version to 1.22 (#506) * BLD: Set python oldest supported version to 3.7 (#507) * DOC: Fix code of conduct link (#508) * Changed y-label in luminosity function example. (#512) * BLD: Set scipy latest supported version to 1.8 (#510) * ENH: Rykoff model of the magnitude uncertainty (#526) * TST: assert photometric error is numerically close to the analytic value (#545) * TST: Drop deprecated astropy.tests.helper.raises (#546) * ENH: compute kcorrect remaining stellar mass (#476) * compute kcorrect remaining stellar mass * added test for stellar mass remain Co-authored-by: Ian Harrison <[email protected]> Co-authored-by: Lucia F. de la Bella <[email protected]> * ENH: Logistic completeness function (#521) * BLD: Set astropy latest supported version to 5.1 (#547) * BUG: `schechter_smf` callable input and docs (#525) * DOC: Typo in Rykoff error (#550) * add Fox's details (#551) Co-authored-by: Richard R <[email protected]> * BLD: Set numpy latest supported version to 1.23 (#552) * codestyle fixes * add six requirement for colossus * tried to fix docs builds * update passenv * rtd configuration Co-authored-by: Richard R <[email protected]> Co-authored-by: Nicolas Tessore <[email protected]> Co-authored-by: Lucia F. de la Bella <[email protected]> Co-authored-by: Sut-Ieng Tam <[email protected]> Co-authored-by: philipp128 <[email protected]> Co-authored-by: Fox Davidson <[email protected]>

Update citation file with JOSS paper reference

816c44e

Lucia-Fonseca added documentation Improvements or additions to documentation enhancement Improvement of existing feature joss_paper labels Sep 10, 2021

Lucia-Fonseca self-assigned this Sep 10, 2021

Lucia-Fonseca added 4 commits September 10, 2021 14:07

Create file to link the citation rst file to docs

cb781e0

Add link to the citation file in the docs

a2e7eab

Add titel to the citation guidelines

f2fa12b

Create BibTeX download button'

d4078de

Lucia-Fonseca requested a review from rrjbca September 10, 2021 14:10

Lucia-Fonseca added 5 commits September 10, 2021 15:21

Fix external link

0f52a9c

Move citation from developer to project doc folder

5554702

Add citatio to the project toctree in index

8106e3e

Fix link to citation file

a66e6c3

Add blank line

6019b13

rrjbca reviewed Sep 10, 2021

View reviewed changes

CITATION.rst Outdated Show resolved Hide resolved

Fix link to bib file

bdb2de0

Lucia-Fonseca requested a review from rrjbca September 10, 2021 14:57

Lucia-Fonseca added 2 commits September 13, 2021 09:42

Delete BibTeX file

be1673d

Update text

c3dc091

ntessore reviewed Sep 13, 2021

View reviewed changes

CITATION.rst Outdated Show resolved Hide resolved

CITATION.rst Show resolved Hide resolved

Lucia-Fonseca added 2 commits September 13, 2021 10:03

Fix badges

b92ae35

Eliminate unnecessary options for badges

d2e4504

Lucia-Fonseca requested review from ntessore and rrjbca September 13, 2021 09:12

itrharrison reviewed Sep 13, 2021

View reviewed changes

rrjbca reviewed Sep 13, 2021

View reviewed changes

CITATION.rst Show resolved Hide resolved

rrjbca reviewed Sep 13, 2021

View reviewed changes

docs/index.rst Outdated Show resolved Hide resolved

Lucia-Fonseca added 4 commits September 13, 2021 11:50

Add admonition

68dfd64

Edit text around the important note

4078b4e

Edit text

82a0ba1

Change admonition to pull-quite

e08e56f

Lucia-Fonseca requested review from itrharrison and rrjbca September 13, 2021 14:28

ntessore removed their request for review September 14, 2021 15:48

rrjbca added the high priority issues needing immediate attention label Sep 16, 2021

rrjbca reviewed Sep 16, 2021

View reviewed changes

CITATION.rst Outdated Show resolved Hide resolved

rrjbca previously approved these changes Sep 16, 2021

View reviewed changes

rrjbca added this to the Version 0.5 milestone Sep 20, 2021

rrjbca dismissed their stale review via 1d7b1ad November 2, 2021 14:20

rrjbca added 2 commits November 2, 2021 14:20

Update CITATION.rst

1d7b1ad

Merge branch 'main' into citation

9c7e7f8

rrjbca approved these changes Nov 2, 2021

View reviewed changes

rrjbca merged commit 5162441 into skypyproject:main Nov 2, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC: Update citation file with JOSS paper reference #496

DOC: Update citation file with JOSS paper reference #496

Lucia-Fonseca commented Sep 10, 2021 •

edited

Loading

Lucia-Fonseca commented Sep 10, 2021

Lucia-Fonseca commented Sep 10, 2021 •

edited

Loading

rrjbca commented Sep 10, 2021

Lucia-Fonseca commented Sep 10, 2021

Lucia-Fonseca commented Sep 10, 2021

Lucia-Fonseca commented Sep 10, 2021

rrjbca commented Sep 10, 2021

Lucia-Fonseca commented Sep 10, 2021

ntessore commented Sep 10, 2021

rrjbca commented Sep 10, 2021

ntessore commented Sep 10, 2021

rrjbca commented Sep 10, 2021 •

edited

Loading

Lucia-Fonseca commented Sep 13, 2021

Lucia-Fonseca commented Sep 13, 2021

itrharrison Sep 13, 2021

rrjbca Sep 13, 2021

Lucia-Fonseca Sep 13, 2021

Lucia-Fonseca Sep 13, 2021

rrjbca Sep 13, 2021

Lucia-Fonseca Sep 14, 2021

rrjbca Sep 16, 2021

ntessore Sep 16, 2021

rrjbca Sep 16, 2021

Lucia-Fonseca Sep 16, 2021

rrjbca left a comment

Lucia-Fonseca commented Nov 2, 2021

DOC: Update citation file with JOSS paper reference #496

DOC: Update citation file with JOSS paper reference #496

Conversation

Lucia-Fonseca commented Sep 10, 2021 • edited Loading

Description

Checklist

Lucia-Fonseca commented Sep 10, 2021

Lucia-Fonseca commented Sep 10, 2021 • edited Loading

rrjbca commented Sep 10, 2021

Lucia-Fonseca commented Sep 10, 2021

Lucia-Fonseca commented Sep 10, 2021

Lucia-Fonseca commented Sep 10, 2021

rrjbca commented Sep 10, 2021

Lucia-Fonseca commented Sep 10, 2021

ntessore commented Sep 10, 2021

rrjbca commented Sep 10, 2021

ntessore commented Sep 10, 2021

rrjbca commented Sep 10, 2021 • edited Loading

Lucia-Fonseca commented Sep 13, 2021

Lucia-Fonseca commented Sep 13, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rrjbca left a comment

Choose a reason for hiding this comment

Lucia-Fonseca commented Nov 2, 2021

Lucia-Fonseca commented Sep 10, 2021 •

edited

Loading

Lucia-Fonseca commented Sep 10, 2021 •

edited

Loading

rrjbca commented Sep 10, 2021 •

edited

Loading