CMIP6 > ES-DOC liaison checklist

ES-DOC liaison checklist for CMIP6

This checklist describes in detail how to create CMIP6 documentation and is primarily intended to be used by ES-DOC liaisons working within a modelling institute.

The order of processes in the list reflects the order in which should tasks should be started, but not necessarily finished. For example, you may want to start documenting experimental conformance whilst the model documentation is still ongoing.

Any questions about this process are welcomed via e-mail at support@es-doc.org

This is an evolving document. Last updated: 2019-12-16

Contents

  1. Background reading
  2. The institutional GitHub repository
    2.1 Layout of files
    2.2 Using GitHub
  3. Model documentation
    3.1 Initialize model documentation
    3.1.1 Initialization from a CMIP5 model
    3.1.2 Initialization from a CMIP6 model
    3.2 Create model documentation
    3.2.1 Best practices for using the model documentation spreadsheets
    3.3 Publish the model documentation
    3.4 Check the model documentation
  4. Conformance documentation
  5. Simulation and Ensemble documentation
  6. Machine and Performance documentation

1. Background Reading

  • Familiarize yourself with the overall CMIP6 documentation process, starting at https://es-doc.org/cmip6 and following the links contained in this page.

2. The institutional GitHub repository

  • GitHub is a collaboration platform that lets multiple people work together on the same files.
  • Yourself and the ES-DOC team will share access to a GitHub repository, called the “institutional GitHub repository”, containing the resources that you can use to create CMIP6 documentation.
  • The repository for each institute is listed at https://github.com/ES-DOC-INSTITUTIONAL. For example, the institutional GitHub repository for the MIROC institute is https://github.com/ES-DOC-INSTITUTIONAL/miroc.
  • To access the shared repository you must have a GitHub account. The repository will only be accessible by this account and by the ES-DOC team. Tell ES-DOC the GitHub account name (e-mail to support@es-doc.org) so that access may be granted.

2.1 Layout of files

2.2 Using GitHub

  • To use the files in your institutional GitHub repository, we recommend that the repository is “cloned” to get the files on to your local computer, either from the command line or using a desktop client (many of which are available, e.g. GitHub Desktop). Edited files may then be “committed” and “pushed” back to the on-line institutional GitHub repository.
  • It is also possible to edit plain-text files directly on the GitHub site, as described in this guide.

3. Model documentation

The following process applies to the general documentation system provided by ES-DOC. If you plan to use a bespoke internal system to generate model documentation, please contact ES-DOC to discuss this further. If you’re unsure as to whether this is the case, then it is certain that you’ll want to use the general system described here.

3.1 Initialize model documentation

  • Initialization of model descriptions from other, already documented, models is not a requirement, but can reduce the workload (sometimes by a very large amount) in cases when a realm’s description is similar to another, already described, realm. There are two types of initialization:
    1. from a CMIP5 model
    2. from a CMIP6 model.

    After initialization, the description  may be edited, both to set still unanswered questions, and to change inappropriate answers coming the from other model.

3.1.1 Initialization from a CMIP5 model

    • Initialization from an existing CMIP5 model is possible if such a description is available. The available CMIP5 model descriptions are listed in the cmip5/models directory. If this directory does not exist, then this type of initialization is not possible. The files in this directory must not be edited, but merely serve to inform which CMIP5 models can be used.
    • Initializing a realm from an existing CMIP5 model description is specified by editing the cmip6/models/initialization_from_CMIP5.json plain-text configuration file in the institutional GitHub repository. This configuration file allows you to specify how you would like to initialize each realm of each of your institute’s models. For example, the configuration file for the IPSL institute’s models is
ipsl/cmip6/models/model-initialization.json
  • For each model realm that is to be initialized from a CMIP5 model, set the relevant  initializedFrom field in the configuration file to the value “cmip5:<model>”, where <model> is the official CMIP5 model name of the from which the information is to be gathered (e.g. “cmip5:miroc4h”).
  • In this example of a completed model configuration file, the description of the aerosol realm of the gfdl-am4 model is to be initialized from the CMIP5 gfdl-cm3 model; and the sea ice component of the gfdl-esm4 model is to be left uninitialized.
  • When you have finished editing the configuration file, make sure that the latest version is on GitHub and tell ES-DOC that you have finished configuring the documentation initialization (e-mail to support@es-doc.org).
  • ES-DOC will then copy values from the CMIP5 model descriptions into the CMIP6 spreadsheets, and will let you know when they are ready for further editing.

3.1.2 Initialization from a CMIP6 model

  • Initializing a realm from an existing CMIP6 model description follows a different process than initializing from a CMIP5 model
  • To initialize a realm of a CMIP6 model from the realm another CMIP6 model, simply copy the spreadsheet file of the other realm. (Copy the file on the filesystem rather than copying rows and columns within a spreadsheet editor.)
  • It is essential to rename the new spreadsheet by replacing the model name (and institute, if required) in the file name. In addition, the institute and model name must be similarly changed on the front page of the new spreadsheet.
  • For example, to initialize the ocean realm of the BCC model ESM1 from the ocean realm of the BCC model CSM2-MR, copy the spreadsheet 
    bcc/cmip6/models/bcc-csm2-mr/cmip6_bcc_csm2-mr_ocean.xlsx

    to the new spreadsheet

    bcc/cmip6/models/bcc-esm1/cmip6_bcc_esm1_ocean.xlsx
  • The new spreadsheet may then be edited, added to the git index (e.g. with the command “git add”) and checked in as usual.

3.2 Create model documentation

    • Each realm of each CMIP6 model is published separately.
    • Open the spreadsheet for each model realm  to edit its description. Most spreadsheet software may be used (LibreOffice calc, Microsoft excel, Google sheets, Apple numbers, etc.). However, it is important that all spreadsheets are saved in Microsoft .xlsx format.
    • Instructions for using the spreadsheets may be  found at https://es-doc.org/how-to-use-model-document-spreadsheets. The link to this page is also given in the spreadsheets themselves, so that the spreadsheets are self-describing to whomever is using the them.
    • If initialization from another model has occurred, then remember that the pre-filled values should still be reviewed in case they don’t, in fact, apply to the CMIP6 model being documented.
    • In the each model folder in the GitHub repository there are also PDF documents describing the model realms (which will  contain any values initialized from a CMIP5 model). These may be useful when discussing the documentation, but the description still needs to be entered into the spreadsheets.

    3.2.1 Best practices for using the model documentation spreadsheets

    • If a question is not applicable to your model, then rather than leaving the answer blank, enter “Not applicable” instead.
    • When entering values, do not refer to the answers of questions entered elsewhere. If the answers to questions are the same, then their text should be repeated. This is because such answers will not produce useful results when documents from multiple models are compared. For example, and answer of “See the description of the ocean model” is not acceptable.
    • When entering an “Other: document in cell to right” option from a pull-down menu of options, be sure to enter the other value in to the cell directly to the right. Any entries in this column that do not correspond to an “other” option will be ignored in the published documentation.

  •  

    3.2.2 Citations

    • Each model realm requires citations (i.e. published references) to be included. These are collected in the cmip6/citations/citations.xlsx spreadsheet.
    • The link between this spreadsheet and the model description spreadsheets is made via an “ES-DOC identifier” that must be accompany each citation’s description. The ES-DOC identifier is arbitrary, but no two identifiers must be the same. This is demonstrated with an example in the  citations spreadsheet.
    • Whenever a citation is needed in the model documentation, its ES-DOC identifier should be entered that has been defined in the citations spreadsheet.
    • Full details on creating and linking citations are available  at https://es-doc.org/how-to-use-model-citation-spreadsheets.

    3.2.3 Responsible parties

    • Each model may have responsible parties (i.e. people or organizations involved with the model) included. These are collected in the cmip6/responsible_parties/responsible_parties.xlsx spreadsheet.
    • The link between this spreadsheet and the model description spreadsheets is made via an “ES-DOC identifier” that must be accompany each responsible party’s description. The ES-DOC identifier is arbitrary, but no two identifiers must be the same. This is demonstrated with an example in the  responsible parties spreadsheet.
    • Whenever a responsible party is needed in the model documentation, its ES-DOC identifier should be entered that has been defined in the responsible parties spreadsheet.
    • Full details on creating and linking responsible parties are available at https://es-doc.org/how-to-use-model-responsible-party-spreadsheets.

    3.2.4 Coupling

    • How two model realms interact with each other, via the sharing of physical variables, is captured with the model’s coupling spreadsheet, which may be found in the cmip6/models folder.
    • Full details on how to creating coupling details are available at https://es-doc.org/how-to-use-coupling-spreadsheets.

  •  

    3.3 Publish the model documentation

    • Publication of a model realm description means getting the documentation entered into the ES-DOC archive and making it publicly available through the ES-DOC viewer at https://search.es-doc.org.
    • The model realm descriptions may be published at any stage of the documentation process, whether partially complete or complete. Publishing partially complete documentation, as an interim step, is encouraged as it allows the contributors to check the descriptions on-line.
    • You control whether or not you would like to publish a realm’s description via the cmip6/models/model_publication.json plain-text configuration file in your institutional GitHub repository.
    • By default, nothing is published.
    • To activate publication for a particular model’s realm, edit the configuration file to change the relevant  “publish” field to the value “on” and save the file to GitHub.
    • Publication is not instantaneous, but will occur within 24 hours. As long as publication is activated for a realm, all changes to the realm spreadsheet that are saved to GitHub will be published on a daily basis.
    • Publication may be deactivated at any time by editing the configuration file to change the relevant  “publish” field to the value “off” and save the file to GitHub. Changes to the realm spreadsheet that are pushed to GitHub will no longer be  published until the value is changed back to “on”.
    • It is important to note that deactivating publication does not remove any existing documentation from the archive nor the ES-DOC viewer.

    3.4 Check the model documentation

    • Search for newly published model documentation in the  beta testing ES-DOC viewer at https://search.es-doc.org . At this site, select “Model” in the “Document Type” menu and select the model that you wish to view.
    • If changes are needed, simply edit the spreadsheet and check the changes in to the institutional repository.
    • The realm will subsequently be automatically republished (assuming that the publication is still on in the model_publication.json configuration file), and the republished version will be the default document returned by the ES-DOC viewer (https://search.es-doc.org).

     

    4. Conformance documentation (not yet available)

     

    4.1 Initialize model conformances (not yet available)

    • Many requirements are used by multiple experiments and their conformance to them may be the same when applied to more than one model. Therefore, to reduce the documentation workload, default conformances to such requirements may be recorded so that they may be reused across many experiments and models.
    • From your institutional GitHub repository, checkout the spreadsheet called cmip6/simulations/cmip6_conformances_default.xlsx. This spreadsheet lists all of the experimental requirements that are used in multiple experiments.
    • For each requirement in the spreadsheet, enter as many conformance details as possible that are correct for most of the experiments and model to which it applies.
    • Entering a default conformance is optional, but entering as many as possible will reduce the workload.
    • Note that there will be an opportunity during the next stage to override any of these default details for individual experiments.
    • Check the updated spreadsheet back into your institutional GitHub repository and tell ES-DOC that you have finished editing the default spreadsheet (e-mail to ES-DOC support).
    • ES-DOC will then create new spreadsheets, one for each model and MIP combination, in which each requirement for every experiment can be documented. In these spreadsheets the default descriptions from the previous stage will be pre-filled.

    4.2 Describe model conformances (not yet available)

    • ES-DOC will create new spreadsheets, one for each model and MIP combination, in which each requirement for every experiment can be documented, and let you know when these are ready. In these spreadsheets the default descriptions from the previous stage will be pre-filled.
    • In these spreadsheets, any descriptions not provided by the defaults may be entered, and any default values that have been pre-filled but do not apply to a particular model and experiment may be edited.
    • To be published, each conformance needs to be marked in the spreadsheet as verified, primarily to ensure that inappropriate default values are not being applied by mistake.

    4.3 Publish the conformance documentation (not yet available)

    • When you are ready for verified conformances to be published, edit the cmip6/publish_conformances.json configuration file.
    • By default, each conformance is not published, but when requested in the configuration file, changes to the spreadsheets  that have been checked in will be  published to the public ES-DOC archive on a daily basis.
    • The configuration file may be changed at any time to turn automatic publication off or on.
    • Published documents are ingested into the ES-DOC archive.

    5. Simulation and ensemble documentation (not yet available)

    6. Machine and Performance documentation (not yet available)