Template for README files for model configuration input files

[aidanheerdegen]

We need a template and accompanying guidelines for README files for model configuration input files to reduce reproducibility debt.

Here are some links with useful sources:

A nice fairly minimal one:

https://zenodo.org/records/12745572/files/Readme%20for%20Datasets%20Guide.pdf?download=1

Bit more academic focus, and probably more detail than is required

https://data.research.cornell.edu/data-management/sharing/readme/

[aidanheerdegen]

A first-pass example

This readme file was generated on [YYYY-MM-DD] by [NAME]

[TITLE OF DATASET]

Contact(s)

Name:
Email:
Institution: ACCESS-NRI

Data Access and Sharing

• Licenses/restrictions placed on the data:
  * Links to publications that cite or use the data:
• Links to other publicly accessible locations of the data:
• Links/relationships to ancillary data sets:
• Was data derived from another source?
  * If yes, list source(s):
• Recommended citation for this dataset:

Data and Files

File List: list all files (or folders, as appropriate for dataset organization) contained in the dataset, with a brief description

• Relationship between files, or a description of the file structure:
• Are there multiple versions of the dataset?
  * If yes, name of file(s) that was updated:
  * Why was the file updated?
  * When was the file updated?

Data Specific Information

For each file without embedded metadata include

• A brief description of the data in each file
• List and define column headings in tabular data, units of measurement, date formats, variables, acronyms, abbreviations, labels, scoring of categorical data.
• Explain how missing data are represented (e.g., NA or blank).

Methodological information

• Workflow and processing steps to replicate analysis; this includes scripts,
  code, packages, notebooks, and software used to process the data

[aidanheerdegen]

Question: Would it be better to go for a human and computer readable format (YAML)?
Follow-up Question: If yes to above, then we should probably have a schema to validate it.

[joshuatorrance]

* Was data derived from another source?
  * If yes, list source(s) **and their license(s)**:

Should we prompt people to list the the licenses of the source datasets? This might encourage people to consider any restrictions that the input data might impose. On the other hand, this would bloat things a bit as some datasets have restrictions/licenses that cannot be concisely described.

[aidanheerdegen]

Should we prompt people to list the the licenses of the source datasets? This might encourage people to consider any restrictions that the input data might impose. On the other hand, this would bloat things a bit as some datasets have restrictions/licenses that cannot be concisely described.

I guess the answer is yes, but in the "it's complicated" case link to licensing detail elsewhere?

We might need to build up a bit of experience to get a feeling for where the line is drawn.

[blimlim]

Links to other publicly accessible locations of the data:
Links to publications that cite or use the data:

Would these two potentially require the README's to be regularly updated?

[aidanheerdegen]

Would these two potentially require the README's to be regularly updated?

Good point. Let's not include the publications that cite. Links to other publicly accessible locations seems harmless enough as it provides another possible source if the NCI location is not accessible, and I don't see a need to keep it updated.

This might have been fairly moot until today, but we're now making the READMEs visible on the repo, so outside collaborators or interested parties could download the data from another location.

[blimlim]

@penguian, we're discussing providing README files documenting each of the model input files on vk83. It would be great to get your thoughts on the above proposed README template, as we'd likely rely on you for many details on the CMIP7 inputs.

[penguian]

I noticed "Methodological information: Workflow and processing steps to replicate analysis; this includes scripts, code, packages, notebooks, and software used to process the data."

By "replicate analysis" with respect to CMIP7-Input, does this mean replicate the data transformation from the CMIP7 forcing dataset to the model configuration input file? What role is the documentation in CMIP7-Input expected to play? Should the methodological information here for the CMIP7 ancillaries be a very brief summary point to the CMIP7-Input documentation?

Also, where would the data transformation for the CMIP7 greenhouse gas forcings be documented, since the corresponding input is in atmnosphere/namelists in the configuration?

[aidanheerdegen]

By "replicate analysis" with respect to CMIP7-Input, does this mean replicate the data transformation from the CMIP7 forcing dataset to the model configuration input file? What role is the documentation in CMIP7-Input expected to play? Should the methodological information here for the CMIP7 ancillaries be a very brief summary point to the CMIP7-Input documentation?

If there is existing documentation then linking to should be sufficient, but a brief summary as well is never a bad idea.

Also, where would the data transformation for the CMIP7 greenhouse gas forcings be documented, since the corresponding input is in atmnosphere/namelists in the configuration?

If there is no file in the configurations/input directory tree then there is no need for a README in this repo.

[blimlim]

An example README for the esm-flat10-cdr CO2 emissions ancillary file:

This readme file was generated on 2026.05.27 by Spencer Wong

Flat10-CDR CO2 flux
Contact(s)
Name: Spencer Wong
Email: spencer.wong@anu.edu.au
Institution: ACCESS-NRI

Data Access and Sharing
Licenses/restrictions placed on the data: CC-BY-4.0
Links to other publicly accessible locations of the data: N/A
Links/relationships to ancillary data sets: This dataset uses the same CO2 emissions value to represent
10GtC/year as the flat10 emissions ancillary (/g/data/vk83/configurations/inputs/access-esm1p6/modern/flat10/atmosphere/forcing/global.N96/2025.12.05/CO2_fluxes_flat10.anc), rounded to 7 decimals.
Was data derived from another source? No
Recommended citation for this dataset: https://doi.org/10.5194/gmd-17-8141-2024


Data and Files
File List: CO2_fluxes_flat10CDR.anc
Relationship between files, or a description of the file structure: N/A
Are there multiple versions of the dataset? No

Data Specific Information
CO2_fluxes_flat10CDR.anc contains gridded time varying CO2 fluxes to the atmosphere in kg(CO2)/m2/s, for use in the CMIP7 esm-flat10-cdr experiment. Emissions evolve following the specification in https://doi.org/10.5194/gmd-17-8141-2024 (Table 1). Total emissions initially decline linearly from 10GtC/year to -10GtC/year over 100 years, remain flat at -10GtC/year for 100 years, and swap to 0 emissions for the remaining years. A 200 year period of zero emissions has been chosen here. During the interpolation, emissions values change between years but remain constant within each year.

This dataset starts at year 301 to match the starting year in the restart file (/g/data/vk83/configurations/inputs/access-esm1p6/modern/flat10-zec/restart/2026.05.27) selected for the esm-flat10-cdr experiment.

Stash codes: s00i251
Units: kg(CO2)/m2/s


Methodological information
This file was generated with commit f745597 of https://github.com/ACCESS-NRI/CMIP7-Input/pull/130, using the arguments "--year-start 301 --nyear-zero 200".

[aidanheerdegen]

This is great @blimlim and I think illustrates really nicely how much value adding README info like this can add. I don't know anything about that data, but after reading that I know a lot more, and how to dig deeper if I need to. Wonderful!

[ccarouge]

I'm sorry to be picky but since @aidanheerdegen shared this widely... That's great information @blimlim , my only remark is it does not tell me how it is different from the flat10 emission file. When I read this:

Links/relationships to ancillary data sets: This dataset uses the same CO2 emissions value to represent
10GtC/year as the flat10 emissions ancillary (/g/data/vk83/configurations/inputs/access-esm1p6/modern/flat10/atmosphere/forcing/global.N96/2025.12.05/CO2_fluxes_flat10.anc), rounded to 7 decimals.

I think, they are the same files. I'm guessing the explanation at the end:

Data Specific Information
CO2_fluxes_flat10CDR.anc contains gridded time varying CO2 fluxes to the atmosphere in kg(CO2)/m2/s, for use in the CMIP7 esm-flat10-cdr experiment. Emissions evolve following the specification in https://doi.org/10.5194/gmd-17-8141-2024 (Table 1). Total emissions initially decline linearly from 10GtC/year to -10GtC/year over 100 years, remain flat at -10GtC/year for 100 years, and swap to 0 emissions for the remaining years. A 200 year period of zero emissions has been chosen here. During the interpolation, emissions values change between years but remain constant within each year.

This dataset starts at year 301 to match the starting year in the restart file (/g/data/vk83/configurations/inputs/access-esm1p6/modern/flat10-zec/restart/2026.05.27) selected for the esm-flat10-cdr experiment.

would be different for the flat10 experiment, but I would guess this README does not exist. I would also think we would get more information on the experiment documentation you are working on for the ESM1.6 configs docs, but the READMEs here will likely pre-date the docs (but can be updated later).

Anyway, a long and windy way to explain that I think it is great to highlight relationships between the input files, but we should be careful to make the differences clear in some way (a link to somewhere else is fine).

[blimlim]

Thanks @ccarouge, would the following make a bit clearer that it's not a direct duplicate of the flat10 file:

Links/relationships to ancillary data sets: This dataset uses a value of `2.2802997e-09`kg/m2/s  to represent 10GtC/year. This value is copied from the flat10 emissions ancillary (/g/data/vk83/configurations/inputs/access-esm1p6/modern/flat10/atmosphere/forcing/global.N96/2025.12.05/CO2_fluxes_flat10.anc) and rounded to 7 decimals.