For each figure, provide citation information in a standard format

[bouweandela]

It would be nice if we could provide citation information along with the figures produced by the diagnostics. This should be in a standard format (e.g bibtex?), for easy use.

The following should be included:

• papers describing the diagnostic and recipe
• model data citation information
• observational data citation information
• esmvaltool and other scientific software citation
• scientific compute cluster citation information, if applicable

It should be fairly easy to extract the required information from the provenance.

Additional information on CMIP6 model data citation provided by Martina:

• Data Citation is provided on two granularities. The data user has to
  decide which one is appropriate for his/her study. The number of data
  citations in a reference list need to be in balance with paper
  references. Both should be included as two data reference list options.
  The granularities in DRS terms are:
  CMIP6.<mip_era>.<institution_id>.<source_id>
  CMIP6.<mip_era>.<institution_id>.<source_id>.<experiment_id>
  Example: https://cera-www.dkrz.de/WDCC/ui/cerasearch/cerarest/exportcmip6?input=CMIP6.CMIP.CNRM-CERFACS.CNRM-CM6-1.historical

• Accessing Data Citation information:
  I would recommend to use the API for ESGF data node managers at
  https://cera-www.dkrz.de/WDCC/ui/cerasearch/cerarest/cmip6Citations?
  with a JSON formatted response and the following AND-connected
  attributes: institutionId, sourceId, complete (true|false), drsId

• Link for information on CMIP6 data citation information: http://cmip6cite.wdc-climate.de

[bouweandela]

Regarding the implementation: all required information should be extracted from the recorded provenance. If some extra information is needed, it should also be recorded as provenance.

In principle, this functionality could be a command line tool that reads a provenance file and writes a references file in e.g. bibtex format, though in practice it probably makes more sense to integrate this into the normal esmvaltool run. A good way to add this would probably be to create a DiagnosticTask._write_references_file() method and calling it just after this line:

ESMValCore/esmvalcore/_task.py

Line 508 in 0cfe7fb

self._collect_provenance()

It may be necessary to update config-refrences.yml to provide the references in a more structured format than just strings for this to work.

[SarahAlidoost]

@mattiarighi: the config-references.yml will be used in the implementation of this issue. In this file, there is an instruction to fill out the entries.
For example, in the section "references" : # If possible as: "[Last name] et al., [journal abbr.], doi:[doi], [year]."

However, some of the entries don't follow this instruction. Also, I am wondering why there is no "title" of the articles in the instruction.

For a useful Bibtex file, I suggest changing the instruction to [First author name] et al., [title], [journal abbr.], [volume], [pages], doi:[doi], [year]. Then it would be easy to split the entries on "," and get the information that should be included in a Bibtex file.
Please let me know what you think. Thanks.

[mattiarighi]

The idea behind that was to keep the reference entry short, possibly within 1 line (given also the 80-charachter limit for yaml, now extended to 120).

Since the doi uniquely identifies a reference, it would actually be enough to specify that, but I added author, journal and year to make it more readable.

Some entries do indeed not follow this instruction, this is mostly the case for technical reports or web sources, for which a doi is not provided (this is also challenging with bibtex sometimes).

If we want to switch to BibTex for all references, fine with me, but it will result in a significantly longer file. Also consider that typically the users are not very careful with such details, so increasing the amount of information to be provided would also increase the maintainance effort from our side.

Another possibility could be to replace the references with actual bibtex files. For example, cox18nature would point to cox18nature.bib and all bib files could be collected in doc/bibtex or wherever. This could be automated using doi2bib.

[SarahAlidoost]

@mattiarighi Thanks a lot. As you suggested, I think the use of the doi and something like doi2bib will solve the problem.

[bouweandela]

I would recommend creating a directory esmvaltool/references and storing the downloaded bibtex files there.

[SarahAlidoost]

@mattiarighi and @bouweandela now "citation information" is stored along with the files produced by diagnostics (draft PR). This is in a standard format bibtex. The information are those mentioned as "reference/s" in provenance.
I am wondering if there is other information that should be also considered as "citation information". 
Thanks.

[mattiarighi]

Very nice addition @SarahAlidoost, thanks!

There are (will be) 4 papers documenting ESMValTool v2.0:

• Righi et al. (2019) is the technical overview and should always be cited.

The other three document the new diagnostics and should be cited depending on the diagnostics contained in the recipe being run:

• Eyring et al. (2019)
• Lauer et al. (in prep.)
• Weigel et al. (in prep.)

To keep it simple, we could also cite all of them in the log file.

Note that Righi et al. and Eyring et al. are still in discussion and the citation will change once published in their final form.