JOSE paper#657
Conversation
There was a problem hiding this comment.
Thanks Navid - looks great.
some ideas ...
- it also teaches about collaboration and git and github, is that worth mentioning ?
- the points about it being a framework for other projects and the amount of user uptake/community use are kind of buried at the end but seem key ?
| the Consortium for Ocean--Sea Ice Modelling in Australia (COSIMA; <https://cosima.org.au>) | ||
| as a community resource for researchers, students, and practitioners working | ||
| with large gridded datasets, especially output from the ACCESS ocean--sea ice | ||
| model configurations [e.g. @kiss2020accessom2]. The repository combines introductory |
There was a problem hiding this comment.
repository hasn't been introduced yet (it's called a module above)
| landing page used to navigate tutorials and recipes. The live site is available | ||
| at https://cosima-recipes.readthedocs.io. \label{fig:website}](website.png) | ||
|
|
||
| Following the "Cookbook" concept, the website sections are deliberately named |
There was a problem hiding this comment.
the cookbook concept is introduced below, so the wording is maybe a bit out of order here
There was a problem hiding this comment.
I agree. I actually think this whole section might flow better if the paragraph starting with "The Cookbook grew from a practical need" was bumped up to before this one.
The start of this paragraph is pretty jarring, and I think it'd benefit from some kind of "why" coming earlier
There was a problem hiding this comment.
I also think this paragraph might go better if it went:
Following the "Cookbook" concept, the website sections are named using a gastronomy theme. We start with tutorials that teach generic, transferable techniques for handling ocean—sea ice model output, which we call "Cooking Tutorials". We then follow this with self-contained notebooks showing how to perform concrete diagnostics and analyses on ocean and sea-ice datasets. These notebooks are the "recipes" that make up the core of the cookbook, and consist of both "Easy Recipes" that provide a good entry point after the tutorials and the "Advanced Recipes" that are more elaborate and demonstrate advanced analysis techniques. Lastly, the Cookbook also contains recipes for working with [should this be setting up?] regional model configurations [@barnes2024regionalmom6], that we term "Regional Specialities." Together, these sections present the documentation as a browsable collection of lessons and recipes gathered into a single cookbook.
I've tried to keep your structure as much as possible in the rewrite, apart from the one major change of flipping to put the tutorial/teaching thing that I think is the more familiar concept first, and the cooking name after. Otherwise, I found the whole paragraph read a bit forced, and like it might have been prioritising the cooking over the pedagogy, which I don't think is what we've done.
| often requires substantial time just to understand the structure of the output, | ||
| the relevant conventions, and the computational environment in which analysis is | ||
| expected to run. There is also substantial scientific labour embedded in many | ||
| common diagnostics. Some calculations, for example computing cross-contour transports, |
There was a problem hiding this comment.
is there a ref for the for example ? Otherwise it only means something to an oceanographer ?
There was a problem hiding this comment.
I would also add that it is a learning tool for those new to physical oceanography, as it explains/outlines how to plot commonly used quantities, and can be independent of model/environment. This is implied from L95 to the end of section but not explicitly stated?
e.g.
https://github.com/COSIMA/cosima-recipes/blob/8a0205ec0c85d2d08fe94fb3acd901b18f392c37/Recipes/Appetisers-Easy/Overturning_Circulation.ipynb
|
|
||
| The intended mode of use is also explicit. The repository is designed around | ||
| Jupyter-based analysis on the Australian National Computational Infrastructure, | ||
| with guidance on running notebooks through ARE/JupyterLab sessions and on |
There was a problem hiding this comment.
I dont think ARE is introduced anywhere
Co-authored-by: Anton Steketee <79179784+anton-seaice@users.noreply.github.com>
Co-authored-by: Anton Steketee <79179784+anton-seaice@users.noreply.github.com>
Co-authored-by: Anton Steketee <79179784+anton-seaice@users.noreply.github.com>
Co-authored-by: Anton Steketee <79179784+anton-seaice@users.noreply.github.com>
|
thanks all for your comments! My plan is to work and finalise this during the mini-hackathon on July 1st-2nd and submit it then. Still a few people haven't responded with excitement to participate. That's OK! But I'm keeping you all on for now. Note though that radio silence will be interpreted as "I don't wanna be part of this". And if you hearted a post or something that's nice, but I want to see verbal confirmation before submitting something with your name on. All who are happy to be part of this, please read and submit comments/thoughts/feelings by June 30th the very latest. |
|
@navidcy - I appreciate being included and happy to be here. I will attempt to read today before the tidal pull of the multi-tasking moon sinks this deep into the to-do list. Thanks for your efforts and those of other authors. |
| require non-trivial development, understanding of model numerics, and validation before | ||
| they can be used confidently. If every new user or project had to reconstruct | ||
| those workflows independently, a large amount of effort would be repeatedly spent | ||
| on rebuilding analysis code rather than conducting research using the model output. |
There was a problem hiding this comment.
not convinced that "using the model output" is adding much here; could just be deleted
| other groups. First, each notebook is intended to be self-contained and | ||
| well-documented, so learners can read, run, and modify a complete workflow | ||
| without reconstructing missing context from scattered notes. Second, the | ||
| repository distinguishes tutorials from recipes. Tutorials teach transferable |
There was a problem hiding this comment.
"Second, the repository distinguishes tutorials from recipes." — when I first read this sentence, I thought "hang on, that needs to be explained earlier on". I think it might be in the initial cookbook introduction paragraph, but I missed it on the first pass because of the foregrounding of cooking terms. If you're okay with my suggested rephrase there, then ignore this comment, otherwise I think the purpose and distinguishing features of recipes & tutorials should be made clearer somehow
| tutorials and finally to recipe notebooks that address concrete scientific | ||
| questions. The categories of "easy" and "advanced" recipes provide | ||
| a lightweight pedagogical cue about expected complexity and scope, with | ||
| "regional specialties" specifically covering recipes for regional model configurations |
There was a problem hiding this comment.
Is this "recipes to do analysis on regional model configurations"? In which case I'm not clear on why the regional configs need their own recipes, and why these aren't the same thing as the global model grids.
Or is it "recipes to set up regional model configurations"? In which case I think that deserves more clarity. Perhaps "specifically covering recipes to configure a regional model"?
|
Thanks Navid & Julia I'm happy to contribute, though I don't really feel I've done enough. I'm going to trust that you've used some reasonable principles to make this decision, so I'll say, "Sure, count me in!" but please be aware that I'm not going to be offended if I'm removed from the author list because I haven't really done much. I've left a handful of comments on the text. My one generic comment is to do with the COSIMA ethics, and if it's related enough as a set of guidelines for sharing code that it's worth mentioning? Also, I was very confused for years about what the purpose of the COSIMA cookbook was, and the value that other community members were getting from it (I'm not denying that it clearly had value for people, the specifics were just confusing me). It's great that we're having conversations about this now, and personally that's going to make it much easier for me to contribute and support the community. I do think that the opening & point of this paper could be further strengthened by having some more of those discussions, and being more clear on whether we want it to be a teaching tool for the basics of how you do analysis, or a teaching tool for specific sets of analysis in general, or a bunch of stuff that just works to begin with and lets you focus on other things. Maybe my mind's being clouded by the fact that I know these discussions are happening, but it seems like the intro might be trying to be vague about which of these purposes are being served and I'm not sure that's beneficial. |
Yes, we have reasonable principles in place. |
Excellent points! Also resonate by some comments made by others in this PR or through chats here and there. |
| those workflows independently, a large amount of effort would be repeatedly spent | ||
| on rebuilding analysis code rather than conducting research using the model output. | ||
|
|
||
| The COSIMA Cookbook facilitates knowledge sharing and accelerates research with |
There was a problem hiding this comment.
Maybe knowledge sharing is a bit broad here? Would something like the sharing of analysis methods and workflows be a bit more accurate ?
There was a problem hiding this comment.
actually "workflow" appears quite frequently in this paragraph already
| affiliation: 2 | ||
| - name: Matthis Auger | ||
| orcid: 0000-0001-6228-5732 | ||
| affiliation: 16 |
There was a problem hiding this comment.
Now in "University of Brest, France"
|
HI @navidcy, I am happy to be included. I'll have a read through it and will provide some feedback next week! Cheers, Jaap |
|
The paper is looking great! Well done everyone, particularly @navidcy and @julia-neme . I have added a few comments. More generally, we should consider mentioning AI coding tools for the following reasons:
|
20 participants
Hi team!
cc @willaguiar, @MatthisAuger, @ashjbarnes, @rbeucher, @dhruvbhagtani, @chrisb13, @hrsdawson, @NoahDay, @fabiobdias, @edoddridge, @AVEllepola, @matthew-england-unsw, @lidefi87, @angus-g, @mauricehuguenin, @aidanheerdegen, @AndyHoggANU, @rmholmes. @wghuneke, @jemmajeffree, @aekiss, @minghangli-uni, @josuemtzmo , @janjaapmeijer, @Thomas-Moore-Creative @ruth-moorman, @paigem, @adele-morrison, @jmunroe, @adityarn, @micaeljtoliveira, @ongqingyee, @max-anu, @mmr0, @schmidt-christina, @taimoorsohail, @PaulSpence, @dougiesquire, @anton-seaice, @charles-turner-1, @vsilvafelipe, @marc-white, @luweiyang, @claireyung, and @janzika!
Me and @julia-neme have been thinking about pushing out a paper about the Cookbook in the Journal of Open Source Education! JOSE is an open source journal (similar to JOSS). They publish relatively short paper (~3-5 pages). But together with the paper, also the whole repository and its documentation are reviewed and published!
(Similar to the regional-mom6 paper.) All the review process occurs openly on Github via issues and pull requests.
We've included as coauthors everybody that have contributed to the repository and had their name in the
.zenodo.jsonfile. That said, we may have left somebody out -- it's not intentional! Please point it out any such case if it is the case or message @navidcy privately if you prefer.This PR adds a first draft of the JOSE paper. After every commit, a Github Action generates a PDF and uploads it at: https://github.com/COSIMA/cosima-recipes/blob/ncc/jose-paper/paper/paper.pdf
What is needed from you at this point?
If you are keen to be part of this then:
Have a read (it's only 3-4 pages)! Click on the link mentioned above to see the PDF.
You can suggest edits on the Markdown file (
paper.md) the same way you would do in a PR. Or if you prefer, you can make a PR from your fork to this branchncc/jose-paper.Give generic thoughts/feelings/comments as a post in this PR.
Check your affiliation and add any grants in the acknowledgments.
The aim is to submit during or just after the mini-hackathon at the beginning of July 2026.
Confirmed participation [@navidcy edits list below when they see verbal confirmation]