access-om3-paper-1

A collaborative project to create and discuss figures for a description and assessment paper(s) for ACCESS-OM3. Help is very welcome! Please see How it works below to get started.

The paper is being written here on Overleaf. Please ask Andrew if you'd like edit access (the link is "view only").

How it works

All community members (and ACCESS-NRI staff) can get write access to this repository (our preference over using forks). To get write access, you need to create an issue and request access, please use this issue template.

All aspects of the project are tracked through issues. Create an issue to represent each small task, a single issue is used for each Figure. Issues will develop to include discussion of analysis methods and figures associated with each task. A mega-issue exists here to track all the evaluation metrics. Feel free to add new Figure-issues as sub-issues.

To start contributing to the code, you have two options:

1. push your code changes to main directly.
2. if you'd prefer for your code changes to be reviewed, you can create a new branch directly in this repository, make your changes there, and then open a pull request from your branch into main.

Detailed instructions

For the first option above omit the branch steps below. This is option 2:

1. Clone this repository locally;
2. Make a new branch with your name git checkout -b claire;
3. cd into notebooks;
4. Copy the example notebook, and start hacking away (see Notebooks section below for the details);
5. When ready to upload, do git add <path to your notebook>, git commit -m "A helpful message" and git push -u REMOTE_NAME branch_name (where REMOTE_NAME is the name of your GitHub remote, this defaults to origin);
6. Make a PR on github to merge it into main
7. Add your authorship details to the citation file

(This assumes you have write access to the repo, if you don't you'll need to ask for it.)

Guidelines for creating Figures

• Create an issue (one per figure) for Figure you are looking to create and add it as a sub-issue to the mega-issue here.
• When posting in the issue, please include path to notebook and the commit hash that created the Figure (also gives run information but you can include this in the post for convenience).
• Try to include OM2 comparison!
• Average over the last 10 years of the RYF run
• Suggestion: pcolor / contourf will handle NaNs in coordinate arrays (if you need pcolormesh/xgcm, use the hack)
• Once you've created your Figure / uploaded your notebook, please tick off your assigned task in the list.
• If it turns out it is not currently possible to complete the metric due to missing diagnostics. Please note that here so we can continue the existing run with the needed output. (Source)

Notebooks

Notebooks for figures should be in the notebooks folder. When starting a new notebook, please use the template here.

To allow us later to run all the notebooks at once, please use the boilerplate at the top of the notebook, namely this second cell:

#parameters

### USER EDIT start
esm_file='/g/data/ol01/access-om3-output/access-om3-025/MC_25km_jra_ryf-1.0-beta/experiment_datastore.json'
dpi=300
### USER EDIT stop

import os
from matplotlib import rcParams
%matplotlib inline
rcParams['figure.dpi']= dpi

plotfolder=f"/g/data/{os.environ['PROJECT']}/{os.environ['USER']}/access-om3-paper-figs/"
os.makedirs(plotfolder, exist_ok=True)

 # a similar cell under this means it's being run in batch
print("ESM datastore path: ",esm_file)
print("Plot folder path: ",plotfolder)

It is important to use esm_file variable for the source data and save plots into the folder defined by the plotfolder variable. This allows notebooks to be easily re-run later with different experiments, here's 00_template_notebook.ipynb as an example:

datastore = intake.open_esm_datastore(
    esm_file,
    columns_with_iterables=[
        "variable",
        "variable_long_name",
        "variable_standard_name",
        "variable_cell_methods",
        "variable_units"
    ]
)

and plt.savefig(plotfolder+'exampleout.png'). This cell needs to have the tag parameters, copying this cell will copy the tag as well but you can also set this on other cells should you wish to parameterize other parts of the notebook. This allows us to pass in arguments externally using papermill (see mkfigs.sh for details)

Once you have finished your notebook, please add the name of your notebook to the array variable in this notebook. This allows us to run your new notebook as part of a suite of evaluation notebooks when assessing new simulations.