How to get citations ? (Basic version)¶

Citations can be retrieved with the help of the Persistent IDentifiers (PIDs). In the CMIP world, there are two types of PIDs:

* file PID (normally referred to as a tracking ID)
* dataset PID (normally simply referred to as PID).

A dataset is a collection of files (for CMIP, this collection of files is for a single variable sampled at a single frequency and spatial sampling from a single model running a single experiment). Both PID types can be given as input.

Imports¶

In [1]:

import traceback

from cmipcite.citations import get

import traceback from cmipcite.citations import get

Python API¶

First, we show how to do this via the Python API. There is a simple get function that allows the user to easily get a citation. This function has sensible defaults and the same arguments as the CLI api (see below).

In [2]:

citations = get(["hdl:21.14100/90f93a05-357c-4ea2-b61f-bf2418700791"])
print(citations[0])

citations = get(["hdl:21.14100/90f93a05-357c-4ea2-b61f-bf2418700791"]) print(citations[0])

Swart, Neil Cameron; Cole, Jason N.S.; Kharin, Viatcheslav V.; Lazare, Mike; Scinocca, John F.; Gillett, Nathan P.; Anstey, James; Arora, Vivek; Christian, James R.; Jiao, Yanjun; Lee, Warren G.; Majaess, Fouad; Saenko, Oleg A.; Seiler, Christian; Seinen, Clint; Shao, Andrew; Solheim, Larry; von Salzen, Knut; Yang, Duo; Winter, Barbara; Sigmond, Michael (2019): CCCma CanESM5 model output prepared for CMIP6 CMIP. Version 20190429. Earth System Grid Federation. https://doi.org/10.22033/ESGF/CMIP6.1303.

Instead of an id, you can also pass a path to a file.

In [3]:

data_file = "tests/test-data/sftlf_fx_CanESM5_historical_r1i1p1f1_gn.nc"
citations = get([data_file])
print(citations[0])

data_file = "tests/test-data/sftlf_fx_CanESM5_historical_r1i1p1f1_gn.nc" citations = get([data_file]) print(citations[0])

Swart, Neil Cameron; Cole, Jason N.S.; Kharin, Viatcheslav V.; Lazare, Mike; Scinocca, John F.; Gillett, Nathan P.; Anstey, James; Arora, Vivek; Christian, James R.; Jiao, Yanjun; Lee, Warren G.; Majaess, Fouad; Saenko, Oleg A.; Seiler, Christian; Seinen, Clint; Shao, Andrew; Solheim, Larry; von Salzen, Knut; Yang, Duo; Winter, Barbara; Sigmond, Michael (2019): CCCma CanESM5 model output prepared for CMIP6 CMIP. Version 20190429. Earth System Grid Federation. https://doi.org/10.22033/ESGF/CMIP6.1303.

You can specify author list style.

In [4]:

citations = get(
    ["hdl:21.14100/90f93a05-357c-4ea2-b61f-bf2418700791"],
    author_list_style="short",
)
print(citations[0])

citations = get( ["hdl:21.14100/90f93a05-357c-4ea2-b61f-bf2418700791"], author_list_style="short", ) print(citations[0])

Swart et al. (2019): CCCma CanESM5 model output prepared for CMIP6 CMIP. Version 20190429. Earth System Grid Federation. https://doi.org/10.22033/ESGF/CMIP6.1303.

You can specify the output format.

In [5]:

citations = get(
    ["hdl:21.14100/90f93a05-357c-4ea2-b61f-bf2418700791"],
    format="bibtex",
)
print(citations[0])

citations = get( ["hdl:21.14100/90f93a05-357c-4ea2-b61f-bf2418700791"], format="bibtex", ) print(citations[0])

@misc{https://doi.org/10.22033/esgf/cmip6.1303,
  doi = {10.22033/ESGF/CMIP6.1303},
  url = {http://cera-www.dkrz.de/WDCC/meta/CMIP6/CMIP6.CMIP.CCCma.CanESM5},
  author = {Swart, Neil Cameron and Cole, Jason N.S. and Kharin, Viatcheslav V. and Lazare, Mike and Scinocca, John F. and Gillett, Nathan P. and Anstey, James and Arora, Vivek and Christian, James R. and Jiao, Yanjun and Lee, Warren G. and Majaess, Fouad and Saenko, Oleg A. and Seiler, Christian and Seinen, Clint and Shao, Andrew and Solheim, Larry and von Salzen, Knut and Yang, Duo and Winter, Barbara and Sigmond, Michael},
  keywords = {CMIP6, climate, CMIP6.CMIP.CCCma.CanESM5},
  language = {en},
  title = {CCCma CanESM5 model output prepared for CMIP6 CMIP. Version 20190429.},
  publisher = {Earth System Grid Federation},
  year = {2019},
  copyright = {Creative Commons Attribution 4.0 International}
}

There are multiple possibilities for the retrieved DOI. These vary based on the granularity of the DOI. At the moment, as far as we know, there are two granularities: * model (capturing all submissions to a given MIP by a given model) * DRS: <mip_era>/<activity_id>/<institution_id>/<source_id> * experiment (capturing all submissions to a given MIP by a given model for a given experiment. * DRS: <mip_era>/<activity_id>/<institution_id>/<source_id>/<experiment_id> This is controlled by doi_granularity.

In [6]:

citations = get(
    ["hdl:21.14100/90f93a05-357c-4ea2-b61f-bf2418700791"],
    doi_granularity="experiment",
)
print(citations[0])

citations = get( ["hdl:21.14100/90f93a05-357c-4ea2-b61f-bf2418700791"], doi_granularity="experiment", ) print(citations[0])

Swart, Neil Cameron; Cole, Jason N.S.; Kharin, Viatcheslav V.; Lazare, Mike; Scinocca, John F.; Gillett, Nathan P.; Anstey, James; Arora, Vivek; Christian, James R.; Jiao, Yanjun; Lee, Warren G.; Majaess, Fouad; Saenko, Oleg A.; Seiler, Christian; Seinen, Clint; Shao, Andrew; Solheim, Larry; von Salzen, Knut; Yang, Duo; Winter, Barbara; Sigmond, Michael (2019): CCCma CanESM5 model output prepared for CMIP6 CMIP historical. Version 20190429. Earth System Grid Federation. https://doi.org/10.22033/ESGF/CMIP6.3610.

Multiple citations can also be retrieved.

In [7]:

citations = get(
    [
        "hdl:21.14100/f2f502c9-9626-31c6-b016-3f7c0534803b",
        "hdl:21.14100/a31d6f22-4066-3e30-913f-501509086357",
        "hdl:21.14100/f821d2df-4b10-3afc-a17d-119b9c24ba3c",
    ],
)
print(f"Retrieved {len(citations)} citations")
print()
print("\n\n".join(citations))

citations = get( [ "hdl:21.14100/f2f502c9-9626-31c6-b016-3f7c0534803b", "hdl:21.14100/a31d6f22-4066-3e30-913f-501509086357", "hdl:21.14100/f821d2df-4b10-3afc-a17d-119b9c24ba3c", ], ) print(f"Retrieved {len(citations)} citations") print() print("\n\n".join(citations))

Retrieved 3 citations

Wieners, Karl-Hermann; Giorgetta, Marco; Jungclaus, Johann; Reick, Christian; Esch, Monika; Bittner, Matthias; Legutke, Stephanie; Schupfner, Martin; Wachsmann, Fabian; Gayler, Veronika; Haak, Helmuth; de Vrese, Philipp; Raddatz, Thomas; Mauritsen, Thorsten; von Storch, Jin-Song; Behrens, Jörg; Brovkin, Victor; Claussen, Martin; Crueger, Traute; Fast, Irina; Fiedler, Stephanie; Hagemann, Stefan; Hohenegger, Cathy; Jahns, Thomas; Kloster, Silvia; Kinne, Stefan; Lasslop, Gitta; Kornblueh, Luis; Marotzke, Jochem; Matei, Daniela; Meraner, Katharina; Mikolajewicz, Uwe; Modali, Kameswarrao; Müller, Wolfgang; Nabel, Julia; Notz, Dirk; Peters-von Gehlen, Karsten; Pincus, Robert; Pohlmann, Holger; Pongratz, Julia; Rast, Sebastian; Schmidt, Hauke; Schnur, Reiner; Schulzweida, Uwe; Six, Katharina; Stevens, Bjorn; Voigt, Aiko; Roeckner, Erich (2019): MPI-M MPIESM1.2-LR model output prepared for CMIP6 CMIP. Version 20211412. Earth System Grid Federation. https://doi.org/10.22033/ESGF/CMIP6.742.

Voldoire, Aurore (2019): CNRM-CERFACS CNRM-CM6-1 model output prepared for CMIP6 ScenarioMIP. Version 20190219. Earth System Grid Federation. https://doi.org/10.22033/ESGF/CMIP6.1384.

EC-Earth Consortium (EC-Earth) (2019): EC-Earth-Consortium EC-Earth3 model output prepared for CMIP6 CMIP. Version 20200412. Earth System Grid Federation. https://doi.org/10.22033/ESGF/CMIP6.181.

On ESGF, a file can be part of multiple datasets. In such a case, the citation to use is ambiguous.

In [8]:

# Trying to get the citation for a dataset
# that is part of multiple datasets gives an error.
try:
    get(["hdl:21.14100/cfb3c24b-921a-49af-8b7b-1346c764e750"])
except ValueError:
    traceback.print_exc(limit=0, chain=False)

# Trying to get the citation for a dataset # that is part of multiple datasets gives an error. try: get(["hdl:21.14100/cfb3c24b-921a-49af-8b7b-1346c764e750"]) except ValueError: traceback.print_exc(limit=0, chain=False)

ValueError: One of your input values is a member of more than one dataset. You can resolve this by passing a value for the `multi_dataset_handling` argument. In most cases, adding `from cmipcite.tracking_id import MultiDatasetHandlingStrategy` and then using `multi_dataset_handling=MultiDatasetHandlingStrategy.LATEST` is what you will want (this will give you the reference to the last published dataset that includes your ID).

In this case, you as the user have to specify the strategy you would like to use to pick a specific dataset.

In [9]:

multi_member_cite = get(
    ["hdl:21.14100/cfb3c24b-921a-49af-8b7b-1346c764e750"],
    # Get the latest dataset
    multi_dataset_handling="latest",
)
print(multi_member_cite)

multi_member_cite = get( ["hdl:21.14100/cfb3c24b-921a-49af-8b7b-1346c764e750"], # Get the latest dataset multi_dataset_handling="latest", ) print(multi_member_cite)

['Good, Peter; Sellar, Alistair; Tang, Yongming; Rumbold, Steve; Ellis, Rich; Kelley, Douglas; Kuhlbrodt, Till; Walton, Jeremy (2019): MOHC UKESM1.0-LL model output prepared for CMIP6 ScenarioMIP. Version 20210205. Earth System Grid Federation. https://doi.org/10.22033/ESGF/CMIP6.1567.']

Command-line interface¶

More or less the same as the above, but from the command line instead.

In [10]:

!cmipcite get 'hdl:21.14100/90f93a05-357c-4ea2-b61f-bf2418700791'

!cmipcite get 'hdl:21.14100/90f93a05-357c-4ea2-b61f-bf2418700791'

Swart, Neil Cameron; Cole, Jason N.S.; Kharin, Viatcheslav V.; Lazare, Mike; Scinocca, John F.; Gillett, Nathan P.; Anstey, James; Arora, Vivek; Christian, James R.; Jiao, Yanjun; Lee, Warren G.; Majaess, Fouad; Saenko, Oleg A.; Seiler, Christian; Seinen, Clint; Shao, Andrew; Solheim, Larry; von Salzen, Knut; Yang, Duo; Winter, Barbara; Sigmond, Michael (2019): CCCma CanESM5 model output prepared for CMIP6 CMIP. Version 20190429. Earth System Grid Federation. https://doi.org/10.22033/ESGF/CMIP6.1303.

In [11]:

!cmipcite get 'hdl:21.14100/90f93a05-357c-4ea2-b61f-bf2418700791' \
  --author-list-style short

!cmipcite get 'hdl:21.14100/90f93a05-357c-4ea2-b61f-bf2418700791' \ --author-list-style short

Swart et al. (2019): CCCma CanESM5 model output prepared for CMIP6 CMIP. Version 20190429. Earth System Grid Federation. https://doi.org/10.22033/ESGF/CMIP6.1303.

In [12]:

!cmipcite get 'hdl:21.14100/cfb3c24b-921a-49af-8b7b-1346c764e750' \
    --multi-dataset-handling latest --format bibtex

!cmipcite get 'hdl:21.14100/cfb3c24b-921a-49af-8b7b-1346c764e750' \ --multi-dataset-handling latest --format bibtex

@misc{https://doi.org/10.22033/esgf/cmip6.1567,
  doi = {10.22033/ESGF/CMIP6.1567},
  url = {http://cera-www.dkrz.de/WDCC/meta/CMIP6/CMIP6.ScenarioMIP.MOHC.UKESM1-0-LL},
  author = {Good, Peter and Sellar, Alistair and Tang, Yongming and Rumbold, Steve and Ellis, Rich and Kelley, Douglas and Kuhlbrodt, Till and Walton, Jeremy},
  keywords = {CMIP6, climate, CMIP6.ScenarioMIP.MOHC.UKESM1-0-LL},
  language = {en},
  title = {MOHC UKESM1.0-LL model output prepared for CMIP6 ScenarioMIP. Version 20210205.},
  publisher = {Earth System Grid Federation},
  year = {2019},
  copyright = {Creative Commons Attribution 4.0 International}
}

If you wish, you can save the output directly to a file.

In [13]:

!cmipcite get 'hdl:21.14100/90f93a05-357c-4ea2-b61f-bf2418700791' --out-path demo.txt

!cmipcite get 'hdl:21.14100/90f93a05-357c-4ea2-b61f-bf2418700791' --out-path demo.txt

In [14]:

with open("demo.txt") as fh:
    print(fh.read())

with open("demo.txt") as fh: print(fh.read())

Swart, Neil Cameron; Cole, Jason N.S.; Kharin, Viatcheslav V.; Lazare, Mike; Scinocca, John F.; Gillett, Nathan P.; Anstey, James; Arora, Vivek; Christian, James R.; Jiao, Yanjun; Lee, Warren G.; Majaess, Fouad; Saenko, Oleg A.; Seiler, Christian; Seinen, Clint; Shao, Andrew; Solheim, Larry; von Salzen, Knut; Yang, Duo; Winter, Barbara; Sigmond, Michael (2019): CCCma CanESM5 model output prepared for CMIP6 CMIP. Version 20190429. Earth System Grid Federation. https://doi.org/10.22033/ESGF/CMIP6.1303.