Tutorial

[jhidding]

We need to write a tutorial, maybe something that runs in Pluto?

• [ ] @xyl96 Outline a usecase: how do you want to use CarboKitten? Don't mind if that doesn't work yet, just think: if only I could use it like this! Use values that make sense for the community, so don't necessarily stick to defaults we have been using so far. What's important here is the story and the outline.
• [ ] @jhidding Implement bits and pieces to make the tutorial work. Add explainers about how CarboKitten works.
• [ ] @EmiliaJarochowska Quality check.

[xyl96]

Some ideas of outline of today:

Overview of 'CarboKitten' model, motivation, aim.

This needs a real case to backup the motivation. Our goal is to persuade people do the 'stratigraphic check' before carrying out their researches: are my rock archives complete enough to tell a geological story? Also, limited julia contents should be included.

Preparation

• What I am thinking is we can actually choose a scenario in Xi and Burgess., 2022. This is because in this paper, they compared their modelling results to the observed data in British Indian Ocean coral reefs. In this way, we can leave an impression of this model could reproduce modern reef architecture. This could also be re-used in later validation stage. We could also choose an event with significant geological meaning to hook them. For example, PETM (Paleocene–Eocene Thermal Maximum), Pyrenees. This area was relatively well studied Scheibner et al., 2022, and we can use many ready dataset.
• Next step is to prepare the input dataset. Including sea-level, insolation, temperature, precipitation, subsidence. I just started to find them. For the input data, what time-step do I need to adopt? The dataset should cover enough duration (e.g., 1Ma) that covers time period before PETM happens. I also need to collect the real sections (e.g., Camo section, etc.) and simply them to stratigraphy column.

Basic functions

• Introduce functionality of the model (self-organisation mediated production, local transportation, erosion). What do these functions do and why we need them. How to switch on/off the functionalities (CA (cellular automata), transport, erosion).
• Explain what does the parameters in each functionality mean.
• Visuaise of input dataset (sea-level, insolation, etc.).
• Try to run the model, visualise the output (cross-section, timeslice of horizontal map, wheeler diagram).

Play around model

• Do you think they look like a cross-section of a carbonate platform?
• What does the color mosaics and white dashed lines mean in the cross-section? How do they distribute? Can you find any patterns? What's the relationship between their spatial distribution and the visualised inout dataset?
• Select two points on the cross-section (i.e., proximal/ distal to shoal, respectively), visualise sediment-accumulation curve with time. Are they different and if so, why?
• Visualise the 'stratigraphy columns' from the two points. Gave three 'dating points' on these two columns, and let users to manually do age-depth model (ADM). Visualise the 'stratigraphy-age' diagram, let users compare their own ADM with the model output.
• Switch off one functionality (I will take CA as an example), repeat the above three steps, compare the differences.
• Switch back the functionality, change the CA rules, repeat the above steps, compare the differences. Also, compare the horizontal time-slice. How would changes in rules would influence the model ouptputs?
• Compare the series of stratigraphy columns from models with the real section and columns (we will provide). Which one looks the best? How to change your parameters to achieve the best match?
• If you find the 'best' match, use sediment accumulation curve to spot out where and what's the duration are the temporal gaps? What cause this gap? How these gaps distrubute?
• Find out the part represent PETM. Where are the gaps? How much time are actually recorded? With this results in mind, please comment on the estimation of the duration of the event. If you sampled on these sections, how much confidence do you have to proceed investigation?
• Try to export the dataset and feed into StratPal to have a look: how distorted are these archive?

Proxy preservation (we need a flexible components allow users to compare their own proxies)

• Generate a pseudo-^1^3C curve. See how it would be presevred in the stratigraphy.
• Assigan different ^1^3C values to different facies. Think about is it possible to generate an 'fake excursion'?

Work on own data

Gave instructions on what input data is needed and potentially where you can get it from. The format of the input, timestep, duration of the input, etc. Where should users incoporate their data.

[EmiliaJarochowska]

1. How to install Julia
2. How to run CarboKitten?
3. How to generate a carbonate platform based on a given sea-level curve? 3.1. SL from an input file 3.1. SL as a function
4. How to extract a stratigraphic column
5. How to plot a section through the platform in a given position?
6. How to extract and plot an ADM?
7. How to export the entire model grid?

This part:

Do you think they look like a cross-section of a carbonate platform? What does the color mosaics and white dashed lines mean in the cross-section? How do they distribute? Can you find any patterns? What's the relationship between their spatial distribution and the visualised inout dataset? Select two points on the cross-section (i.e., proximal/ distal to shoal, respectively), visualise sediment-accumulation curve with time. Are they different and if so, why? Visualise the 'stratigraphy columns' from the two points. Gave three 'dating points' on these two columns, and let users to manually do age-depth model (ADM). Visualise the 'stratigraphy-age' diagram, let users compare their own ADM with the model output. Switch off one functionality (I will take CA as an example), repeat the above three steps, compare the differences. Switch back the functionality, change the CA rules, repeat the above steps, compare the differences. Also, compare the horizontal time-slice. How would changes in rules would influence the model ouptputs? Compare the series of stratigraphy columns from models with the real section and columns (we will provide). Which one looks the best? How to change your parameters to achieve the best match? If you find the 'best' match, use sediment accumulation curve to spot out where and what's the duration are the temporal gaps? What cause this gap? How these gaps distrubute? Find out the part represent PETM. Where are the gaps? How much time are actually recorded? With this results in mind, please comment on the estimation of the duration of the event. If you sampled on these sections, how much confidence do you have to proceed investigation? Try to export the dataset and feed into StratPal to have a look: how distorted are these archive?

can go into a paper planned by @jhidding (or part of it)

[EmiliaJarochowska]

We had a discussion about it today and @xyl96 had a very good point: for people who do not use VS Code, building a tutorial around it will be one more new tool to install and master, and some Windows users at UU don't even have the rights to install it. So the tutorial shouldn't require a dedicated IDE.

@xyl96 also convinced me to using Pluto instead of Jupyter Notebook! Because for people used to Jupyter, switching to a different notebook will not be a big overhead, and for those who never used it, it won't matter that much as Jupyter would be equally new.

And starting Pluto requires using Julia REPL, so it will be a gateway drug and people will realize that they can also run commands directly from the REPL, if need be. @xyl96 is still waiting for some amendments to the code to finish the tutorial, but I think Pluto it is :-)

[jhidding]

I'm glad to hear that! Pluto notebooks are very good in reproducibility as well. That being said, for developing Julia code in earnest, VSCode does give the best experience. For most people just using CarboKitten, Pluto is king.

[EmiliaJarochowska]

Not much of the specification proposed here was included in the tutorial, so I think this is still open?

[jhidding]

Sure. The tutorial and the notebook for 18 nov. got mixed up in here. The issue got closed automatically. I had to merge to get a working notebook that doesn't rely on workenv. The content isn't final by a mile, but at least now, Hanno and Niklas can also review the tutorial material.

[EmiliaJarochowska]

The tutorial and the notebook for 18 nov. got mixed up in here.

Are these separate things?

[NiklasHohmann]

I went through the tutorial. Key points:

• Be more explicit about what users have to do (e.g., now, type "Pluto.run()" in your console)
• Add meaning to the code, e.g. "First, we do X. This can be done using the following code". Make sure users have sufficient handrails and context at any place in the tutorial
• Provide scientific context and questions. Users will be more familiar with those, and it will give them context to what is happening, and starting points to explore the model further
• Explain visual model outputs
• Maybe provide a simple scientific question as an exercise, and provide a concise solution for it, providing people with a reduced complexity use-case

[jhidding]

The tutorial and the notebook for 18 nov. got mixed up in here.

Are these separate things?

Well, the proposed material by Xianyi on October 1st is way to ambitious for a single tutorial session. Not all of it is even possible in CarboKitten at the moment. (And I don't know what some of it means). If we are serious about this, we need better quality descriptions even here in this issue and decide on a workable output. If we decide this issue is about November 18, then we need to scale down the proposed content significantly.

[jhidding]

* Maybe provide a simple scientific question as an exercise, and provide a concise solution for it, providing people with a reduced complexity use-case

I would love this! Can you provide such a question?

[NiklasHohmann]

@jhidding just brainstorming:

• Introduce a global carbonate production modifier, and explore under what values of subsidence, sea level curve, and modifier the carbonate platform drowns
• Explore the role of production rates and diffusion values on carbonate platform geometry
• Carbonate platform growth under uplift (reversed subsidence) I think all of those are valid research questions, and can be visually solved with the current visualization options.

[xyl96]

Thanks Nik. I think changing the subsidence rate/sealevel one is very nice and I'm adding the small scientific task.

[EmiliaJarochowska]

the proposed material by Xianyi on October 1st is way to ambitious for a single tutorial session

That is why we changed it. In my email I pointed to the follow-up: https://github.com/MindTheGap-ERC/CarboKitten.jl/issues/64#issuecomment-2388004231

Is this the current specification of what needs to be done or does this need cutting down? I agree that what Xianyi proposed the day earlier was not feasible for a tutorial, but would make a great series of papers ;-)

[EmiliaJarochowska]

As for the suggestions by @NiklasHohmann , I favor this:

Explore the role of production rates and diffusion values on carbonate platform geometry

Because it does not require adding new features (unlike point 1) to CarboKitten and because we will have specialists of sediment transport in the audience, so that's a use case where they can best contribute good discussion.

[EmiliaJarochowska]

But I would say the scientific case can be added only after we agree on what to do with the points here: https://github.com/MindTheGap-ERC/CarboKitten.jl/issues/64#issuecomment-2388004231

[jhidding]

But I would say the scientific case can be added only after we agree on what to do with the points here: https://github.com/MindTheGap-ERC/CarboKitten.jl/issues/64#issuecomment-2388004231

I think most of those points are addressed in the current tutorial. We can leave point 4 as an exercise (which I'll add). As for point 7, I don't know what you mean by exporting the whole grid.

[xyl96]

I have now added plot stratigraphic column as a exercise. I also added a task of changing facies to produce different shapes of carbonate platform. For the general scientific aim and motivation and Nik's point 3, they should be in the presentation as we discussed this afternoon?

[jhidding]

Plotting stratigraphic column is way to hard as an exercise. I replaced it with a library call, but that doesn't leave much for an exercise. I really like the platform morphology task, though I'm afraid that to recreate some of these morphologies needs some additions to the transport model or other changes to CarboKitten itself. This could be fun to look into on the afternoon, or Tuesday!

[jhidding]

I managed to squeeze in an interactive demo, similar to the carbo_explorer. Also some minor improvements.

[EmiliaJarochowska]

I edited at the same time. Resolving conflicts in notebooks is a nightmare. It might be that I destroyed something, but too tired now to continue.

This seemed illogical:

If you downloaded this notebook to an empty directory, using "." would be a good choice. and then

OUTPUTDIR = "../../data/output"

If we tell people to use . then that's what should be in the example.

Btw, initial topography and bedrock elevation are not the same things. What we have in CarboKitten is initial topography (literally) i.e. heights in different grid cells, not bedrock elevation - that is just a height w/r to some arbitrary point on earth.

[EmiliaJarochowska]

I do wonder though what are all these files: Tutorial_Notebook backup 1.jl src/Burgess2013/Production 2.jl src/Burgess2013/Transport 2.jl src/CaProd 2.jl etc

git shows me a lot of gibberish on this branch

[jhidding]

Don't know about most of these. Sometimes Pluto creates a backup file, but only for opened notebooks.

[HannoSpreeuw]

I am simply executing the commands from first_tutorial: I know it's greyed out, but the ambitious user should be able to execute

run_model(Model{ALCAP}, Example.INPUT, "$(OUTPUTDIR)/example.h5")

right? However, that gives:

UndefVarError: `Model` not defined in `Main.var"workspace#28"`

So apparently an import is missing.

[jhidding]

The idea is for people to download the notebook. Have a little patience. In an hour or so, everything should work fine.