access-cm3-paper-1

A collaborative project to create and discuss figures for description and assessment paper(s) for ACCESS-CM3. Your help is welcome!

To get started, see the How it works section below.

Experiment descriptions

Currently we welcome feedback on:

• /g/data/zv30/non-cmip/ACCESS-CM3/cm3-run-11-08-2025-25km-beta-om3-new-um-params/cm3-demo-datastore/cm3-demo-datastore.json: CM3 25km ocean which is a present day control with constant forcing (year numbers are essentially meaningless). This run is not made from a released configuration/build so there is no guarantees of it being available or re-producible long-term. Ocean initial conditions are taken from a "cold start" in ACCESS-OM3 (e.g., WOA2023 January).
• /g/data/lg87/wgh581/cz861/: CM2 25km present day control run for comparison. Again year numbers are meaningless but in this case start from "1". We recommend comparing the first N years of this run to ACCESS-CM3 runs to assess the spin-up.

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 requesting access using this template.

All aspects of the project are tracked through issues, where each small task is captured in a separate issue, i.e., a single issue for each Figure. Issues will develop to include discussion of analysis methods and figures associated with each task.

The mega-issue is used to track all evaluation metrics. Additionally, evaluation metrics "ported" from OM3 evaluation are tracked seperately here.

Please use sub-issues of the mega-issue for creating new Figures and follow the checklist in the issue template.

Options for scripts/notebooks

There are 3 different levels of scripts/notebooks to enable anyone to contribute, regardless of their language or workflow preference. These reside within the access-cm3-paper-1/notebooksdirectory:

1. polished-pythoncontains scripts that have used the access-cm3-paper-1/notebook/polished-python/00_template_notebook.ipynb template as a starting point and have followed the checklist in the issue template, which includes adding the new script to access-cm3-paper-1/notebooks/polished-python/mkfigs.sh;
2. sandbox-pythoncontains scripts that create evaluation using python, but are not using the above workflow;
3. non-python contains any kind of script that creates an evaluation figure.

How to copy the access-cm3-paper-1 repo and create a notebook

To start contributing to the code, you have can either:

• Push your code changes to the main branch directly (i.e., follow the steps below, omitting the branch steps), or
• Create a new branch directly in this repository, make your changes there, and then open a pull request from your branch into main to request review (i.e., carry out all steps below.

1. Clone the access-cm3-paper-1 repository locally. Go to the directory on your local machine where you want to store the project, e.g., in your home directory or a subdirectory, such as ~/git/:

   cd ~/git/
   git clone https://github.com/ACCESS-Community-Hub/access-cm3-paper-1.git
   cd ~/git/access-cm3-paper-1/notebooks/polished-python

2. Make a new branch called YOUR-USERNAME and switch to the current branch using the -b option:

   git checkout -b YOUR-USERNAME

   To list all branches (the * indicates the branch you're on) and print the name of the upstream branch, type git branch -vvl.

3. Change into notebooks/polished-python/ directory

   cd notebooks/polished-python/

4. Copy the example notebook as YOUR-NOTEBOOK.ipynb and start hacking away. See Notebooks section below for more details.

   cp 00_template_notebook.ipynb YOUR-NOTEBOOK.ipynb

   The git status command displays information about the working directory (your local files), where you can see which changes have been staged, which haven’t, and which files aren’t being tracked by Git.

5. Add the new file to the staging area so it can be committed:

   git add YOUR-NOTEBOOK.ipynb

   If you type git status, you will see a Changes to be committed message indicating your new YOUR-NOTEBOOK.ipynb is now staged for commit.

6. Commit the new file and give a meaningful short message:

   git commit -m "Notebook for xx evaluation of ACCESS-CM3"

7. As your local YOUR-USERNAME branch has no Upstream branch to the remote repository, you need to set the Upstream branch in order to push your changes to the remote repository:

   git push --set-upstream origin YOUR-USERNAME

   Note: For the git push --set-upstream origin <branch-name> command to successfully push to a remote repository, you need to have an authentication mechanism with that remote. It is recommended to use SSH keys for authentication with Git.

   If successful you should see a branch 'YOUR-USERNAME' set up to track 'origin/YOUR-USERNAME message.

   Now you can see your active branch YOUR-USERNAME in the list of branches in the remote repository.

8. Create a New pull request for YOUR-USERNAME branch on the remote repository and follow the prompts.

   You can also see the changes you've made so far: https://github.com/ACCESS-Community-Hub/access-cm3-paper-1/commits/YOUR-USERNAME/

   Once this pull request has been reviewed and merged into main, you can delete your branch on the remote repository.

9. Include the Git hash when sharing a Figure on your github issue as detailed next in the Guidelines for Creating Figures.

   The specifics of a commit can be found in the Git hash (also known as a commit hash). This is a 40-character hexadecimal string unique identifier for every single commit in a Git repository, e.g., b7a4f2c10903c989efe3694481c9325d2040ed2b, which can be found here.

10. Add your authorship details to the citation file. You will need to have write access to the repo - if you don't, please request it.

11. If polished-python (i.e., follows the template), add your notebook to the array variable in access-cm3-paper-1/notebooks/polished-python/mkfigs.sh and test that it runs. For more details, see Notebooks section below.

Guidelines for Creating Figures

• Create an issue for the Figure you are looking to create (i.e., one issue per figure).
• Add it as a sub-issue to the mega-issue.
• When posting in the issue, please include path to notebook and the commit hash that created the Figure. The commit hash also gives run information, which you can also include in the issue. If possible:
• include a CM2 comparison;
• Average over the last 10 years;
• Once you've created your Figure and uploaded your notebook, please tick off your assigned task in the mega-issue list.
• If it's not currently possible to complete the metric due to missing diagnostics, please note that in the Missing diagnostics to do analysis issue so we can provide that output in future runs.

Notebooks

• Notebooks for figures should be in the polished-python folder.

• When starting a new notebook, please use this template.

• To enable all notebooks to be run at once, please include the following code snippet at the top of your notebook:

  #parameters
  
  ### USER EDIT start
  esm_file='/g/data/zv30/non-cmip/ACCESS-CM3/cm3-run-11-08-2025-25km-beta-om3-new-um-params/cm3-demo-datastore/cm3-demo-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-cm3-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)

  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 parameterise other parts of the notebook. This allows us to pass in arguments externally using papermill as detailed in mkfigs.sh.

• To enable notebooks to be re-run with different experiments, it's important to use the esm_file variable for the source data and save plots in the folder defined by the plotfolder variable, e.g., plt.savefig(plotfolder+'exampleout.png'). Please refer to this example notebook.

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

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