Overview
A citation is a reference to a published work. The publication can be in any form, e.g. a book, journal article, internal report, etc.
The citations for the CMIP6 models are documented and published using spreadsheets; one spreadsheet is used to collect citations for all of an institute’s models . Below are instructions for collecting citations using this spreadsheet.
1. Open the spreadsheet using Microsoft Excel, LibreOffice, or another spreadsheet editor.
The spreadsheet is found in the institutional GitHub repository in the cmip6/citations directory (see the layout of institutional GitHub repositories).
The spreadsheet is composed of three pages. The first page contains a link to these instructions.
The second page contains some example citations to demonstrate how it works.
The third page is where you can enter your own citations.
2. Create a citation
The third, “Citations” page contains an “Identifier” column for providing a unique identifier for the citation (see below) and other columns for describing the actual citation.
The citation must be described by
- either a DOI for the citation
- or a BibTeX entry for the citation
In addition, a URL may also be provided.
A DOI is the recommended way of describing a citation.
As many citations as you like can be described, each one on a separate row of the spreadsheet.
If a DOI does not exist, however, then the BibTeX option must be used. A BibTeX entry must include fields for the author, title and year of the publication and how how it was published. Any additional BibTeX fields are also allowed. Some examples of acceptable BibTeX entries:
@misc{
title = {NetCDF User's Guide},
author = {Rew, Russ and Davis, Glenn and Emmerson, Steve and Davies, Harvey},
howpublished = {http://www.unidata.ucar.edu/software/thredds/current/netcdf-java/CDM/},
year = {1997},
}
@inproceedings{
title = {Linking Data, Models and Tools: An Overview},
booktitle = {2010 International Congress on Environmental Modelling and Software Modelling for Environment's Sake},
author = {Jagers, H.R.A (Bert)},
year = {2010},
}
3. Provide an identifier for the citation
A citation is linked to model descriptions via the identifier provided in the “Identifier” column of the spreadsheet. This identifier can be anything you like, as long as no two identifiers are the same.
4. Use the identifiers to set citations in the model spreadsheets
A citation is then linked to a model realm in the “Parties & Citations” page of a model realm spreadsheet. In this page you simply enter, under the “Citations” section, the identifier of the citation as defined in the citations spreadsheet, and to which realm process it applies (left-click in the required cell in the “Process” column to activate the pull-down menu button):
If the citation applies to the realm as a whole, select the “Key Properties” process. If the citation applies to only a subset of multiple processes then enter them as separate citations.
The same citation identifier can be be used in multiple model realm spreadsheets.
To provide another citation, copy the entire row by
- right-clicking over the row number (e.g. row 17 in the above example) and selecting “Copy”,
- right-clicking again in the same place and inserting one row below, and
- pasting the copied row into the newly created row below.
The new row will have the all of the functionality of the original row, including the pull-down menu in the “Process” column.
5. Upload the citations to the institutional GitHub repository
Upload the citations spreadsheet to the institutional GitHub repository.
When the model documents are created and entered into the ES-DOC archive, the requested citations are automatically copied from the citations spreadsheet into the published model descriptions.
Updating the citations spreadsheet in the institutional GitHub repository will trigger an update to the published model documents, provided publication is set to “on” for that realm in the cmip6/model_publication.json file.