Citation

[navidcy]

It would be good to have something citable (eg with a DOI) that we would suggest people to do so if they use one of the recipes in the cookbook or if they base their analysis out of one of the recipes.

A quick solution is to make a Zenodo record of the repository in which we add all contributors as coauthors. We can update this Zenodo record every year or every 6 months and add more coauthors as needed. Then we have a section in the README the would ask users to cite this Zenodo repository alongside with their acknowledgments.

What do you all think? cc @edoddridge @aekiss @adele-morrison @AndyHoggANU @angus-g @chrisb13 @dougiesquire @julia-neme

Ideally we publish a small announcement paper in JOSS or something but that's a longer process. We can start with a Zenodo record and see how we go?

[navidcy]

x-ref: ACCESS-Community-Hub/atmosphere-cookbook#19

[navidcy]

cc @kdruken

[edoddridge]

I think that's a great suggestion.

Zenodo allows for proper versioning, so I would prefer for us to apply semantic versioning rather than biannual updates. But also, I don't think it's a big deal.

I like JOSS, but a paper wouldn't allow us to have the same sort of up-to-date versioning as Zenodo. Do we really need a publication?

[navidcy]

Do we really need a publication?

Not really..

Only minor issue with Zenodo is that sometimes Google Scholar or Web of Science or other databases sooooometimes don't properly capture citations in Zenodo record. But I think if done properly and linked with orcid IDs etc it should be very easy!

[navidcy]

I would prefer for us to apply semantic versioning rather than biannual updates

Yes that would be my preference also! But if people feel intimidated with semantic versioning then don't worry; rest assure that your contribution will be taken into account in the next Zenodo version of the repository ;)

[edoddridge]

Only minor issue with Zenodo is that sometimes Google Scholar or Web of Science or other databases sooooometimes don't properly capture citations in Zenodo record. But I think if done properly and linked with orcid IDs etc it should be very easy!

OK. I wasn't aware it can be an issue. I've got a bunch of Zenodo stuff (MITgcm and xmitgcm) that shows up nicely on my Google Scholar.

[navidcy]

Only minor issue with Zenodo is that sometimes Google Scholar or Web of Science or other databases sooooometimes don't properly capture citations in Zenodo record. But I think if done properly and linked with orcid IDs etc it should be very easy!

OK. I wasn't aware it can be an issue. I've got a bunch of Zenodo stuff (MITgcm and xmitgcm) that shows up nicely on my Google Scholar.

Perhaps it's just an issue for me sometimes...
It's really minor! it's much better we have a Zenodo record rather than nothing as we currently do.

[julia-neme]

I like it! Should we make sure only the recipes that are OK are pushed into zenodo? E.g. there's some recipes with open pull requests that need fixing, like SWMT.

[navidcy]

@julia-neme, there will always be bugs... there is no way to avoid that. There are bugs in everything that is released, from iOS, to MOM6, MOM7, etc. So let's not worry if a notebook is not quite there; when we fix it, it'll be included in the next release.

I wasn't thinking that people would actually go to the Zenodo to download the notebooks but that they would still get the notebooks from the repository. The Zenodo is (in my head at least) a way for people to give COSIMAers some attribution by a citation. That's what I was thinking at least.

[chrisb13]

Thanks @navidcy, great to see this idea progressing.

I've updated the COSIMA get involved acknowledgements section with the citation. To simply the last two parts of the README (Conditions of use for ACCESS-OM2 output and Citation), could we just add a link to this page:
https://cosima.org.au/index.php/get-involved/
? It just means we only have to keep one page up to date.

Do we have a mechanism to remind us to do the updates? Perhaps after the next hackathon is good timing? Additionally, there are several branches at the moment (yet to be merged) updating the recipes to use intake by (I think) @rbeucher @marc-white @max-anu @charles-turner-1. So on this..

I wasn't thinking that people would actually go to the Zenodo to download the notebooks but that they would still get the notebooks from the repository. The Zenodo is (in my head at least) a way for people to give COSIMAers some attribution by a citation. That's what I was thinking at least.

I agree. And at the moment, we really don't want people to use the tarballed version!

[navidcy]

Regarding when to do updates: After each hackathon is good idea, or whenever a new recipe is added, or when a major bug is fixed.. These are good times to bump a release, right?

[julia-neme]

That sounds good to me - hackathons are when the recipes get updated any way !

[chrisb13]

Sounds like a plan!

I've updated the COSIMA get involved acknowledgements section with the citation. To simply the last two parts of the README (Conditions of use for ACCESS-OM2 output and Citation), could we just add a link to this page: https://cosima.org.au/index.php/get-involved/ ? It just means we only have to keep one page up to date.

Any thoughts on this suggestion? Just trying to avoid confusion of best-practice and make it easier from our side to only maintain one set of acknowledgements.

[dougiesquire]

@navidcy I'm curious how the author-list was decided for the Zenodo record? There seem to be a number of people listed as contributors on Github that aren't included as authors?

[navidcy]

I think I just copied the author list from a poster submission we had for Ocean Sciences! Let's add them! We can edit the Zenodo author list and add more people!! Do you have rights to edit?

The best way is to add a .zenodo.json like e.g. https://github.com/ACCESS-Community-Hub/atmosphere-cookbook/blob/main/.zenodo.json and then just modify that. When we make a new release of the cookbook the Zenodo will read off the contributors from there.

[navidcy]

I didn't mean to exclude anybody! I just made a start and then nobody said anything :(
Sorry if it felt that I was trying to downplay anybody's contributions...

[chrisb13]

Thanks @dougiesquire and @navidcy. Great to see this being updated, can you please let me know when the changes are implemented with a new citation and I'll update the COSIMA page.

Also, does the doi/link change with the update? If so, I think this page needs to be updated as well?

[navidcy]

Thanks @dougiesquire and @navidcy. Great to see this being updated, can you please let me know when the changes are implemented with a new citation and I'll update the COSIMA page.

Also, does the doi/link change with the update? If so, I think this page needs to be updated as well?

I think you can replace the citation with just the DOI and that way you don't need to update it every time we make a new release?

[dougiesquire]

I believe the DOI will change with every zenodo release

[navidcy]

The DOI I posted (10.5281/zenodo.14353852) is the DOI that always points to the latest release!

[dougiesquire]

Oh nice! I hadn't seen that

[chrisb13]

Okay great, good forward thinking!

I'll update the COSIMA page.

I think you can replace the citation with just the DOI and that way you don't need to update it every time we make a new release?

Good thinking, now done.

[chrisb13]

@navidcy, @adele-morrison, @aekiss, all...

@dougiesquire and I were chatting about this recently and we noticed that while it's now great that we have a .json it would be really good if new users understood that the file needs to be changed once additions are made such that they become authors in the citation. This will hopefully also be prompted by reviewers doing PRs but I think it would be helpful to aspiring authors to know that the expectation is that they can be added as authors once there changes are accepted. Hence, can a comment like this be added to Contributing here.

Here's some proposed text:

Contributors to the COSIMA cookbook will be added to the citatable doi associated with this repository, hence, when putting together your pull request for a new contribution, please add your affiliation details to this file.

[navidcy]

Sounds great! PRs are welcome to add this in the contributors docs page/wiki!

[navidcy]

I don't expect new contributing users to know this. But it'd be nice if reviewers urge the users to add their entry in the .json file. For example, I did that in #416. Hopefully the trend will follow. :)

[navidcy]

Slight modifications of the above. Note that the "all versions" DOI is better.

Contributors to the COSIMA Cookbook are added to the citable DOI entry associated with the repository. Hence, users who put together a pull request for a new contribution, should ensure that the pull request also modifies the .zenodo.json file to include their affiliation details.

[chrisb13]

I don't expect new contributing users to know this.

Yeah I'm imagining that'll happen, I'm thinking it means we have two mechanisms (no harm in duplication here) and it's clear to contributors/new authors from the start.

But it'd be nice if reviewers urge the users to add their entry in the .json file. For example, I did that in #416. Hopefully the trend will follow.

Great to see!

Slight modifications of the above.

Nice, looks good to me. Shall we go ahead and add it here?

[navidcy]

Nice, looks good to me. Shall we go ahead and add it here?

And/or at https://github.com/COSIMA/cosima-recipes/wiki/1.-Working-on-a-recipe ?

[chrisb13]

Yeah, huh I didn't realise there was a wiki! (Perhaps everyone else knows this though..) I'd be inclined to have something on the very front page as it's new contributors we're looking to entice. If you prefer, there can be a very short statement on the README and then a longer one elsewhere. I note there is this too.

[chrisb13]

@navidcy, any thoughts on my last message? Would be good to close this one off. I can insert the edit into the README if that's helpful?

[navidcy]

Sorry for the slack.

Yes, perhaps a very short mention under "Contributing" section in the README and then a more detailed explanation of how to modify the .zenodo.json file in the wiki? That sounds right! Open a PR and we'll work on it.

[chrisb13]

NP.

Cool, now opened a new PR here:

small change to contributing section such that authors know they can also add themselves to .json file for zenodo.
Would be good to also update 1 and 2

I've pinged @navidcy on it, so feel free to accept/modify.

[chrisb13]

As part of the training program, we have:

Upcoming Session next-next Friday (7/3)
Topic - How to use COSIMA recipes?
Presenters - @charles-turner-1 @AndyHoggANU

@navidcy, would be good to get this over the line before then if possible?