diff --git a/.circleci/config.yml b/.circleci/config.yml index 0b112e55a0..f3c375b480 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -77,36 +77,36 @@ jobs: pip install codacy-coverage python-codacy-coverage -r test-reports/coverage.xml - develop: - # Test development installation - working_directory: /develop + documentation: + # Test building documentation + working_directory: /doc docker: - image: continuumio/miniconda3 steps: - checkout + - restore_cache: + key: documentation-{{ .Branch }} - run: command: | - . /opt/conda/etc/profile.d/conda.sh - set -x mkdir /logs # Install - conda update -y conda > /logs/conda.txt 2>&1 - conda env update >> /logs/conda.txt 2>&1 - set +x; conda activate esmvaltool; set -x - pip install -e .[develop] > /logs/install.txt 2>&1 + pip install -r doc/requirements.txt > /logs/install.txt 2>&1 + pip install sphinx sphinx_rtd_theme >> /logs/install.txt 2>&1 # Log versions dpkg -l > /logs/versions.txt - conda env export > /logs/environment.yml pip freeze > /logs/requirements.txt - # Test installation - esmvaltool -h - python setup.py test --addopts --installation + # Test building documentation + MPLBACKEND=Agg python setup.py build_sphinx --warning-is-error + - save_cache: + key: documentation-{{ .Branch }} + paths: + - ".eggs" - store_artifacts: path: /logs - doc: - # Test building documentation - working_directory: /doc + develop: + # Test development installation + working_directory: /develop docker: - image: continuumio/miniconda3 steps: @@ -125,8 +125,9 @@ jobs: dpkg -l > /logs/versions.txt conda env export > /logs/environment.yml pip freeze > /logs/requirements.txt - # Test building documentation - python setup.py build_sphinx + # Test installation + esmvaltool -h + python setup.py test --addopts --installation - store_artifacts: path: /logs @@ -190,6 +191,7 @@ workflows: jobs: - test - install + - documentation nightly: triggers: - schedule: @@ -202,7 +204,7 @@ workflows: jobs: - test - install + - documentation - develop - - doc - conda_build - conda_install diff --git a/.codacy.yml b/.codacy.yml index 06a0ea342f..e5dad81c5b 100644 --- a/.codacy.yml +++ b/.codacy.yml @@ -19,7 +19,7 @@ engines: python_version: 3 exclude_paths: [ - 'doc/sphinx/**', + 'doc/conf.py', 'esmvaltool/cmor/tables/**', 'tests/**' ] diff --git a/.gitignore b/.gitignore index c0f1f23055..88120204ae 100644 --- a/.gitignore +++ b/.gitignore @@ -83,9 +83,8 @@ test-reports/ /python_test_out.txt # Build folder -doc/sphinx/source/diag_scripts/** -doc/sphinx/source/plot_scripts/** -doc/sphinx/build +doc/build +doc/_sidebar.rst.inc # Data files *.nc diff --git a/doc/sphinx/source/codedoc2/esmvalcore.cmor.rst b/doc/api/esmvalcore.cmor.rst similarity index 100% rename from doc/sphinx/source/codedoc2/esmvalcore.cmor.rst rename to doc/api/esmvalcore.cmor.rst diff --git a/doc/sphinx/source/codedoc2/esmvalcore.preprocessor.rst b/doc/api/esmvalcore.preprocessor.rst similarity index 100% rename from doc/sphinx/source/codedoc2/esmvalcore.preprocessor.rst rename to doc/api/esmvalcore.preprocessor.rst diff --git a/doc/api/esmvalcore.rst b/doc/api/esmvalcore.rst new file mode 100644 index 0000000000..1f042854cd --- /dev/null +++ b/doc/api/esmvalcore.rst @@ -0,0 +1,10 @@ +ESMValTool Core API Reference +============================= + +ESMValTool Core is mostly used as a commandline tool. However, it is also possibly to use (parts of) ESMValTool as a +library. This section documents the public API of ESMValTool Core. + +.. toctree:: + + esmvalcore.cmor + esmvalcore.preprocessor diff --git a/doc/sphinx/source/conf.py b/doc/conf.py similarity index 74% rename from doc/sphinx/source/conf.py rename to doc/conf.py index c6d3aea9a3..61c180644b 100644 --- a/doc/sphinx/source/conf.py +++ b/doc/conf.py @@ -13,20 +13,34 @@ # serve to show the default. import sys +import os from pathlib import Path +from datetime import datetime # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. -root = Path(__file__).absolute().parent.parent.parent +root = Path(__file__).absolute().parent.parent sys.path.insert(0, str(root)) +from esmvalcore.utils.doc.gensidebar import generate_sidebar from esmvalcore import __version__ +# -- RTD configuration ------------------------------------------------ + +# on_rtd is whether we are on readthedocs.org, this line of code grabbed from +# docs.readthedocs.org +on_rtd = os.environ.get("READTHEDOCS", None) == "True" + +# This is used for linking and such so we link to the thing we're building +rtd_version = os.environ.get("READTHEDOCS_VERSION", "latest") +if rtd_version not in ["latest"]: # TODO: add "stable" once we have it + rtd_version = "latest" + # -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' +# needs_sphinx = '1.0' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom @@ -50,17 +64,16 @@ 'show-inheritance', ] -#autodoc_mock_imports = ['cf_units', 'iris', 'matplotlib', 'numpy', 'cartopy', 'cftime', 'netCDF4', 'yaml', 'PIL', 'prov', 'scipy', 'psutil', 'shapely', 'stratify', 'ESMF'] +# autodoc_mock_imports = ['cf_units', 'iris', 'matplotlib', 'numpy', 'cartopy', +# 'cftime', 'netCDF4', 'yaml', 'PIL', 'prov', 'scipy', +# 'psutil', 'shapely', 'stratify', 'ESMF'] autodoc_mock_imports = [ 'iris', - 'cftime', - 'PIL', - 'prov', - 'scipy', 'stratify', 'ESMF', 'cartopy', 'cf_units', + 'psutil', ] # Add any paths that contain templates here, relative to this directory. @@ -70,14 +83,15 @@ source_suffix = '.rst' # The encoding of source files. -#source_encoding = 'utf-8-sig' +# source_encoding = 'utf-8-sig' # The master toctree document. master_doc = 'index' # General information about the project. project = u'ESMValTool' -copyright = u'2015, Veronika Eyring, Axel Lauer, Mattia Righi, Martin Evaldsson et al.' +copyright = (u"{0}, Veronika Eyring, Axel Lauer, Mattia Righi, " + u"Martin Evaldsson et al.").format(datetime.now().year) # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -90,13 +104,13 @@ # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -#language = None +# language = None # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: -#today = '' +# today = '' # Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' +# today_fmt = '%B %d, %Y' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. @@ -104,27 +118,27 @@ # The reST default role (used for this markup: `text`) to use for all # documents. -#default_role = None +# default_role = None # If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True +# add_function_parentheses = True # If true, the current module name will be prepended to all description # unit titles (such as .. function::). -#add_module_names = True +# add_module_names = True # If true, sectionauthor and moduleauthor directives will be shown in the # output. They are ignored by default. -#show_authors = False +# show_authors = False # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' # A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] +# modindex_common_prefix = [] # If true, keep warnings as "system message" paragraphs in the built documents. -#keep_warnings = False +# keep_warnings = False # -- Options for HTML output ---------------------------------------------- @@ -135,14 +149,14 @@ # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. -#html_theme_options = {} +# html_theme_options = {} # Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] +# html_theme_path = [] # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". -#html_title = None +# html_title = None # A shorter title for the navigation bar. Default is the same as html_title. html_short_title = "ESMValTool {0}".format(release) @@ -154,7 +168,7 @@ # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. -#html_favicon = None +# html_favicon = None # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, @@ -164,48 +178,48 @@ # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied # directly to the root of the documentation. -#html_extra_path = [] +# html_extra_path = [] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' +# html_last_updated_fmt = '%b %d, %Y' # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. -#html_use_smartypants = True +# html_use_smartypants = True # Custom sidebar templates, maps document names to template names. -#html_sidebars = {} +# html_sidebars = {} # Additional templates that should be rendered to pages, maps page names to # template names. -#html_additional_pages = {} +# html_additional_pages = {} # If false, no module index is generated. -#html_domain_indices = True +# html_domain_indices = True # If false, no index is generated. -#html_use_index = True +# html_use_index = True # If true, the index is split into individual pages for each letter. -#html_split_index = False +# html_split_index = False # If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True +# html_show_sourcelink = True # If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True +# html_show_sphinx = True # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True +# html_show_copyright = True # If true, an OpenSearch description file will be output, and all pages will # contain a tag referring to it. The value of this option must be the # base URL from which the finished HTML is served. -#html_use_opensearch = '' +# html_use_opensearch = '' # This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None +# html_file_suffix = None # Output file base name for HTML help builder. htmlhelp_basename = 'ESMValTooldoc' @@ -214,10 +228,10 @@ latex_elements = { # The paper size ('letterpaper' or 'a4paper'). - #'papersize': 'letterpaper', + # 'papersize': 'letterpaper', # The font size ('10pt', '11pt' or '12pt'). - #'pointsize': '10pt', + # 'pointsize': '10pt', # Additional stuff for the LaTeX preamble. 'preamble': @@ -241,13 +255,14 @@ \fi} \begin{titlepage} \begin{center} - \includegraphics[width=\textwidth]{../../source/figures/ESMValTool-logo.pdf}\par + \includegraphics[width=\textwidth]{figures/ESMValTool-logo.pdf}\par \vspace{2cm} {\Huge \bf \sffamily User's and Developer's Guide \par} \vspace{1cm} {\Large \sffamily \MONTH ~ \the\year \par} \vspace{12cm} - Deutsches Zentrum f\"ur Luft- und Raumfahrt (DLR), Institut f\"ur Physik der Atmosph\"are, Oberpfaffenhofen, Germany \par + Deutsches Zentrum f\"ur Luft- und Raumfahrt (DLR), + Institut f\"ur Physik der Atmosph\"are, Oberpfaffenhofen, Germany \par \vspace{0.5cm} http://www.esmvaltool.org/ \par \end{center} @@ -265,65 +280,69 @@ latex_documents = [ ('index', 'ESMValTool_Users_Guide.tex', u'ESMValTool User\'s and Developer\'s Guide', - u'ESMValTool Development Team', - 'manual'), + u'ESMValTool Development Team', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of # the title page. -#latex_logo = None +# latex_logo = None # For "manual" documents, if this is true, then toplevel headings are parts, # not chapters. -#latex_use_parts = True +# latex_use_parts = True latex_toplevel_sectioning = "part" # If true, show page references after internal links. -#latex_show_pagerefs = False +# latex_show_pagerefs = False # If true, show URL addresses after external links. -#latex_show_urls = False +# latex_show_urls = False # Documents to append as an appendix to all manuals. -#latex_appendices = [] +# latex_appendices = [] # If false, no module index is generated. -#latex_domain_indices = True +# latex_domain_indices = True # -- Options for manual page output --------------------------------------- # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). -#man_pages = [ +# man_pages = [ # ('index', 'esmvaltool', u'ESMValTool Documentation', -# [u'Veronika Eyring, Axel Lauer, Mattia Righi, Martin Evaldsson et al.'], 1) -#] +# [ +# (u'Veronika Eyring, Axel Lauer, Mattia Righi,' +# u' Martin Evaldsson et al.') +# ], 1) +# ] # If true, show URL addresses after external links. -#man_show_urls = False +# man_show_urls = False # -- Options for Texinfo output ------------------------------------------- # Grouping the document tree into Texinfo files. List of tuples # (source start file, target name, title, author, # dir menu entry, description, category) -#texinfo_documents = [ -## ('index', 'ESMValTool', u'ESMValTool Documentation', -# u'Veronika Eyring, Axel Lauer, Mattia Righi, Martin Evaldsson et al.', 'ESMValTool', 'One line #description of project.', +# texinfo_documents = [ +# ('index', 'ESMValTool', u'ESMValTool Documentation', +# u'Veronika Eyring, Axel Lauer, Mattia Righi, Martin Evaldsson et al.', +# 'ESMValTool', +# 'One line #description of project.', # 'Miscellaneous'), -#] +# ] # Documents to append as an appendix to all manuals. -#texinfo_appendices = [] +# texinfo_appendices = [] # If false, no module index is generated. -#texinfo_domain_indices = True +# texinfo_domain_indices = True # How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' +# texinfo_show_urls = 'footnote' # If true, do not generate a @detailmenu in the "Top" node's menu. -#texinfo_no_detailmenu = False +# texinfo_no_detailmenu = False # -- Options for Epub output ---------------------------------------------- @@ -334,65 +353,65 @@ epub_copyright = u'ESMValTool Development Team' # The basename for the epub file. It defaults to the project name. -#epub_basename = u'ESMValTool' +# epub_basename = u'ESMValTool' -# The HTML theme for the epub output. Since the default themes are not optimized -# for small screen space, using the same theme for HTML and epub output is -# usually not wise. This defaults to 'epub', a theme designed to save visual -# space. -#epub_theme = 'epub' +# The HTML theme for the epub output. Since the default themes are not +# optimized for small screen space, using the same theme for HTML and epub +# output is usually not wise. This defaults to 'epub', a theme designed to +# save visual space. +# epub_theme = 'epub' # The language of the text. It defaults to the language option # or en if the language is not set. -#epub_language = '' +# epub_language = '' # The scheme of the identifier. Typical schemes are ISBN or URL. -#epub_scheme = '' +# epub_scheme = '' # The unique identifier of the text. This can be a ISBN number # or the project homepage. -#epub_identifier = '' +# epub_identifier = '' # A unique identification for the text. -#epub_uid = '' +# epub_uid = '' # A tuple containing the cover image and cover page html template filenames. -#epub_cover = () +# epub_cover = () # A sequence of (type, uri, title) tuples for the guide element of content.opf. -#epub_guide = () +# epub_guide = () # HTML files that should be inserted before the pages created by sphinx. # The format is a list of tuples containing the path and title. -#epub_pre_files = [] +# epub_pre_files = [] # HTML files shat should be inserted after the pages created by sphinx. # The format is a list of tuples containing the path and title. -#epub_post_files = [] +# epub_post_files = [] # A list of files that should not be packed into the epub file. epub_exclude_files = ['search.html'] # The depth of the table of contents in toc.ncx. -#epub_tocdepth = 3 +# epub_tocdepth = 3 # Allow duplicate toc entries. -#epub_tocdup = True +# epub_tocdup = True # Choose between 'default' and 'includehidden'. -#epub_tocscope = 'default' +# epub_tocscope = 'default' # Fix unsupported image types using the PIL. -#epub_fix_images = False +# epub_fix_images = False # Scale large images. -#epub_max_image_width = 0 +# epub_max_image_width = 0 # How to display URL addresses: 'footnote', 'no', or 'inline'. -#epub_show_urls = 'inline' +# epub_show_urls = 'inline' # If false, no index is generated. -#epub_use_index = True +# epub_use_index = True numfig = True @@ -402,4 +421,13 @@ 'iris': ('https://scitools.org.uk/iris/docs/latest/', None), 'numpy': ('https://docs.scipy.org/doc/numpy/', None), 'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None), + 'esmvaltool': + ('https://esmvaltool.readthedocs.io/en/%s/' % rtd_version, None), + 'esmvalcore': + ('https://esmvaltool.readthedocs.io/projects/esmvalcore/en/%s/' % + rtd_version, None), } + +# -- Custom Document processing ---------------------------------------------- + +generate_sidebar(globals(), "esmvalcore") diff --git a/doc/sphinx/source/esmvalcore/config.inc b/doc/esmvalcore/config.rst similarity index 100% rename from doc/sphinx/source/esmvalcore/config.inc rename to doc/esmvalcore/config.rst diff --git a/doc/sphinx/source/esmvalcore/datafinder.inc b/doc/esmvalcore/datafinder.rst similarity index 85% rename from doc/sphinx/source/esmvalcore/datafinder.inc rename to doc/esmvalcore/datafinder.rst index 333a828cd0..6759018c27 100644 --- a/doc/sphinx/source/esmvalcore/datafinder.inc +++ b/doc/esmvalcore/datafinder.rst @@ -1,7 +1,7 @@ -:: _inputdata: +.. _datafinder: *********** Data finder *********** -Documentation of the _data_finder.py module (incl. _download.py?) \ No newline at end of file +Documentation of the _data_finder.py module (incl. _download.py?) diff --git a/doc/esmvalcore/index.rst b/doc/esmvalcore/index.rst new file mode 100644 index 0000000000..e0e8750364 --- /dev/null +++ b/doc/esmvalcore/index.rst @@ -0,0 +1,12 @@ +############### +ESMValTool Core +############### + + +.. toctree:: + :maxdepth: 1 + + Configuration files + Finding data + Recipe + Preprocessor diff --git a/doc/esmvalcore/preprocessor.rst b/doc/esmvalcore/preprocessor.rst new file mode 100644 index 0000000000..4c4bfbae1d --- /dev/null +++ b/doc/esmvalcore/preprocessor.rst @@ -0,0 +1,491 @@ +.. _preprocessor: + +************ +Preprocessor +************ +The ESMValTool preprocessor can be used to perform a broad range of operations +on the input data before diagnostics or metrics are applied. The +preprocessor performs these operations in a centralized, documented and +efficient way, thus reducing the data processing load on the diagnostics side. + +Each of the preprocessor operations is written in a dedicated python module and +all of them receive and return an Iris cube, working sequentially on the data +with no interactions between them. The order +in which the preprocessor operations is applied is set by default in order to +minimize the loss of information due to, for example, temporal and spatial +subsetting or multi-model averaging. Nevertheless, the user is free to change +such order to address specific scientific requirements, but keeping in mind +that some operations must be necessarily performed in a specific order. This is +the case, for instance, for multi-model statistics, which required the model to +be on a common grid and therefore has to be called after the regridding module. + +In this section, each of the preprocessor modules is described in detail +following the default order in which they are applied: + +* `Variable derivation`_. +* `CMOR check and dataset-specific fixes`_. +* `Vertical interpolation`_. +* `Land/Sea/Ice masking`_. +* `Horizontal regridding`_. +* `Masking of missing values`_. +* `Multi-model statistics`_. +* `Time operations`_. +* `Area operations`_. +* `Volume operations`_. +* `Unit conversion`_. + + +Variable derivation +=================== + +The variable derivation module allows to derive variables which are not in the +CMIP standard data request using standard variables as input. The typical use +case of this operation is the evaluation of a variable which is only available +in an observational dataset but not in the models. In this case a derivation +function is provided by the ESMValTool in order to calculate the variable and +perform the comparison. For example, several observational datasets deliver +total column ozone as observed variable (`toz`), but CMIP models only provide +the ozone 3D field. In this case, a derivation function is provided to +vertically integrate the ozone and obtain total column ozone for direct +comparison with the observations. + +To contribute a new derived variable, it is also necessary to define a name for +it and to provide the corresponding CMOR table. This is to guarantee the proper +metadata definition is attached to the derived data. Such custom CMOR tables +are collected as part of the `ESMValTool core package +`_. By default, the variable +derivation will be applied only if not already available in the input data, but +the derivation can be forced by setting the appropriate flag. + +.. code-block:: yaml + + variables: + toz: + derive: true + force_derivation: false + +The required arguments for this module are two boolean switches: +* derive: activate variable derivation +* force_derivation: force variable derivation even if the variable is +directly available in the input data. + +See also :func:`esmvalcore.preprocessor.derive`. + + +CMOR check and dataset-specific fixes +====================================== +.. warning:: + Documentation of _reformat.py, check.py and fix.py to be added + + +Vertical interpolation +====================== +.. warning:: + Documentation of _regrid.py (part 1) to be added + + +Land/Sea/Ice masking +==================== + +Certain metrics and diagnostics need to be computed and performed on specific +domains on the globe. The ESMValTool preprocessor supports filtering +the input data on continents, oceans/seas and ice. This is achived by masking +the model data and keeping only the values associated with grid points that +correspond to, e.g., land, ocean or ice surfaces, as specified by the +user. Where possible, the masking is realized using the standard mask files +provided together with the model data as part of the CMIP data request (the +so-called fx variable). In the absence of these files, the Natural Earth masks +are used: although these are not model-specific, they represent a good +approximation since they have a much higher resolution than most of the models +and they are regularly updated with changing geographical features. + +In ESMValTool, land-sea-ice masking can be done in two places: in the +preprocessor, to apply a mask on the data before any subsequent preprocessing +step and before running the diagnostic, or in the diagnostic scripts +themselves. We present both these implementations below. + +To mask out a certain domain (e.g., sea) in the preprocessor, +`mask_landsea` can be used: + +.. code-block:: yaml + + preprocessors: + preproc_mask: + mask_landsea: + mask_out: sea + +and requires only one argument: +* mask_out: either land or sea. + +The preprocessor automatically retrieves the corresponding mask (`fx: stfof` in +this case) and applies it so that sea-covered grid cells are set to +missing. Conversely, it retrieves the `fx: sftlf` mask when land need to be +masked out, respectively. If the corresponding fx file is not found (which is +the case for some models and almost all observational datasets), the +preprocessor attempts to mask the data using Natural Earth mask files (that are +vectorized rasters). As mentioned above, the spatial resolution of the the +Natural Earth masks are much higher than any typical global model (10m for +land and 50m for ocean masks). + +Note that for masking out ice sheets, the preprocessor uses a different +function, to ensure that both land and sea or ice can be masked out without +losing generality. To mask ice out, `mask_landseaice` can be used: + +.. code-block:: yaml + + preprocessors: + preproc_mask: + mask_landseaice: + mask_out: ice + +and requires only one argument: +* mask_out: either landsea or ice. + +As in the case of `mask_landsea`, the preprocessor automatically retrieves the +`fx: sftgif` mask. + +Another option is to just read the fx masks as any other CMOR variable and use +it within a diagnostic script. This can be done in the variable dictionary by +specifiying the desired fx variables (masks): + +.. warning:: + Code snippet, text and link to function to be added (after #1037 and #1075 + are closed). + + +Horizontal regridding +===================== +.. warning:: + Documentation of _regrid.py (part 2) to be added + + +Masking of missing values +========================= +.. warning:: + Documentation of _mask.py (part 2) to be added + + +Multi-model statistics +====================== + +.. warning:: + Documentation of _multimodel.py to be added. + +Information on maximum memory required: In the most general case, we can set +upper limits on the maximum memory the analysis will require: + +Ms = (R + N) x F_eff - F_eff - when no multimodel analysis is performed; +Mm = (2R + N) x F_eff - 2F_eff - when multimodel analysis is performed; + +where + +Ms: maximum memory for non-multimodel module +Mm: maximum memory for multimodel module +R: computational efficiency of module (typically 2-3) +N: number of datasets +F_eff: average size of data per dataset where F_eff = e x f x F +where e is the factor that describes how lazy the data is (e = 1 for fully +realized data) and f describes how much the data was shrunk by the immediately +previous module e.g. time extraction, area selection or level extraction; note +that for fix_data f relates only to the time extraction, if data is exact in +time (no time selection) f = 1 for fix_data. + +So for cases when we deal with a lot of datasets (R + N = N), data is fully +realized, assuming an average size of 1.5GB for 10 years of 3D netCDF data, N +datasets will require: + +Ms = 1.5 x (N - 1) GB +Mm = 1.5 x (N - 2) GB + + +Time operations +=============== + +The time operations module contains a broad set of functions to subset data and apply +statistical operators along the temporal coordinate of the input data: + +| `1. extract_time`_: extract a specified time range from a cube. +| `2. extract_season`_: extract only the times that occur within a specific + season. +| `3. extract_month`_: extract only the times that occur within a specific + month. +| `4. time_average`_: take the weighted average over the entire time dimension. +| `5. seasonal_mean`_: produce a mean for each season (DJF, MAM, JJA, SON) +| `6. annual_mean`_: produce an annual or decadal mean. +| `7. regrid_time`_: align the time axis of each dataset to have common time + points and calendars. + +1. extract_time +--------------- + +This function subsets a dataset between two points in times. It removes all +times in the dataset before the first time and after the last time point. +The required arguments are relatively self explanatory: + +* start_year +* start_month +* start_day +* end_year +* end_month +* end_day + +These start and end points are set using the datasets native calendar. All six +arguments should be given as integers, named month strings (e.g., March) will +not be accepted. Note that start_year and end_year can be omitted, as they are +filled in automatically from the dataset definition if not specified +here (end_year will be the value in the dataset definition + 1). + +See also :func:`esmvalcore.preprocessor.extract_time`. + +2. extract_season +----------------- + +Extract only the times that occur within a specific season. + +This function only has one argument: + +* season: DJF, MAM, JJA, or SON + +Note that this function does not change the time resolution. If your original +data is in monthly time resolution, then this function will return three +monthly datapoints per year. + +To calculate a seasonal average, this function needs to be combined with the +seasonal_mean function, below. + +See also :func:`esmvalcore.preprocessor.extract_season`. + +3. extract_month +---------------- + +The function extracts the times that occur within a specific month. +This function only has one argument: + +* month: [1-12] + +Note that named month strings will not be accepted. + +See also :func:`esmvalcore.preprocessor.extract_month`. + +4. time_average +--------------- + +This function takes the weighted average over the time dimension. This +function requires no arguments and removes the time dimension of the cube. + +See also :func:`esmvalcore.preprocessor.time_average`. + +5. seasonal_mean +---------------- + +This function produces a seasonal mean for each season (DJF, MAM, JJA, SON). +Note that this function will not check for missing time points. For instance, +if the DJF field is selected, but the input datasets starts on January 1st, +the first DJF field will only contain data from January and February. + +We recommend using the extract_time to start the dataset from the following +December and remove such biased initial datapoints. + +See also :func:`esmvalcore.preprocessor.seasonal_mean`. + +6. annual_mean +-------------- + +This function produces an annual or a decadal mean. It takes a single boolean +switch as argument: +* decadal: set this to true to calculate decadal averages instead of annual +averages. + +See also :func:`esmvalcore.preprocessor.annual_mean`. + +7. regrid_time +-------------- + +This function aligns the time points of each component dataset to allow the +subtraction of two Iris cubes from different datasets. The operation makes the +datasets time points common and sets common calendars; it also resets the time +bounds and auxiliary coordinates to reflect the artifically shifted time +points. The current implementation works only for monthly and daily data. + +See also :func:`esmvalcore.preprocessor.regrid_time`. + + +Area operations +=============== + +.. warning:: + Need to be adapted after renaming action in #1123 + +The area manipulation module contains the following preprocessor functions: + +| `1. extract_region`_: extract a region from a cube based on lat/lon corners. +| `2. zonal_means`_: calculate the zonal or meridional means. +| `3. area_statistics`_: calculate the average value over a region. +| `4. extract_named_regions`_: extract a region from a cube given its name. + +1. extract_region +----------------- + +This function masks data outside a rectagular region requested. The boundairies +of the region are provided as latitude and longitude coordinates in the +arguments: + +* start_longitude +* end_longitude +* start_latitude +* end_latitude + +Note that this function can only be used to extract a rectangular region. + +See also :func:`esmvalcore.preprocessor.extract_region`. + +2. zonal_means +-------------- + +The function calculates the zonal or meridional means. While this function is +named `zonal_mean`, it can be used to apply several different operations in +an zonal or meridional direction. +This function takes two arguments: + +* coordinate: Which direction to apply the operation: latitude or longitude. +* mean_type: Which operation to apply: mean, std_dev, variance, median, min or +* max. + +See also :func:`esmvalcore.preprocessor.zonal_means`. + +3. area_statistics +------------------ + +This function calculates the average value over a region - weighted by the +cell areas of the region. + +This function takes one argument: +* operator: the name of the operation to apply. + +This function can be used to apply several different operations in the +horizonal plane: mean, standard deviation, median variance, minimum and +maximum. + +Note that this function is applied over the entire dataset. If only a specific +region, depth layer or time period is required, then those regions need to be +removed using other preprocessor operations in advance. + +See also :func:`esmvalcore.preprocessor.area_statistics`. + +4. extract_named_regions +------------------------ + +This function extract a specific named region from the data. +This function takes onw argument: + +* regions: either a string or a list of strings of named regions. + +Note that the dataset must have a `region` cooordinate which includes a list of +strings as values. This function then matches the named regions against the +requested string. + +See also :func:`esmvalcore.preprocessor.extract_named_regions`. + + +Volume operations +================= + +The volume operations module contains the following preprocessor functions: + +| `1. extract_volume`_: extract a specific depth range from a cube. +| `2. volume_statistics`_: calculate the volume-weighted average. +| `3. depth_integration`_: integrate over the depth dimension. +| `4. extract_transect`_: extract data along a line of constant latitude or + longitude. +| `5. extract_trajectory`_: extract data along a specified trajectory. + +1. extract_volume +----------------- + +This function extracts a specific range in the z-direction from a cube. +This function takes two arguments: + +* z_min: minimum in the z direction +* z_max: maximum in the z direction + +Note that this requires the requested z-coordinate range to be the same sign as +the Iris cube, i.e. if the cube has z-coordinate as negative, then z_min and +z_max need to be negative numbers. + +See also :func:`esmvalcore.preprocessor.extract_volume`. + +2. volume_statistics +-------------------- + +This function calculates the volume-weighted average across three dimensions, +but maintains the time dimension. + +This function takes one argument: +* operator: operation to apply over the volume (at the moment only mean is implemented) + +No depth coordinate is required as this is determined by Iris. This +function works best when the fx files provide the cell volume. + +See also :func:`esmvalcore.preprocessor.volume_statistics`. + + +3. depth_integration +-------------------- + +This function integrates over the depth dimension. It performs a weighted sum +along the z-coordinate, and removes the z direction of the output cube. It takes no arguments. + +See also :func:`esmvalcore.preprocessor.depth_integration`. + +4. extract_transect +------------------- + +This function extracts data along a line of constant latitude or longitude. +This function takes two arguments, although only one is strictly required: +* latitude +* longitude + +One of these arguments needs to be set to a float, and the other can then be +either ignored or set to a minimum or maximum value. For example, if latitude +is set to 0 and longitude is left blank, the function would produce a cube +along the equator. If latitude is set to to 0 and longitude to `[40., 100.]` it +will produce a transect of the equator in the Indian Ocean. + +See also :func:`esmvalcore.preprocessor.extract_transect`. + +5. extract_trajectory +--------------------- + +This function extracts data along a specified trajectory. It requires three +arguments: +* latitude_points: list of latitude coordinates +* longitude_points: list of longiute coordinates +* number_points: if two points are provided, the `number_points` argument is +used to set the number of places to extract between the two end points. + +If more than two points are provided, then extract_trajectory will produce a +cube which has extrapolated the data of the cube to those points, and +`number_points` is not needed. Note that this function uses the expensive +interpolate method, but it may be necessary for irregular grids. + +See also :func:`esmvalcore.preprocessor.extract_trajectory`. + + +Unit conversion +=============== +Converting units is also supported. This is particularly useful in +cases where different datasets might have different units, for example +when comparing CMIP5 and CMIP6 variables where the units have changed +or in case of observational datasets that are delivered in different +units. + +In these cases, having a unit conversion at the end of the processing +will guarantee homogeneous input for the diagnostics. + +.. note:: + Conversion is only supported between compatible units! In other + words, converting temperature units from `degC` to `Kelvin` works + fine, changing precipitation units from a rate based unit to an + amount based unit is not supported at the moment. + +See also :func:`esmvalcore.preprocessor.convert_units`. diff --git a/doc/esmvalcore/recipe.rst b/doc/esmvalcore/recipe.rst new file mode 100644 index 0000000000..77ee1cdacf --- /dev/null +++ b/doc/esmvalcore/recipe.rst @@ -0,0 +1,185 @@ +.. _recipe: + +***************** +ESMValTool recipe +***************** + +Recipes are the instructions telling ESMValTool about the user who wrote the +recipe, the datasets which need to be run, the preprocessors that need to be +applied, and the diagnostics which need to be run over the preprocessed data. +This information is provided to ESMValTool in the recipe sections: +`Documentation`_, `Datasets`_, `Preprocessors`_ and `Diagnostics`_, +respectively. + + +Documentation +============= + +The documentation section includes: + +- The recipe's author's user name +- A description of the recipe +- The user name of the maintainer +- A list of scientific references +- the project or projects associated with the recipe. + +For example, please see the documentation section from the recipe: +recipe_ocean_amoc.yml. + +.. code-block:: yaml + + documentation: + description: | + Recipe to produce time series figures of the derived variable, the + Atlantic meriodinal overturning circulation (AMOC). + This recipe also produces transect figures of the stream functions for + the years 2001-2004. + + authors: + - demo_le + + maintainer: + - demo_le + + references: + - demora2018gmd + + projects: + - ukesm + +Note that the authors, projects, and references will need to be included in the +``config-references.yml`` file. The author name uses the format: +`surname_name`. For instance, Mickey Mouse would be: `mouse_mickey`. +Also note that this username is unlikely to be the same as the github +user name. + + + +Datasets +======== + +The datasets section includes: + +- dataset name +- Project (CMIP5 or 6, observations...) +- experiment (historical/ RCP8.5 etc...) +- Ensemble member +- The time range +- The model grid, gn or gr, (CMIP6 only). + +For example, a datasets section could be: + +.. code-block:: yaml + + datasets: + - {dataset: CanESM2, project: CMIP5, exp: historical, ensemble: r1i1p1, start_year: 2001, end_year: 2004} + - {dataset: UKESM1-0-LL, project: CMIP6, exp: historical, ensemble: r1i1p1f2, start_year: 2001, end_year: 2004, grid: gn} + + +Note that this section is not required, as datasets can also be provided in the +`Diagnostics`_ section. + + +Preprocessors +============= + +The preprocessor section of the recipe includes one or more preprocesors, each +of which may call one or several preprocessor functions. + +Each preprocessor section includes: + +- A preprocessor name. +- A list of preprocesor functions to apply +- Any Arguments given to the preprocessor functions. +- The order that the preprocesor functions are applied can also be specified using the ``custom_order`` preprocesor function. + +The following preprocessor is an example of a preprocessor that contains +multiple preprocessor functions: + +.. code-block:: yaml + + preprocessors: + prep_map: + regrid: + target_grid: 1x1 + scheme: linear + time_average: + multi_model_statistics: + span: overlap + statistics: [mean ] + +If only the default preprocessor is needed, then this section can be omitted. + + +Diagnostics +=========== + +The diagnostics section includes one or more diagnostics. Each diagnostics will +have: + +- A list of which variables to load +- A description of the variables (optional) +- Which preprocessor to apply to each variable +- The script to run +- The diagnostics can also include an optional ``additional_datasets`` section. + +The ``additional_datasets`` can add datasets beyond those listed in the the +`Datasets`_ section. This is useful if specific datasets need to be linked with +a specific diagnostics. The addition datasets can be used to add variable +specific datasets. This is also a good way to add observational datasets can be +added to the diagnostic. + +The following example, taken from recipe_ocean_example.yml, shows a diagnostic +named `diag_map`, which loads the temperature at the ocean surface between +the years 2001 and 2003 and then passes it to the prep_map preprocessor. +The result of this process is then passed to the ocean diagnostic map scipt, +``ocean/diagnostic_maps.py``. + +.. code-block:: yaml + + diagnostics: + + diag_map: + description: Global Ocean Surface regridded temperature map + variables: + tos: # Temperature at the ocean surface + preprocessor: prep_map + start_year: 2001 + end_year: 2003 + scripts: + Global_Ocean_Surface_regrid_map: + script: ocean/diagnostic_maps.py + +To define a variable/dataset combination, the keys in the diagnostic section +are combined with the keys from datasets section. If two versions of the same +key are provided, then the key in the datasets section will take precedence +over the keys in variables section. For many recipes it makes more sense to +define the ``start_year`` and ``end_year`` items in the variable section, because the +diagnostic script assumes that all the data has the same time range. + +Note that the path to the script provided in the `script` option should be +either: + +1. the absolute path to the script. +2. the path relative to the ``esmvaltool/diag_scripts`` directory. + + +As mentioned above, the datasets are provided in the `Diagnostics`_ section +in this section. However, they could also be included in the `Datasets`_ +section. + + +Brief introduction to YAML +========================== + +While .yaml is a relatively common format, maybe users may not have +encountered this language before. The key information about this format is: + +- Yaml is a human friendly markup language. +- Yaml is commonly used for configuration files. +- the syntax is relatively straightforward +- Indentation matters a lot (like python)! +- yaml is case sensitive +- A yml tutorial is available here: https://learnxinyminutes.com/docs/yaml/ +- A yml quick reference card is available here: https://yaml.org/refcard.html +- ESMValTool uses the yamllint linter tool: http://www.yamllint.com diff --git a/doc/sphinx/source/figures/ESMValTool-logo.png b/doc/figures/ESMValTool-logo.png similarity index 100% rename from doc/sphinx/source/figures/ESMValTool-logo.png rename to doc/figures/ESMValTool-logo.png diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 0000000000..3026d4b564 --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,11 @@ +Welcome to ESMValTool's documentation! +====================================== + +.. include:: _sidebar.rst.inc + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`search` + diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 0000000000..92fcae28b0 --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,10 @@ +dask[array] +netCDF4 +numba +numpy +pillow +prov[dot] +pyyaml +scipy +shapely +yamale diff --git a/doc/sphinx/source/codedoc2/esmvaltool.diag_scripts.ocean.rst b/doc/sphinx/source/codedoc2/esmvaltool.diag_scripts.ocean.rst deleted file mode 100644 index 2c7d562239..0000000000 --- a/doc/sphinx/source/codedoc2/esmvaltool.diag_scripts.ocean.rst +++ /dev/null @@ -1,21 +0,0 @@ -Ocean diagnostics toolkit -============================= - -Welcome to the API documentation for the ocean diagnostics tool kit. -This toolkit is built to assist in the evaluation of models of the ocean. - -This toolkit is part of ESMValTool v2. - -Author: Lee de Mora (PML) - ledm@pml.ac.uk - -.. toctree:: - -.. automodule:: esmvaltool.diag_scripts.ocean.diagnostic_maps -.. automodule:: esmvaltool.diag_scripts.ocean.diagnostic_maps_quad -.. automodule:: esmvaltool.diag_scripts.ocean.diagnostic_model_vs_obs -.. automodule:: esmvaltool.diag_scripts.ocean.diagnostic_profiles -.. automodule:: esmvaltool.diag_scripts.ocean.diagnostic_timeseries -.. automodule:: esmvaltool.diag_scripts.ocean.diagnostic_transects -.. automodule:: esmvaltool.diag_scripts.ocean.diagnostic_seaice -.. automodule:: esmvaltool.diag_scripts.ocean.diagnostic_tools diff --git a/doc/sphinx/source/codedoc2/esmvaltool.diag_scripts.rst b/doc/sphinx/source/codedoc2/esmvaltool.diag_scripts.rst deleted file mode 100644 index 70c1c0526a..0000000000 --- a/doc/sphinx/source/codedoc2/esmvaltool.diag_scripts.rst +++ /dev/null @@ -1,8 +0,0 @@ -Diagnostic scripts -================== - -Various diagnostic packages exist as part of ESMValTool. - -.. automodule:: esmvaltool.diag_scripts - -.. automodule:: esmvaltool.diag_scripts.ocean diff --git a/doc/sphinx/source/codedoc2/esmvaltool.diag_scripts.shared.rst b/doc/sphinx/source/codedoc2/esmvaltool.diag_scripts.shared.rst deleted file mode 100644 index 4069e0f6bd..0000000000 --- a/doc/sphinx/source/codedoc2/esmvaltool.diag_scripts.shared.rst +++ /dev/null @@ -1,9 +0,0 @@ -Shared diagnostic script code -============================= - -.. automodule:: esmvaltool.diag_scripts.shared - -Plotting --------- - -.. automodule:: esmvaltool.diag_scripts.shared.plot diff --git a/doc/sphinx/source/codedoc2/esmvaltool.rst b/doc/sphinx/source/codedoc2/esmvaltool.rst deleted file mode 100644 index feb68adf18..0000000000 --- a/doc/sphinx/source/codedoc2/esmvaltool.rst +++ /dev/null @@ -1,13 +0,0 @@ -ESMValTool Code API Documentation -================================= - -ESMValTool is mostly used as a commandline tool. However, it is also possibly to use (parts of) EsmValTool as a -library. This section documents the public API of ESMValTool. - -.. toctree:: - - esmvalcore.preprocessor - esmvalcore.cmor - esmvaltool.diag_scripts.shared - esmvaltool.diag_scripts - esmvaltool.diag_scripts.ocean diff --git a/doc/sphinx/source/esmvalcore/index.rst b/doc/sphinx/source/esmvalcore/index.rst deleted file mode 100644 index f7c63389d0..0000000000 --- a/doc/sphinx/source/esmvalcore/index.rst +++ /dev/null @@ -1,8 +0,0 @@ -############### -ESMValTool Core -############### - -.. include:: config.inc -.. include:: datafinder.inc -.. include:: recipe.inc -.. include:: preprocessor.inc diff --git a/doc/sphinx/source/esmvalcore/preprocessor.inc b/doc/sphinx/source/esmvalcore/preprocessor.inc deleted file mode 100644 index 40323cb53b..0000000000 --- a/doc/sphinx/source/esmvalcore/preprocessor.inc +++ /dev/null @@ -1,466 +0,0 @@ -:: _preprocessor: - -************ -Preprocessor -************ -The ESMValTool preprocessor can be used to perform all types of climate data pre-processing needed before indices or diagnostics can be calculated. It is a base component for many other diagnostics and metrics shown on this portal. It can be applied to tailor the climate model data to the need of the user for its own calculations. - -Features of the ESMValTool Climate data pre-processor are: - -* Regridding -* Geographical area selection -* Aggregation of data -* Provenance tracking of the calculations -* Model statistics -* Multi-model mean -* and many more - -Variable derivation -=================== -Documentation of _derive.py - - -Time manipulation -================= -The _time.py module contains the following preprocessor functions: - -* extract_time: Extract a time range from a cube. -* extract_season: Extract only the times that occur within a specific season. -* extract_month: Extract only the times that occur within a specific month. -* time_average: Take the weighted average over the time dimension. -* seasonal_mean: Produces a mean for each season (DJF, MAM, JJA, SON) -* annual_mean: Produces an annual or decadal mean. -* regrid_time: Aligns the time axis of each dataset to have common time points and calendars. - -1. extract_time ---------------- - -This function subsets a dataset between two points in times. It removes all -times in the dataset before the first time and after the last time point. -The required arguments are relatively self explanatory: - -* start_year -* start_month -* start_day -* end_year -* end_month -* end_day - -These start and end points are set using the datasets native calendar. -All six arguments should be given as integers - the named month string -will not be accepted. - -See also :func:`esmvalcore.preprocessor.extract_time`. - - -2. extract_season ------------------ - -Extract only the times that occur within a specific season. - -This function only has one argument: `season`. This is the named season to -extract. ie: DJF, MAM, JJA, SON. - -Note that this function does not change the time resolution. If your original -data is in monthly time resolution, then this function will return three -monthly datapoints per year. - -If you want the seasonal average, then this function needs to be combined with -the seasonal_mean function, below. - -See also :func:`esmvalcore.preprocessor.extract_season`. - - -3. extract_month ----------------- - -The function extracts the times that occur within a specific month. -This function only has one argument: `month`. This value should be an integer -between 1 and 12 as the named month string will not be accepted. - -See also :func:`esmvalcore.preprocessor.extract_month`. - - -4. time_average ---------------- - -This functions takes the weighted average over the time dimension. This -function requires no arguments and removes the time dimension of the cube. - -See also :func:`esmvalcore.preprocessor.time_average`. - - -5. seasonal_mean ----------------- - -This function produces a seasonal mean for each season (DJF, MAM, JJA, SON). -Note that this function will not check for missing time points. For instance, -if you are looking at the DJF field, but your datasets starts on January 1st, -the first DJF field will only contain data from January and February. - -We recommend using the extract_time to start the dataset from the following -December and remove such biased initial datapoints. - -See also :func:`esmvalcore.preprocessor.seasonal_mean`. - - -6. annual_mean --------------- - -This function produces an annual or a decadal mean. The only argument is the -decadal boolean switch. When this switch is set to true, this function -will output the decadal averages. - -See also :func:`esmvalcore.preprocessor.annual_mean`. - - -7. regrid_time --------------- - -This function aligns the time points of each component dataset so that the dataset -iris cubes can be subtracted. The operation makes the datasets time points common and -sets common calendars; it also resets the time bounds and auxiliary coordinates to -reflect the artifically shifted time points. Current implementation for monthly -and daily data; the frequency is set automatically from the variable CMOR table -unless a custom frequency is set manually by the user in recipe. - - -Area manipulation -================= -The _area.py module contains the following preprocessor functions: - -* extract_region: Extract a region from a cube based on lat/lon corners. -* zonal_means: Calculates the zonal or meridional means. -* area_statistics: Calculates the average value over a region. -* extract_named_regions: Extract a specific region from in the region cooordinate. - - -1. extract_region ------------------ - -This function masks data outside a rectagular region requested. The boundairies -of the region are provided as latitude and longitude coordinates in the -arguments: - -* start_longitude -* end_longitude -* start_latitude -* end_latitude - -Note that this function can only be used to extract a rectangular region. - -See also :func:`esmvalcore.preprocessor.extract_region`. - - -2. zonal_means --------------- - -The function calculates the zonal or meridional means. While this function is -named `zonal_mean`, it can be used to apply several different operations in -an zonal or meridional direction. -This function takes two arguments: - -* coordinate: Which direction to apply the operation: latitude or longitude -* mean_type: Which operation to apply: mean, std_dev, variance, median, min or max - -See also :func:`esmvalcore.preprocessor.zonal_means`. - - -3. area_statistics ------------------ - -This function calculates the average value over a region - weighted by the -cell areas of the region. - -This function takes the argument, -operator: the name of the operation to apply. - -This function can be used to apply several -different operations in the horizonal plane: mean, standard deviation, median -variance, minimum and maximum. - -Note that this function is applied over the entire dataset. If only a specific -region, depth layer or time period is required, then those regions need to be -removed using other preprocessor operations in advance. - -See also :func:`esmvalcore.preprocessor.area_statistics`. - - -4. extract_named_regions ------------------------- - -This function extract a specific named region from the data. This function -takes the following argument: `regions` which is either a string or a list -of strings of named regions. Note that the dataset must have a `region` -cooordinate which includes a list of strings as values. This function then -matches the named regions against the requested string. - -See also :func:`esmvalcore.preprocessor.extract_named_regions`. - - -Volume manipulation -=================== -The _volume.py module contains the following preprocessor functions: - -* extract_volume: Extract a specific depth range from a cube. -* volume_statistics: Calculate the volume-weighted average. -* depth_integration: Integrate over the depth dimension. -* extract_transect: Extract data along a line of constant latitude or longitude. -* extract_trajectory: Extract data along a specified trajectory. - - -1. extract_volume ------------------ - -Extract a specific range in the z-direction from a cube. This function -takes two arguments, a minimum and a maximum (`z_min` and `z_max`, -respectively) in the z direction. - -Note that this requires the requested z-coordinate range to be the -same sign as the iris cube. ie, if the cube has z-coordinate as -negative, then z_min and z_max need to be negative numbers. - -See also :func:`esmvalcore.preprocessor.extract_volume`. - - -2. volume_statistics ------------------ - -This function calculates the volume-weighted average across three dimensions, -but maintains the time dimension. The following arguments are required: - -This function takes the argument: operator, which defines the -operation to apply over the volume. - -No depth coordinate is required as this is determined by iris. This -function works best when the fx_files provide the cell volume. - -See also :func:`esmvalcore.preprocessor.volume_statistics`. - - -3. depth_integration --------------------- - -This function integrate over the depth dimension. This function does a -weighted sum along the z-coordinate, and removes the z direction of the output -cube. This preprocessor takes no arguments. - -See also :func:`esmvalcore.preprocessor.depth_integration`. - - -4. extract_transect -------------------- - -This function extract data along a line of constant latitude or longitude. -This function takes two arguments, although only one is strictly required. -The two arguments are `latitude` and `longitude`. One of these arguments -needs to be set to a float, and the other can then be either ignored or set to -a minimum or maximum value. -Ie: If we set latitude to 0 N and leave longitude blank, it would produce a -cube along the equator. On the other hand, if we set latitude to 0 and then -set longitude to `[40., 100.]` this will produce a transect of the equator -in the indian ocean. - -See also :func:`esmvalcore.preprocessor.extract_transect`. - - -5. extract_trajectory ---------------------- - -This function extract data along a specified trajectory. -The three areguments are: latitudes and longitudes are the coordinates of the -trajectory. - -If two points are provided, the `number_points` argument is used to set a -the number of places to extract between the two end points. - -If more than two points are provided, then -extract_trajectory will produce a cube which has extrapolated the data -of the cube to those points, and `number_points` is not needed. - -Note that this function uses the expensive interpolate method, but it may be -necceasiry for irregular grids. - -See also :func:`esmvalcore.preprocessor.extract_trajectory`. - - -CMORization and dataset-specific fixes -====================================== -Documentation of _reformat.py, check.py and fix.py - -Vertical interpolation -====================== -Documentation of _regrid.py (part 1) - -Masking -======= -Documentation of _mask.py (part 1) - -1. Introduction to masking ---------------------------- - -Certain metrics and diagnostics need to be computed and performed on restricted regions of the Globe; ESMValTool supports subsetting the input data on land mass, oceans and seas, ice. This is achived by masking the model data and keeping only the values associated with grid points that correspond to e.g. land mass -or oceans and seas; masking is done either by using standard mask files that have the same grid resolution as the model data (these files are usually produced -at the same time with the model data and are called fx files) or, in the absence of these files, by using Natural Earth masks. Natural Earth masks, even if they are not model-specific, represent a good approximation since their grid resolution is almost always much higher than the model data, and they are constantly updated with changing -geographical features. - -2. Land-sea masking -------------------- - -In ESMValTool v2 land-seas-ice masking can be done in two places: in the preprocessor, to apply a mask on the data before any subsequent preprocessing step, and before -running the diagnostic, or in the disgnostic phase. We present both these implementations below. - -To mask out seas in the preprocessor step, simply add `mask_landsea:` as a preprocessor step in the `preprocessor` of your choice section of the recipe, example: - -.. code-block:: bash - - preprocessors: - my_masking_preprocessor: - mask_landsea: - mask_out: sea - -The tool will retrieve the corresponding `fx: stfof` type of mask for each of the used variables and apply the mask so that only the land mass points are -kept in the data after applying the mask; conversely, it will retrieve the `fx: sftlf` files when land needs to be masked out. -`mask_out` accepts: land or sea as values. If the corresponding fx file is not found (some models are missing these -type of files; observational data is missing them altogether), then the tool attempts to mask using Natural Earth mask files (that are vectorized rasters). -Note that the resolutions for the Natural Earth masks are much higher than any usual CMIP model: 10m for land and 50m for ocean masks. - -3. Ice masking ---------------- - -Note that for masking out ice the preprocessor is using a different function, this so that both land and sea or ice can be masked out without -losing generality. To mask ice out one needs to add the preprocessing step much as above: - -.. code-block:: bash - - preprocessors: - my_masking_preprocessor: - mask_landseaice: - mask_out: ice - -To keep only the ice, one needs to mask out landsea, so use that as value for mask_out. As in the case of mask_landsea, the tool will automatically -retrieve the `fx: sftgif` file corresponding the the used variable and extract the ice mask from it. - -4. mask files --------------- - -At the core of the land/sea/ice masking in the preprocessor are the mask files (whether it be fx type or Natural Earth type of files); these files (bar Natural Earth) -can be retrived and used in the diagnostic phase as well or solely. By specifying the `fx_files:` key in the variable in diagnostic in the recipe, and populating it -with a list of desired files e.g.: - -.. code-block:: bash - - variables: - ta: - preprocessor: my_masking_preprocessor - fx_files: [sftlf, sftof, sftgif, areacello, areacella] - -Such a recipe will automatically retrieve all the `[sftlf, sftof, sftgif, areacello, areacella]`-type fx files for each of the variables that are needed for -and then, in the diagnostic phase, these mask files will be available for the developer to use them as they need to. They `fx_files` attribute of the big `variable` -nested dictionary that gets passed to the diagnostic is, in turn, a dictionary on its own, and members of it can be accessed in the diagnostic through a simple loop over -the 'config' diagnostic variable items e.g.: - -.. code-block:: bash - - for filename, attributes in config['input_data'].items(): - sftlf_file = attributes['fx_files']['sftlf'] - areacello_file = attributes['fx_files']['areacello'] - -5. Missing values masks ------------------------ - -Missing (masked) values can be a nuisance especially when dealing with multimodel ensembles and having to compute -multimodel statistics; different numbers of missing data from dataset to datest may introduce biases and artifically -assign more weight to the datasets that have less missing data. This is handled in ESMValTool via the missing values -masks: two types of such masks are available: one for the multimodel case and another for the single model case. - -The multimodel missing values mask (mask_fillvalues) is a preprocessor step that usually comes after all the single-model -steps (regridding, area selection etc) have been performed; in a nutshell, it combines missing values masks from individual -models into a multimodel missing values mask; the individual model masks are built according to common criteria: -the user chooses a time window in which missing data points are counted, and if the number of missing data points relative -to the number of total data points in a window is less than a chosen fractional theshold, the window is discarded i.e. -all the points in the window are masked (set to missing). - -.. code-block:: bash - - preprocessors: - missing_values_preprocessor: - mask_fillvalues: - threshold_fraction: 0.95 - min_value: 19.0 - time_window: 10.0 - -In the example above, the fractional threshold for missing data vs. total data is set to 95% and the time window is set to -10.0 (units of the time coordinate units). Optionally, a minimum value threshold can be applied, in this case it is set -to 19.0 (in units of the variable units). - -A similar preprocessor step exists for the single-dataset: mask_window_threshold (with the same arguments as mask_fillvalues). - -6. Min, max and interval masking --------------------------------- - -Thresholding on minimum and maximum accepted data values can also be performed: masks are constructed based on the -results of thresholding; inside and outside interval thresholding and masking can also be performed. These functions -are mask_above_threshold, mask_below_threshold, mask_inside_range, and mask_outside_range. - -Horizontal regridding -===================== -Documentation of _regrid.py (part 2) - -Masking of missing values -========================= -Documentation of _mask.py (part 2) - -Multi-model statistics -====================== -Documentation of_multimodel.py - -Time-area statistics -==================== -Documentation of _area_pp.py and _volume_pp.py - -Information on maximum memory required -====================================== -In the most general case, we can set upper limits on the maximum memory the anlysis will require: - - -Ms = (R + N) x F_eff - F_eff - when no multimodel analysis is performed; -Mm = (2R + N) x F_eff - 2F_eff - when multimodel analysis is performed; - -where - -Ms: maximum memory for non-multimodel module -Mm: maximum memory for multimodel module -R: computational efficiency of module; R is typically 2-3 -N: number of datasets -F_eff: average size of data per dataset where F_eff = e x f x F -where e is the factor that describes how lazy the data is (e = 1 for fully realized data) -and f describes how much the data was shrunk by the immediately previous module eg -time extraction, area selection or level extraction; note that for fix_data f relates only to the time extraction, if data is exact in time (no time selection) f = 1 for fix_data - -so for cases when we deal with a lot of datasets (R + N = N), data is fully realized, assuming an average size of 1.5GB for 10 years of 3D netCDF data, N datasets will require - - -Ms = 1.5 x (N - 1) GB -Mm = 1.5 x (N - 2) GB - - -Unit conversion -=============== - -Converting units is also supported. This is particularly useful in -cases where different datasets might have different units, for example -when comparing CMIP5 and CMIP6 variables where the units have changed -or in case of observational datasets that are delivered in different -units. - -In these cases, having a unit conversion at the end of the processing -will guarantee homogeneous input for the diagnostics. - -.. note:: - Conversion is only supported between compatible units! In other - words, converting temperature units from `degC` to `Kelvin` works - fine, changing precipitation units from a rate based unit to an - amount based unit is not supported at the moment. - -See also :func:`esmvalcore.preprocessor.convert_units`. diff --git a/doc/sphinx/source/esmvalcore/recipe.inc b/doc/sphinx/source/esmvalcore/recipe.inc deleted file mode 100644 index 72402f9865..0000000000 --- a/doc/sphinx/source/esmvalcore/recipe.inc +++ /dev/null @@ -1,5 +0,0 @@ -.. _recipe: - -****** -Recipe -****** diff --git a/doc/sphinx/source/esmvaldiag/first_diagnostic.inc b/doc/sphinx/source/esmvaldiag/first_diagnostic.inc deleted file mode 100644 index 1ad5cf6c32..0000000000 --- a/doc/sphinx/source/esmvaldiag/first_diagnostic.inc +++ /dev/null @@ -1,96 +0,0 @@ -******************************************** -How to prepare and run your first diagnostic -******************************************** - -Instructions for personal diagnostic -==================================== - -Anyone can run a personal diagnostic, no matter where the location of it; -there is no need to install esmvaltool in developer mode nor is it to -git push or for that matter, do any git operations; the example recipe - -.. code-block:: bash - esmvaltool/recipes/recipe_my_personal_diagnostic.yml - -shows the use of running a personal diagnostic; the example - -.. code-block:: bash - esmvaltool/diag_scripts/examples/my_little_diagnostic.py - -and any of its alterations may be used as training wheels for the future ESMValTool -diagnostic developer. The purpose of this example is to familiarize the user with -the framework of ESMValTool without the constraints of installing and running the -tool as developer. - -Functionality -============= - -`my_little_diagnostic` (or whatever the user will call their diagnostic) makes full use -of ESMValTool's preprocessor output (both phyisical files and run variables); this output -comes in form of a nested dictionary, or config dictionary, see an example below; -it also makes full use of the ability to call any of the preprocessor's functions, -note that relative imports of modules from the esmvaltool package are allowed and -work without altering the $PYTHONPATH. - -The user may parse this dictionary so that they execute a number of operations on the -preprocessed data; for example the `my_little_diagnostic.plot_time_series` grabs the -preprocessed data output, computes global area averages for each model, then plots -a time-series for each model. Different manipulation functionalities for grouping, -sorting etc of the data in the config dictionary are available, -please consult ESMValTool User Manual. - - -Writing a basic recipe -====================== -The user will need to write a basic recipe to be able to run their own personal diagnostic. -An example of such a recipe is found in `esmvaltool/recipes/recipe_my_personal_diagnostic.yml`. -For general guidelines with regards to ESMValTool recipes please consult the User Guide; -the specific parameters needed by a recipe that runs a personal diagnostic are: - -.. code-block:: bash - scripts: - my_diagnostic: - script: /path/to/your/my_little_diagnostic.py - -i.e. the full path to the personal diagnostic that the user needs to run. - -Example of config dictionary -============================ -``` -{'input_files': -['/group_workspaces/jasmin2/cmip6_prep/esmvaltool_users/valeriu/MyDIAG/recipe_my_personal_diagnostic_20181001_112918/preproc/simple_pp_ta/metadata.yml'], -'log_level': 'info', -'max_data_filesize': 100, -'myDiag': 'my_personal_diagnostic_example', -'myDiagPlace': '/group_workspaces/jasmin2/cmip6_prep/esmvaltool_users/valeriu', -'output_file_type': 'pdf', -'plot_dir': '/group_workspaces/jasmin2/cmip6_prep/esmvaltool_users/valeriu/MyDIAG/recipe_my_personal_diagnostic_20181001_112918/plots/simple/my_diagnostic', 'recipe': 'recipe_my_personal_diagnostic.yml', -'run_dir': '/group_workspaces/jasmin2/cmip6_prep/esmvaltool_users/valeriu/MyDIAG/recipe_my_personal_diagnostic_20181001_112918/run/simple/my_diagnostic', -'script': 'my_diagnostic', -'title': 'My First Diagnostic', -'version': '2.0a1', -'work_dir': '/group_workspaces/jasmin2/cmip6_prep/esmvaltool_users/valeriu/MyDIAG/recipe_my_personal_diagnostic_20181001_112918/work/simple/my_diagnostic', -'write_netcdf': True, -'write_plots': True, -'input_data': {'/group_workspaces/jasmin2/cmip6_prep/esmvaltool_users/valeriu/MyDIAG/recipe_my_personal_diagnostic_20181001_112918/preproc/simple_pp_ta/CMIP5_MPI-ESM-LR_Amon_historical_r1i1p1_T3M_ta_2000-2002.nc': - {'cmor_table': 'CMIP5', - 'dataset': 'MPI-ESM-LR', - 'diagnostic': 'simple', - 'end_year': 2002, - 'ensemble': 'r1i1p1', - 'exp': 'historical', - 'field': 'T3M', - 'filename': '/group_workspaces/jasmin2/cmip6_prep/esmvaltool_users/valeriu/MyDIAG/recipe_my_personal_diagnostic_20181001_112918/preproc/simple_pp_ta/CMIP5_MPI-ESM-LR_Amon_historical_r1i1p1_T3M_ta_2000-2002.nc', - 'fx_files': {'areacello': '/badc/cmip5/data/cmip5/output1/MPI-M/MPI-ESM-LR/historical/fx/ocean/fx/r0i0p0/latest/areacello/areacello_fx_MPI-ESM-LR_historical_r0i0p0.nc', 'sftlf': '/badc/cmip5/data/cmip5/output1/MPI-M/MPI-ESM-LR/historical/fx/atmos/fx/r0i0p0/latest/sftlf/sftlf_fx_MPI-ESM-LR_historical_r0i0p0.nc', 'sftof': '/badc/cmip5/data/cmip5/output1/MPI-M/MPI-ESM-LR/historical/fx/ocean/fx/r0i0p0/latest/sftof/sftof_fx_MPI-ESM-LR_historical_r0i0p0.nc'}, - 'long_name': 'Air Temperature', - 'mip': 'Amon', - 'preprocessor': 'pp', - 'project': 'CMIP5', - 'short_name': 'ta', - 'standard_name': 'air_temperature', - 'start_year': 2000, - 'units': 'K' - } -- end of input_data member value (key: preprocessed file) - } -- end of input_data dictionary -} -- end of config dictionary -``` diff --git a/doc/sphinx/source/esmvaldiag/git_repository.inc b/doc/sphinx/source/esmvaldiag/git_repository.inc deleted file mode 100644 index 23ee046941..0000000000 --- a/doc/sphinx/source/esmvaldiag/git_repository.inc +++ /dev/null @@ -1,179 +0,0 @@ -.. _git_repository: - -*************** -GitHub Workflow -*************** - -Basics -====== - -The source code of the ESMValTool is hosted on GitHub. The following description gives an overview of the typical workflow and usage for implementing new diagnostics or technical changes into the ESMValTool. For general information on Git, see e.g. the online documentation at https://www.git-scm.com/doc. - -There are *two* ESMValTool GitHub repositories available: - -#. The **PUBLIC** GitHub repository is open to the public. The ESMValTool is released as open-source software under the Apache License 2.0. Use of the software constitutes acceptance of this license and terms. The PUBLIC ESMValTool repository is located at https://github.com/ESMValGroup/ESMValTool - -#. The **PRIVATE** GitHub repository is restricted to the ESMValTool Development Team. This repository is only accessible to ESMValTool developers that have accepted the terms of use for the ESMValTool development environment. The use of the ESMValTool software and access to the private ESMValTool GitHub repository constitutes acceptance of these terms. *When you fork or copy this repository, you must ensure that you do not copy the PRIVATE repository into an open domain!* The PRIVATE ESMValTool repository for the ESMValTool development team is located at https://github.com/ESMValGroup/ESMValTool-private - -All developments can be made in either of the two repositories. The creation of *FEATURE BRANCHES* (see below), however, is restricted to registered ESMValTool developers in both repositories. We encourage all developers to join the ESMValTool development team. Please contact the ESMValTool Core Development Team (Section :ref:`core_dev_team`) if you want to join the ESMValTool development team. -The PRIVATE GitHub repository offers a central protected environment for ESMValTool developers who would like to keep their contributions undisclosed (e.g., unpublished scientific work, work in progress by PhD students) while at the same time benefiting from the possibilities of collaborating with other ESMValTool developers and having a backup of their work. *FEATURE BRANCHES* created in the PRIVATE repository are only visible to the ESMValTool development team but not to the public. The concept of a PRIVATE repository has proven to be very useful to efficiently share code during the development across institutions and projects in a common repository without having the contributions immediately accessible to the public. - -Both, the PUBLIC and the PRIVATE repository, contain the following kinds of branches: - -* *MASTER BRANCH* (official releases), -* *DEVELOPMENT BRANCH* (includes approved new contributions but version is not yet fully tested), -* *FEATURE BRANCH* (development branches for new features and diagnostics created by developers, the naming convention for *FEATURE BRANCHES* is _). - -Access rights -============= - -* Write access to the *MASTER* and *DEVELOPMENT BRANCH* in both, the PUBLIC and the PRIVATE GitHub repositories, is restricted to the ESMValTool core development team. -* *FEATURE BRANCHES* in both the PUBLIC and the PRIVATE repository can be created by all members of the ESMValTool development team (i.e. members in the GitHub organization "ESMValGroup"). If needed, branches can be individually write-protected within each repository so that other developers cannot accidently push changes to these branches. - -The *MASTER BRANCH* of the PRIVATE repository will be regularly synchronized with the *MASTER BRANCH* of the PUBLIC repository (currently by hand). This ensures that they are identical at all times (see schematic in :ref:`fig_git`). The recommended workflow for members of the ESMValTool development team is to create additional *FEATURE BRANCHES* in either the PUBLIC or the PRIVATE repository, see further instructions below. - -.. _fig_git: -.. figure:: /figures/git_diagram.png - :align: center - :width: 10cm - - Schematic diagram of the ESMValTool GitHub repositories. - -Workflow -======== - -The following description gives an overview of the typical workflow and usage for implementing new diagnostics or technical changes into the ESMValTool. The description assumes that your local development machine is running a Unix-like operating system. For a general introduction to Git tutorials such as, for instance, https://www.git-scm.com/docs/gittutorial are recommended. - -Getting started ---------------- - -First make sure that you have Git installed on your development machine. On shared machines, software is usually installed using the environment modules. Try e.g. - -.. code:: bash - - module avail git - -if this is the case. You can ask your system administrator for assistance. You can test this with the command: - -.. code:: bash - - git --version - -In order to properly identify your contributions to the ESMValTool you need to configure your local Git with some personal data. This can be done with the following commands: - -.. code:: bash - - git config --global user.name "YOUR NAME" - git config --global user.email "YOUR EMAIL" - -.. note:: For working on GitHub you need to create an account and login to https://github.com/. - -Working with the ESMValTool GitHub Repositories ------------------------------------------------ - -As a member of the ESMValTool development team you can create *FEATURE BRANCHES* in the PUBLIC as well as in the PRIVATE repository. We encourage all ESMValTool developers to use the following workflow for long-lived developments (>2 weeks). - -* Login to GitHub.com -* On GitHub, go to the website of the ESMValTool repository (https://github.com/ESMValGroup/ESMValTool-private or https://github.com/ESMValGroup/ESMValTool) -* Click on the button create *FEATURE BRANCH* -* Select the *"DEVELOPMENT" BRANCH* and create a new *FEATURE BRANCH* for the diagnostic/feature you want to implement. Please follow the following naming convention for your new *FEATURE BRANCH*: _. - -.. figure:: /figures/git_branch.png - :align: center - :width: 6cm - -* Click the button "Clone or Download" and copy the URL shown there -* Open a terminal window and go to the folder where you would like to store your local copy of the ESMValTool source -* Type git clone, and paste the URL: - -.. code:: bash - - git clone - -This will clone the ESMValTool repository at GitHub to a local folder. You can now query the status of your local working copy with: - -.. code:: bash - - git status - -You will see that you are on a branch called master and your local working copy is up to date with the remote repository. With - -.. code:: bash - - git branch --all - -you can list all available remote and local branches. Now switch to your feature branch by: - -.. code:: bash - - git checkout - -You can now start coding. To check your current developments you can use the command - -.. code:: bash - - git status - -You can add new files and folders that you want to have tracked by Git using: - -.. code:: bash - - git add - -Commit your tracked changes to your local working copy via: - -.. code:: bash - - git commit -m "YOUR COMMIT MESSAGE" - -You can inspect your changes with (use man git-log for all options): - -.. code:: bash - - git log - -To share your work and to have an online backup, push your local development to your *FEATURE BRANCH* on GitHub: - -.. code:: bash - - git push origin - -.. note:: An overview on Git commands and best practices can be found e.g. here: https://zeroturnaround.com/rebellabs/git-commands-and-best-practices-cheat-sheet/ - -Pull requests -------------- - -Once your development is completely finished, go to the GitHub website of the ESMValTool repository and switch to your *FEATURE BRANCH*. You can then initiate a pull request by clicking on the button "New pull request". Select the *DEVELOPMENT BRANCH* as "base branch" and click on "Create pull request". Your pull request will then be tested, discussed and implemented into the *DEVELPOMENT BRANCH* by the ESMValTool Core Development Team. - -.. attention:: Before creating a pull request, please make sure all requirements listed in Sections :ref:`writing` and :ref:`documentation` are fully met (see also checklist in :ref:`tab_checklist`). - -GitHub issues -------------- - -In case you encounter a bug of if you have a feature request or something similar you can open an issue on the PUBLIC ESMValTool GitHub repository. - -General do-s and don't-s -======================== - -Do-s ----- - -* Create a *FEATURE BRANCH* and use exclusively this branch for developing the ESMValTool. The naming convention for *FEATURE BRANCHES* is _. -* Comment your code as much as possible and in English. -* Use short but self-explanatory variable names (e.g., model_input and reference_input instead of xm and xr). -* Consider a modular/functional programming style. This often makes code easier to read and deletes intermediate variables immediately. If possible, separate diagnostic calculations from plotting routines. -* Consider reusing or extending existing code. General-purpose code can be found in esmvaltool/diag_scripts/shared/. -* Comment all switches and parameters including a list of all possible settings/options in the header section of your code (see also Section :ref:`std_diag`). -* Use templates for recipes (Section :ref:`std_recipe`) and diagnostics (Section :ref:`std_diag`) to help with proper documentation. -* Keep your *FEATURE BRANCH* regularly synchronized with the *DEVELOPMENT BRANCH* (git merge). -* Keep developments / modifications of the ESMValTool framework / backend / basic structure separate from developments of diagnostics by creating different *FEATURE BRANCHES* for these two kinds of developments. Create *FEATURE BRANCHES* for changes / modifications of the ESMValTool framework only in the *PUBLIC* repository. - -Don't-s -------- - -* Do not use other programming languages than the ones currently supported (NCL, Python, R). Contact the Core Development Team (Section :ref:`core_dev_team`) if you wish to use another language, but remember that only open-source languages are supported by the ESMValTool. -* Do not develop without proper version control (see do-s above). -* Avoid large (memory, disk space) intermediate results. Delete intermediate files/variables or see modular/functional programming style. -* Do not use hard-coded pathnames or filenames. -* Do not mix developments / modifications of the ESMValTool framework and developments / modifications of diagnostics in the same *FEATURE BRANCH*. - diff --git a/doc/sphinx/source/esmvaldiag/index.rst b/doc/sphinx/source/esmvaldiag/index.rst deleted file mode 100644 index 3713f60eca..0000000000 --- a/doc/sphinx/source/esmvaldiag/index.rst +++ /dev/null @@ -1,9 +0,0 @@ -#################################### -Guidelines for diagnostic developers -#################################### - -.. include:: new_diagnostic.inc -.. include:: porting.inc -.. include:: config_developer.inc -.. include:: observations.inc -.. include:: git_repository.inc diff --git a/doc/sphinx/source/esmvaldiag/new_diagnostic.inc b/doc/sphinx/source/esmvaldiag/new_diagnostic.inc deleted file mode 100644 index bf98741688..0000000000 --- a/doc/sphinx/source/esmvaldiag/new_diagnostic.inc +++ /dev/null @@ -1,202 +0,0 @@ -.. _new_diagnostic: - -*************************************** -Contributing a new diagnostic or recipe -*************************************** - -Getting started -=============== - -Please discuss your idea for a new diagnostic or recipe with the development team before getting started, -to avoid disappointment later. A good way to do this is to open an -`issue on GitHub `_. -This is also a good way to get help. - -Creating a recipe and diagnostic script(s) -========================================== -First create a recipe in esmvaltool/recipes to define the input data your analysis script needs -and optionally preprocessing and other settings. Also create a script in the esmvaltool/diag_scripts directory -and make sure it is referenced from your recipe. The easiest way to do this is probably to copy the example recipe -and diagnostic script and adjust those to your needs. -A good example recipe is esmvaltool/recipes/examples/recipe_python.yml -and a good example diagnostic is esmvaltool/diag_scripts/examples/diagnostic.py. - -If you have no preferred programming language yet, Python 3 is highly recommended, because it is most well supported. -However, NCL, R, and Julia scripts are also supported. - -Unfortunately not much documentation is available at this stage, -so have a look at the other recipes and diagnostics for further inspiration. - -Re-using existing code -====================== -Always make sure your code is or can be released under a license that is compatible with the Apache 2 license. - -If you have existing code in a supported scripting language, you have two options for re-using it. If it is fairly -mature and a large amount of code, the preferred way is to package and publish it on the -official package repository for that language and add it as a dependency of esmvaltool. -If it is just a few simple scripts or packaging is not possible (i.e. for NCL) you can simply copy -and paste the source code into the esmvaltool/diag_scripts directory. - -If you have existing code in a compiled language like -C, C++, or Fortran that you want to re-use, the recommended way to proceed is to add Python bindings and publish -the package on PyPI so it can be installed as a Python dependency. You can then call the functions it provides -using a Python diagnostic. - -Interfaces and provenance -========================= -When ESMValTool runs a recipe, it will first find all data and run the default preprocessor steps plus any -additional preprocessing steps defined in the recipe. Next it will run the diagnostic script defined in the recipe -and finally it will store provenance information. Provenance information is stored in the -`W3C PROV XML format `_ -and also plotted in an SVG file for human inspection. In addition to provenance information, a caption is also added -to the plots. - -In order to communicate with the diagnostic script, two interfaces have been defined, which are described below. -Note that for Python and NCL diagnostics much more convenient methods are available than -directly reading and writing the interface files. For other languages these are not implemented yet. - -Using the interfaces from Python --------------------------------- -Always use :meth:`esmvaltool.diag_scripts.shared.run_diagnostic` to start your script and make use of a -:class:`esmvaltool.diag_scripts.shared.ProvenanceLogger` to log provenance. Have a look at the example -Python diagnostic in esmvaltool/diag_scripts/examples/diagnostic.py for a complete example. - -Using the interfaces from NCL ------------------------------ -Always call the ``log_provenance`` procedure after plotting from your NCL diag_script. You could find available shortcuts for -statistics, domain, plottype, authors and references in the ``config-references.yml`` file. - -.. code-block:: bash - - log_provenance(nc-file,plot_file,caption,statistics,domain,plottype,authors,references,input-files) - -Have a look at the example NCL diagnostic in ``esmvaltool/diag_scripts/examples/diagnostic.ncl`` for a complete example. - -Generic interface between backend and diagnostic ------------------------------------------------- -To provide the diagnostic script with the information it needs to run (e.g. location of input data, various settings), -the backend creates a YAML file called settings.yml and provides the path to this file as the first command line -argument to the diagnostic script. - -The most interesting settings provided in this file are - -.. code:: yaml - - run_dir: /path/to/recipe_output/run/diagnostic_name/script_name - work_dir: /path/to/recipe_output/work/diagnostic_name/script_name - plot_dir: /path/to/recipe_output/work/diagnostic_name/script_name - input_files: - - /path/to/recipe_output/preproc/diagnostic_name/ta/metadata.yml - - /path/to/recipe_output/preproc/diagnostic_name/pr/metadata.yml - -Custom settings in the script section of the recipe will also be made available in this file. - -There are three directories defined: - -- :code:`run_dir` use this for storing temporary files -- :code:`work_dir` use this for storing NetCDF files containing the data used to make a plot -- :code:`plot_dir` use this for storing plots - -Finally :code:`input_files` is a list of YAML files, containing a description of the preprocessed data. Each entry in these -YAML files is a path to a preprocessed file in NetCDF format, with a list of various attributes. -An example preprocessor metadata.yml file could look like this - -.. code:: yaml - - ? /path/to/recipe_output/preproc/diagnostic_name/pr/CMIP5_GFDL-ESM2G_Amon_historical_r1i1p1_T2Ms_pr_2000-2002.nc - : cmor_table: CMIP5 - dataset: GFDL-ESM2G - diagnostic: diagnostic_name - end_year: 2002 - ensemble: r1i1p1 - exp: historical - filename: /path/to/recipe_output/preproc/diagnostic_name/pr/CMIP5_GFDL-ESM2G_Amon_historical_r1i1p1_T2Ms_pr_2000-2002.nc - frequency: mon - institute: [NOAA-GFDL] - long_name: Precipitation - mip: Amon - modeling_realm: [atmos] - preprocessor: preprocessor_name - project: CMIP5 - recipe_dataset_index: 1 - reference_dataset: MPI-ESM-LR - short_name: pr - standard_name: precipitation_flux - start_year: 2000 - units: kg m-2 s-1 - variable_group: pr - ? /path/to/recipe_output/preproc/diagnostic_name/pr/CMIP5_MPI-ESM-LR_Amon_historical_r1i1p1_T2Ms_pr_2000-2002.nc - : cmor_table: CMIP5 - dataset: MPI-ESM-LR - diagnostic: diagnostic_name - end_year: 2002 - ensemble: r1i1p1 - exp: historical - filename: /path/to/recipe_output/preproc/diagnostic1/pr/CMIP5_MPI-ESM-LR_Amon_historical_r1i1p1_T2Ms_pr_2000-2002.nc - frequency: mon - institute: [MPI-M] - long_name: Precipitation - mip: Amon - modeling_realm: [atmos] - preprocessor: preprocessor_name - project: CMIP5 - recipe_dataset_index: 2 - reference_dataset: MPI-ESM-LR - short_name: pr - standard_name: precipitation_flux - start_year: 2000 - units: kg m-2 s-1 - variable_group: pr - -Generic interface between diagnostic and backend ------------------------------------------------- - -After the diagnostic script has finished running, the backend will try to store provenance information. In order to -link the produced files to input data, the diagnostic script needs to store a YAML file called :code:`diagnostic_provenance.yml` -in it's :code:`run_dir`. - -For output file produced by the diagnostic script, there should be an entry in the :code:`diagnostic_provenance.yml` file. -The name of each entry should be the path to the output file. -Each file entry should at least contain the following items - -- :code:`ancestors` a list of input files used to create the plot -- :code:`caption` a caption text for the plot -- :code:`plot_file` if the diagnostic also created a plot file, e.g. in .png format. - -Each file entry can also contain items from the categories defined in the file :code:`esmvaltool/config_references.yml`. -The short entries will automatically be replaced by their longer equivalent in the final provenance records. -It is possible to add custom provenance information by adding custom items to entries. - -An example :code:`diagnostic_provenance.yml` file could look like this - -.. code:: yaml - - ? /path/to/recipe_output/work/diagnostic_name/script_name/CMIP5_GFDL-ESM2G_Amon_historical_r1i1p1_T2Ms_pr_2000-2002_mean.nc - : ancestors: - - /path/to/recipe_output/preproc/diagnostic_name/pr/CMIP5_GFDL-ESM2G_Amon_historical_r1i1p1_T2Ms_pr_2000-2002.nc - authors: [ande_bo, righ_ma] - caption: Average Precipitation between 2000 and 2002 according to GFDL-ESM2G. - domains: [global] - plot_file: /path/to/recipe_output/plots/diagnostic_name/script_name/CMIP5_GFDL-ESM2G_Amon_historical_r1i1p1_T2Ms_pr_2000-2002_mean.png - plot_type: zonal - references: [acknow_project] - statistics: [mean] - ? /path/to/recipe_output/work/diagnostic_name/script_name/CMIP5_MPI-ESM-LR_Amon_historical_r1i1p1_T2Ms_pr_2000-2002_mean.nc - : ancestors: - - /path/to/recipe_output/preproc/diagnostic_name/pr/CMIP5_MPI-ESM-LR_Amon_historical_r1i1p1_T2Ms_pr_2000-2002.nc - authors: [ande_bo, righ_ma] - caption: Average Precipitation between 2000 and 2002 according to MPI-ESM-LR. - domains: [global] - plot_file: /path/to/recipe_output/plots/diagnostic_name/script_name/CMIP5_MPI-ESM-LR_Amon_historical_r1i1p1_T2Ms_pr_2000-2002_mean.png - plot_type: zonal - references: [acknow_project] - statistics: [mean] - -You can check whether your diagnostic script successfully provided the provenance information to the backend by -verifying that - -- for each output file in the :code:`work_dir`, a file with the same name, but ending with _provenance.xml is created -- any NetCDF files created by your diagnostic script contain a 'provenance' global attribute -- any PNG plots created by your diagnostic script contain the provenance information in the 'Image History' attribute - -Note that this is done automatically by the ESMValTool backend. diff --git a/doc/sphinx/source/esmvaldiag/observations.inc b/doc/sphinx/source/esmvaldiag/observations.inc deleted file mode 100644 index fff8ade0fd..0000000000 --- a/doc/sphinx/source/esmvaldiag/observations.inc +++ /dev/null @@ -1,7 +0,0 @@ -:: _CMORobs: - -************************************************************ -Contributing a CMORizing script for an observational dataset -************************************************************ - - diff --git a/doc/sphinx/source/esmvaldiag/porting.inc b/doc/sphinx/source/esmvaldiag/porting.inc deleted file mode 100644 index 5216abcce8..0000000000 --- a/doc/sphinx/source/esmvaldiag/porting.inc +++ /dev/null @@ -1,216 +0,0 @@ -.. _porting: - -************************************************************ -Porting a namelist (recipe) or diagnostic to ESMValTool v2.0 -************************************************************ - -This guide summarizes the main steps to be taken in order to port an ESMValTool namelist (now called **recipe**) and the corresponding diagnostic(s) from v1.0 to v2.0, hereafter also referred as the *"old"* and the *"new version"*, respectively. The new ESMValTool version is being developed in the public git branch ``version2_development``. An identical version of this branch is maintained in the private repository as well and kept synchronized on an hourly basis. - -In the following, it is assumed that the user has successfully installed ESMValTool v2 and has a rough overview of its structure (see `Technical Overview `_). - -Create a github issue -===================== - -Create an issue in the public repository to keep track of your work and inform other developers. See an example `here `_. Use the following title for the issue: "PORTING into v2.0". -Do not forget to assign it to yourself. - -Create your own branch -====================== - -Create your own branch from ``version2_development`` for each namelist (recipe) to be ported: - -.. code-block:: bash - - git checkout version2_development - git checkout -b version2_ - -``version2_development`` contains only v2.0 under the ``./esmvaltool/`` directory. - -Convert xml to yml -================== - -In ESMValTool v2.0, the namelist (now recipe) is written in yaml format (`Yet Another Markup Language format `_). It may be useful to activate the yaml syntax highlighting for the editor in use. This improves the readability of the recipe file and facilitates the editing, especially concerning the indentations which are essential in this format (like in python). Instructions can be easily found online, for example for `emacs `_ and `vim `_. - -A xml2yml converter is available in ``esmvaltool/utils/xml2yml/``, please refer to the corresponding README file for detailed instructions on how to use it. - -Once the recipe is converted, a first attempt to run it can be done, possibly starting with a few datasets and one diagnostics and proceed gradually. The recipe file ``./esmvaltool/recipes/recipe_perfmetrics_CMIP5.yml`` can be used as an example, as it covers most of the common cases. - -Do not forget to also rewrite the recipe header in a ``documentation`` section using the yaml syntax and, if possible, to add themes and realms item to each diagnostic section. All keys and tags used for this part must be defined in ``./esmvaltool/config-references.yml``. See ``./esmvaltool/recipes/recipe_perfmetrics_CMIP5.yml`` for an example. - -Create a copy of the diag script in v2.0 -======================================== - -The diagnostic script to be ported goes into the directory ./esmvaltool/diag_script/. It is recommended to get a copy of the very last version of the script to be ported from the development branch (either in the public or in the private repository). Just create a local (offline) copy of this file from the repository and add it to ../esmvaltool/diag_script/ as a new file. - -Note that (in general) this is not necessary for plot scripts and for the libraries in ``./esmvaltool/diag_script/ncl/lib/``, which have already been ported. Changes may however still be necessary, especially in the plot scripts which have not yet been fully tested with all diagnostics. - -Check and apply renamings -========================= - -The new ESMValTool version includes a completely revised interface, handling the communication between the python workflow and the (NCL) scripts. This required several variables and functions to be renamed or removed. These chagnes are listed in the following table and have to be applied to the diagnostic code before starting with testing. - -.. tabularcolumns:: |p{6cm}|p{6cm}|p{3cm}| - -+-------------------------------------------------+-----------------------------------------------------------+------------------+ -| Name in v1.0 | Name in v2.0 | Affected code | -+=================================================+===========================================================+==================+ -| ``getenv("ESMValTool_wrk_dir")`` | ``config_user_info@work_dir`` | all .ncl scripts | -+-------------------------------------------------+-----------------------------------------------------------+------------------+ -| ``getenv(ESMValTool_att)`` | ``diag_script_info@att`` or | all .ncl scripts | -| | ``config_user_info@att`` | | -+-------------------------------------------------+-----------------------------------------------------------+------------------+ -| ``xml`` | ``yml`` | all scripts | -+-------------------------------------------------+-----------------------------------------------------------+------------------+ -| ``var_attr_ref(0)`` | ``variable_info@reference_dataset`` | all .ncl scripts | -+-------------------------------------------------+-----------------------------------------------------------+------------------+ -| ``var_attr_ref(1)`` | ``variable_info@alternative_dataset`` | all .ncl scripts | -+-------------------------------------------------+-----------------------------------------------------------+------------------+ -| ``models`` | ``input_file_info`` | all .ncl scripts | -+-------------------------------------------------+-----------------------------------------------------------+------------------+ -| ``models@name`` | ``input_file_info@dataset`` | all .ncl scripts | -+-------------------------------------------------+-----------------------------------------------------------+------------------+ -| ``verbosity`` | ``config_user_info@log_level`` | all .ncl scripts | -+-------------------------------------------------+-----------------------------------------------------------+------------------+ -| ``isfilepresent_esmval`` | ``fileexists`` | all .ncl scripts | -+-------------------------------------------------+-----------------------------------------------------------+------------------+ -| ``messaging.ncl`` | ``logging.ncl`` | all .ncl scripts | -+-------------------------------------------------+-----------------------------------------------------------+------------------+ -| ``info_output(arg1, arg2, arg3)`` | ``log_info(arg1)`` if ``arg3=1`` | all .ncl scripts | -+-------------------------------------------------+-----------------------------------------------------------+------------------+ -| ``info_output(arg1, arg2, arg3)`` | ``log_debug(arg1)`` if ``arg3>1`` | all .ncl scripts | -+-------------------------------------------------+-----------------------------------------------------------+------------------+ -| ``verbosity = config_user_info@verbosity`` | remove this statement | all .ncl scripts | -+-------------------------------------------------+-----------------------------------------------------------+------------------+ -| ``enter_msg(arg1, arg2, arg3)`` | ``enter_msg(arg1, arg2)`` | all .ncl scripts | -+-------------------------------------------------+-----------------------------------------------------------+------------------+ -| ``leave_msg(arg1, arg2, arg3)`` | ``leave_msg(arg1, arg2)`` | all .ncl scripts | -+-------------------------------------------------+-----------------------------------------------------------+------------------+ -| ``noop()`` | appropriate ``if-else`` statement | all .ncl scripts | -+-------------------------------------------------+-----------------------------------------------------------+------------------+ -| ``nooperation()`` | appropriate ``if-else`` stsatement | all .ncl scripts | -+-------------------------------------------------+-----------------------------------------------------------+------------------+ -| ``fullpaths`` | ``input_file_info@filename`` | all .ncl scripts | -+-------------------------------------------------+-----------------------------------------------------------+------------------+ -| ``get_output_dir(arg1, arg2)`` | ``config_user_info@plot_dir`` | all .ncl scripts | -+-------------------------------------------------+-----------------------------------------------------------+------------------+ -| ``get_work_dir`` | ``config_user_info@work_dir`` | all .ncl scripts | -+-------------------------------------------------+-----------------------------------------------------------+------------------+ -| ``inlist(arg1, arg2)`` | ``any(arg1.eq.arg2)`` | all .ncl scripts | -+-------------------------------------------------+-----------------------------------------------------------+------------------+ -| ``load interface_scripts/*.ncl`` | ``load $diag_scripts/../interface_scripts/interface.ncl`` | all .ncl scripts | -+-------------------------------------------------+-----------------------------------------------------------+------------------+ -| ``_info.tmp`` | ``_info.ncl`` in ``preproc`` dir | all .ncl scripts | -+-------------------------------------------------+-----------------------------------------------------------+------------------+ -| ``ncl.interface`` | ``settings.ncl`` in ``run_dir`` and | all .ncl scripts | -| | ``interface_scripts/interface.ncl`` | | -+-------------------------------------------------+-----------------------------------------------------------+------------------+ -| ``load diag_scripts/lib/ncl/`` | ``load $diag_scripts/shared/`` | all .ncl scripts | -+-------------------------------------------------+-----------------------------------------------------------+------------------+ -| ``load plot_scripts/ncl/`` | ``load $diag_scripts/shared/plot/`` | all .ncl scripts | -+-------------------------------------------------+-----------------------------------------------------------+------------------+ -| ``load diag_scripts/lib/ncl/rgb/`` | ``load $diag_scripts/shared/plot/rgb/`` | all .ncl scripts | -+-------------------------------------------------+-----------------------------------------------------------+------------------+ -| ``load diag_scripts/lib/ncl/styles/`` | ``load $diag_scripts/shared/plot/styles`` | all .ncl scripts | -+-------------------------------------------------+-----------------------------------------------------------+------------------+ -| ``load diag_scripts/lib/ncl/misc_function.ncl`` | ``load $diag_scripts/shared/plot/misc_function.ncl`` | all .ncl scripts | -+-------------------------------------------------+-----------------------------------------------------------+------------------+ -| ``LW_CRE``, ``SW_CRE`` | ``lwcre``, ``swcre`` | some yml recipes | -+-------------------------------------------------+-----------------------------------------------------------+------------------+ -| ``check_min_max_models`` | ``check_min_max_datasets`` | all .ncl scripts | -+-------------------------------------------------+-----------------------------------------------------------+------------------+ -| ``get_ref_model_idx`` | ``get_ref_dataset_idx`` | all .ncl scripts | -+-------------------------------------------------+-----------------------------------------------------------+------------------+ -| ``get_model_minus_ref`` | ``get_dataset_minus_ref`` | all .ncl scripts | -+-------------------------------------------------+-----------------------------------------------------------+------------------+ - -The following changes may also have to be considered: - -- namelists are now called recipes and collected in ``esmvaltool/recipes``; -- models are now called datasets and all files have been updated accordingly, including NCL functions (see table above); -- ``run_dir`` (previous ``interface_data``), ``plot_dir``, ``work_dir`` are now unique to each diagnostic script, so it is no longer necessary to define specific paths in the diagnostic scripts to prevent file collision; -- `input_file_info`` is now a list of a list of logicals, where each element describes one dataset and one variable. Convenience functions to extract the required elements (e.g., all datasets of a given variable) are provided in ``esmvaltool/interface_scripts/interface.ncl``; -- the interface functions ``interface_get_*`` and ``get_figure_filename`` are no longer available: their functionalities can be easily reproduced using the ``input_file_info`` and the convenience functions in ``esmvaltool/interface_scripts/interface.ncl`` to access the required attributes; -- there are now only 4 log levels (``debug``, ``info``, ``warning``, and ``error``) instead of (infinite) numerical values in ``verbosity`` -- diagnostic scripts are now organized in subdirectories in ``esmvaltool/diag_scripts/``: all scripts belonging to the same diagnostics are to be collected in a single subdirectory (see ``esmvaltool/diag_scripts/perfmetrics/`` for example). This applies also to the ``aux_`` scripts, unless they are shared among multiple diagnostics (in this case they go in ``shared/``); -- the relevant input_file_info items required by a plot routine should be passed as argument to the routine itself; -- upper case characters have to be avoided in script names, if possible. - -As for the recipe, the diagnostic script ``./esmvaltool/diag_scripts/perfmetrics/main.ncl`` can be followed as working example. - -Move preprocessing from the diagnostic script to the backend -============================================================ - -Many operations previously performed by the diagnostic scripts, are now included in the backend, including level extraction, regridding, masking, and multi-model statistics. If the diagnostics to be ported contains code performing any of such operations, the corresponding code has to be removed from the diagnostic script and the respective backend functionality can be used instead. - -The backend operations are fully controlled by the ``preprocessors`` section in the recipe. Here, a number of preprocessor sets can be defined, with different options for each of the operations. The sets defined in this section are applied in the ``diagnostics`` section to preprocess a given variable. - -It is recommended to proceed step by step, porting and testing each operation separately before proceeding with the next one. A useful setting in the user configuration file (``config-private.yml``) called ``write_intermediary_cube`` allows writing out the variable field after each preprocessing step, thus facilitating the comparison with the old version (e.g., after CMORization, level selection, after regridding, etc.). The CMORization step of the new backend exactly corresponds to the operation performed by the old backend (and stored in the ``climo`` directory, now called ``preprec``): this is the very first step to be checked, by simply comparing the intermediary file produced by the new backend after CMORization with the output of the old backend in the ``climo`` directorsy (see "Testing" below for instructions). - -The new backend also performs variable derivation, replacing the ``calculate`` function in the ``variable_defs`` scripts. If the recipe which is being ported makes use of derived variables, the corresponding calculation must be ported from the ``./variable_defs/.ncl`` file to ``./esmvaltool/preprocessor/_derive.py``. - -Note that the Python library ``esmval_lib``, containing the ``ESMValProject`` class is no longer available in version 2. Most functionalities have been moved to the new preprocessor. If you miss a feature, please open an issue on github [https://github.com/ESMValGroup/ESMValTool/issues]. - -Move diagnostic- and variable-specific settings to the recipe -=============================================================== - -In the new version, all settings are centralized in the recipe, completely replacing the diagnostic-specific settings in ``./nml/cfg_files/`` (passed as ``diag_script_info`` to the diagnostic scripts) and the variable-specific settings in ``variable_defs/.ncl`` (passed as ``variable_info``). There is also no distinction anymore between diagnostic- and variable-specific settings: they are collectively defined in the ``scripts`` dictionary of each diagnostic in the recipe and passed as ``diag_script_info`` attributes by the new ESMValTool interface. Note that the ``variable_info`` logical still exists, but it is used to pass variable information as given in the corresponding dictionary of the recipe. - -Make sure the diagnostic script writes NetCDF output -====================================================== - -Each diagnostic script is required to write the output of the anaylsis in one or more NetCDF files. This is to give the user the possibility to further look into the results, besides the plots, but (most importantly) for tagging purposes when publishing the data in a report and/or on a website. - -For each of the plot produced by the diagnostic script a single NetCDF file has to be generated. The variable saved in this file should also contain all the necessary metadata that documents the plot (dataset names, units, statistical methods, etc.). -The files have to be saved in the work directory (defined in `cfg['work_dir']` and `config_user_info@work_dir`, for the python and NCL diagnostics, respectively). - -Test the recipe/diagnostic in the new version -=============================================== - -Once complete, the porting of the diagnostic script can be tested. Most of the diagnostic script allows writing the output in a NetCDF file before calling the plotting routine. This output can be used to check whether the results of v1.0 are correctly reproduced. As a reference for v1.0, it is recommended to use the development branch. - -There are two methods for comparing NetCDF files: ``cdo`` and ``ncdiff``. The first method is applied with the command: - -.. code-block:: bash - - cdo diffv old_output.nc new_output.nc - -which will print a log on the stdout, reporting how many records of the file differ and the absolute/relative differences. - -The second method produces a NetCDF file (e.g., ``diff.nc``) with the difference between two given files: - -.. code-block:: bash - - ncdiff old_output.nc new_output.nc diff.nc - -This file can be opened with ``ncview`` to visually inspect the differences. - -In general, binary identical results cannot be expected, due to the use of different languages and algorithms in the two versions, especially for complex operations such as regridding. However, difference within machine precision are desirable. At this stage, it is essential to test all datasets in the recipe and not just a subset of them. - -It is also recommended to compare the graphical output (this may be necessary if the ported diagnostic does not produce a NetCDF output). For this comparison, the PostScript format is preferable, since it is easy to directly compare two PostScript files with the standard ``diff`` command in Linux: - -.. code-block:: bash - - diff old_graphic.ps new_graphic.ps - -but it is very unlikely to produce no differences, therefore visual inspection of the output may also be required. - -Clean the code -============== - -Before submitting a pull request, the code should be cleaned to adhere to the coding standard, which are somehow stricter in v2.0. This check is performed automatically on GitHub (CircleCI and Codacy) when opening a pull request on the public repository. A code-style checker (``nclcodestyle``) is available in the tool to check NCL scripts and installed alongside the tool itself. When checking NCL code style, the following should be considered in addition to the warning issued by the style checker: - -- two-space instead of four-space indentation is now adopted for NCL as per NCL standard; -- ``load`` statements for NCL standard libraries should be removed: these are automatically loaded since NCL v6.4.0 (see `NCL documentation `_); -- the description of diagnostic- and variable-specific settings can be moved from the header of the diagnostic script to the recipe, since the settings are now defined there (see above); -- NCL ``print`` and ``printVarSummary`` statements must be avoided and replaced by the ``log_info`` and ``log_debug`` functions; -- for error and warning statments, the ``error_msg`` function can be used, which automatically include an exit statement. - -Update the documentation -======================== - -If necessary, add or update the documentation for your recipes in the corrsponding rst file, which is now in ``doc\sphinx\source\recipes``. Do not forget to also add the documentation file to the list in ``doc\sphinx\source\annex_c`` to make sure it actually appears in the documentation. - -Open a pull request -=================== - -Create a pull request on github to merge your branch back to ``version2_development``, provide a short description of what has been done and nominate one or more reviewers. diff --git a/doc/sphinx/source/figures/ESMValTool-logo.pdf b/doc/sphinx/source/figures/ESMValTool-logo.pdf deleted file mode 100644 index 56bd147951..0000000000 Binary files a/doc/sphinx/source/figures/ESMValTool-logo.pdf and /dev/null differ diff --git a/doc/sphinx/source/figures/git_branch.png b/doc/sphinx/source/figures/git_branch.png deleted file mode 100644 index 585f71f158..0000000000 Binary files a/doc/sphinx/source/figures/git_branch.png and /dev/null differ diff --git a/doc/sphinx/source/figures/git_diagram.png b/doc/sphinx/source/figures/git_diagram.png deleted file mode 100644 index d35bedf8b7..0000000000 Binary files a/doc/sphinx/source/figures/git_diagram.png and /dev/null differ diff --git a/doc/sphinx/source/figures/schematic.png b/doc/sphinx/source/figures/schematic.png deleted file mode 100644 index fce8f16c69..0000000000 Binary files a/doc/sphinx/source/figures/schematic.png and /dev/null differ diff --git a/doc/sphinx/source/getting_started/config_user.inc b/doc/sphinx/source/getting_started/config_user.inc deleted file mode 100644 index 9aca5de17f..0000000000 --- a/doc/sphinx/source/getting_started/config_user.inc +++ /dev/null @@ -1,88 +0,0 @@ -.. _config_user: - -*********************** -User configuration file -*********************** - -The ``config-user.yml`` configuration file contains all the global level -information needed by ESMValTool. The following shows the default settings from -the ``config-user.yml`` file. - -.. code-block:: yaml - - # Diagnostics create plots? [true]/false - write_plots: true - # Diagnositcs write NetCDF files? [true]/false - write_netcdf: true - # Set the console log level debug, [info], warning, error - log_level: info - # verbosity is deprecated and will be removed in the future - # verbosity: 1 - # Exit on warning? true/[false] - exit_on_warning: false - # Plot file format? [ps]/pdf/png/eps/epsi - output_file_type: pdf - # Destination directory - output_dir: ./esmvaltool_output - # Auxiliary data directory (used for some additional datasets) - auxiliary_data_dir: ./auxiliary_data - # Use netCDF compression true/[false] - compress_netcdf: false - # Save intermediary cubes in the preprocessor true/[false] - save_intermediary_cubes: false - # Remove the preproc dir if all fine - remove_preproc_dir: true - # Run at most this many tasks in parallel null/[1]/2/3/4/.. - # Set to null to use the number of available CPUs. - # Make sure your system has enough memory for the specified number of tasks. - max_parallel_tasks: 1 - # Path to custom config-developer file, to customise project configurations. - # See config-developer.yml for an example. Set to None to use the default - config_developer_file: null - # Get profiling information for diagnostics - # Only available for Python diagnostics - profile_diagnostic: false - - # Rootpaths to the data from different projects (lists are also possible) - rootpath: - CMIP5: [~/cmip5_inputpath1, ~/cmip5_inputpath2] - OBS: ~/obs_inputpath - default: ~/default_inputpath - - # Directory structure for input data: [default]/BADC/DKRZ/ETHZ/etc - # See config-developer.yml for definitions. - drs: - CMIP5: default - -Most of these settings are fairly self-explanatory, ie: - -.. code-block:: yaml - - # Diagnostics create plots? [true]/false - write_plots: true - # Diagnositcs write NetCDF files? [true]/false - write_netcdf: true - -The ``write_plots`` setting is used to inform ESMValTool about your preference -for saving figures. Similarly, the ``write_netcdf`` setting is a boolean which -turns on or off the writing of netCDF files. - -.. code-block:: yaml - - # Auxiliary data directory (used for some additional datasets) - auxiliary_data_dir: ./auxiliary_data - -The ``auxiliary_data_dir`` setting is the path to place any required -additional auxiliary data files. This method was necessary because certain -Python toolkits such as cartopy will attempt to download data files at run -time, typically geographic data files such as coastlines or land surface maps. -This can fail if the machine does not have access to the wider internet. This -location allows us to tell cartopy (and other similar tools) where to find the -files if they can not be downloaded at runtime. To reiterate, this setting is -not for model or observational datasets, rather it is for data files used in -plotting such as coastline descriptions and so on. - - -Tip: You choose your config.yml file at run time, so you could have several -available with different purposes. One for formalised run, one for debugging, -etc... diff --git a/doc/sphinx/source/getting_started/index.rst b/doc/sphinx/source/getting_started/index.rst deleted file mode 100644 index a16f696e37..0000000000 --- a/doc/sphinx/source/getting_started/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -####################### -Getting started -####################### - -.. include:: install.inc -.. include:: config_user.inc -.. include:: inputdata.inc -.. include:: running.inc -.. include:: outputdata.inc - diff --git a/doc/sphinx/source/getting_started/inputdata.inc b/doc/sphinx/source/getting_started/inputdata.inc deleted file mode 100644 index 2aaa80e632..0000000000 --- a/doc/sphinx/source/getting_started/inputdata.inc +++ /dev/null @@ -1,93 +0,0 @@ -:: _inputdata: - -********** -Input data -********** - -Models -====== - -Observations -============ - -Observational and reanalysis products in the standard CF/CMOR format used in CMIP and required by the ESMValTool are available via the obs4mips (https://esgf-node.llnl.gov/projects/obs4mips/) and ana4mips (https://esgf.nccs.nasa.gov/projects/ana4mips/) proejcts, respectively. Their use is strongly recommended, when possible. - -Other datasets not available in these archives can be obtained by the user from the respective sources and reformatted to the CF/CMOR standard using the cmorizers included in the ESMValTool. The cmorizers are dataset-specific scripts that can be run once to generate a local pool of observational datasets for usage with the ESMValTool. The necessary information to download and process the data is provided in the header of each cmorizing script. These scripts also serve as template to create new cmorizers for datasets not yet included. Note that dataset cmorized for ESMValTool v1 may not be working with v2, due to the much stronger constraints on metadata set by the Iris library. - -To cmorize one or more datasets, run: - -.. code-block:: bash - - cmorize_obs -c [CONFIG_FILE] -o [DATASET_LIST] - -The path to the raw data to be cmorized must be specified in the CONFIG_FILE as RAWOBS. Within this path, the data are expected to be organized in subdirectories corresponding to the data tier: Tier2 for freely-available datasets (other than obs4mips and ana4mips) and Tier3 for restricted datasets (i.e., dataset which requires a registration to be retrieved or provided upon request to the respective contact or PI). The cmorization follows the CMIP5 CMOR tables. The resulting output is saved in the output_dir, again following the Tier structure. The output file names follow the definition given in ``config-developer.yml`` for the ``OBS`` project: ``OBS_[dataset]_[type]_[version]_[mip]_[short_name]_YYYYMM_YYYYMM.nc``, where ``type`` may be ``sat`` (satellite data), ``reanaly`` (reanalysis data), ``ground`` (ground observations), ``clim`` (derived climatologies), ``campaign`` (aircraft campaign). - - -At the moment, cmorize_obs supports Python and NCL scripts. - -A list of the datasets for which a cmorizers is available is provided in the following table. - -.. tabularcolumns:: |p{3cm}|p{6cm}|p{3cm}|p{3cm}| - -+------------------------------+------------------------------------------------------------------------------------------------------+------+-----------------+ -| Dataset | Variables (MIP) | Tier | Script language | -+==============================+======================================================================================================+======+=================+ -| AURA-TES | tro3 (Amon) | 3 | NCL | -+------------------------------+------------------------------------------------------------------------------------------------------+------+-----------------+ -| CDS-SATELLITE-SOIL-MOISTURE | sm (Lmon), smStderr (Lmon) | 3 | NCL | -+------------------------------+------------------------------------------------------------------------------------------------------+------+-----------------+ -| CDS-XCH4 | xch4 (Amon) | 3 | NCL | -+------------------------------+------------------------------------------------------------------------------------------------------+------+-----------------+ -| CDS-XCO2 | xco2 (Amon) | 3 | NCL | -+------------------------------+------------------------------------------------------------------------------------------------------+------+-----------------+ -| CERES-SYN1deg | rlds, rldscs, rlus, rluscs, rlut, rlutcs, rsds, rsdscs, rsus, rsuscs, rsut, rsutcs (3hr) | 3 | NCL | -| | rlds, rldscs, rlus, rlut, rlutcs, rsds, rsdt, rsus, rsut, rsutcs (Amon) | | | -+------------------------------+------------------------------------------------------------------------------------------------------+------+-----------------+ -| CRU | tas, pr (Amon) | 2 | Python | -+------------------------------+------------------------------------------------------------------------------------------------------+------+-----------------+ -| ERA-Interim | clivi, clt, clwvi, hfds, hur, hus, pr, prw, ps, psl, ta, tas, tauu, tauv, ts, ua, va, wap, zg (Amon) | 3 | NCL | -| | pr, psl, tas, tasmin, tasmax, zg (day), sftlf (fx), tos (Omon) | | | -+------------------------------+------------------------------------------------------------------------------------------------------+------+-----------------+ -| ESACCI-AEROSOL | abs550aer, od550aer, od550aerStderr, od550lt1aer, od870aer, od870aerStderr (aero) | 2 | NCL | -+------------------------------+------------------------------------------------------------------------------------------------------+------+-----------------+ -| ESACCI-CLOUD | clivi, clt, cltStderr, clwvi (Amon) | 2 | NCL | -+------------------------------+------------------------------------------------------------------------------------------------------+------+-----------------+ -| ESACCI-FIRE | burntArea (Lmon) | 2 | NCL | -+------------------------------+------------------------------------------------------------------------------------------------------+------+-----------------+ -| ESACCI-LANDCOVER | baresoilFrac, cropFrac, grassFrac, shrubFrac, treeFrac (Lmon) | 2 | NCL | -+------------------------------+------------------------------------------------------------------------------------------------------+------+-----------------+ -| ESACCI-OC | chl | 2 | Python | -+------------------------------+------------------------------------------------------------------------------------------------------+------+-----------------+ -| ESACCI-OZONE | toz, tozStderr, tro3prof, tro3profStderr (Amon) | 2 | NCL | -+------------------------------+------------------------------------------------------------------------------------------------------+------+-----------------+ -| ESACCI-SOILMOISTURE | dos, dosStderr, sm, smStderr (Lmon) | 2 | NCL | -+------------------------------+------------------------------------------------------------------------------------------------------+------+-----------------+ -| ESACCI-SST | ts, tsStderr (Amon) | 2 | NCL | -+------------------------------+------------------------------------------------------------------------------------------------------+------+-----------------+ -| GHCN | pr (Amon) | 2 | NCL | -+------------------------------+------------------------------------------------------------------------------------------------------+------+-----------------+ -| HadCRUT3 | tas, tasa (Amon) | 2 | NCL | -+------------------------------+------------------------------------------------------------------------------------------------------+------+-----------------+ -| HadCRUT4 | tas, tasa (Amon) | 2 | NCL | -+------------------------------+------------------------------------------------------------------------------------------------------+------+-----------------+ -| HadISST | sic (OImon), tos (Omon), ts (Amon) | 2 | NCL | -+------------------------------+------------------------------------------------------------------------------------------------------+------+-----------------+ -| LandFlux-EVAL | et, etStderr (Lmon) | 3 | Python | -+------------------------------+------------------------------------------------------------------------------------------------------+------+-----------------+ -| Landschuetzer2016 | fgco2 (Omon), spco2 (Omon), dpco2 (Omon) | 2 | Python | -+------------------------------+------------------------------------------------------------------------------------------------------+------+-----------------+ -| MODIS | cliwi, clt, clwvi, iwpStderr, lwpStderr (Amon), od550aer (aero) | 3 | NCL | -+------------------------------+------------------------------------------------------------------------------------------------------+------+-----------------+ -| MTE | gpp, gppStderr (Lmon) | 3 | Python | -+------------------------------+------------------------------------------------------------------------------------------------------+------+-----------------+ -| NCEP | hur, hus, pr, ta, tas, ua, va, wap, zg (Amon) | 2 | NCL | -| | pr, rlut, ua, va (day) | | | -+------------------------------+------------------------------------------------------------------------------------------------------+------+-----------------+ -| NIWA-BS | toz, tozStderr (Amon) | 3 | NCL | -+------------------------------+------------------------------------------------------------------------------------------------------+------+-----------------+ -| PATMOS-x | clt (Amon) | 2 | NCL | -+------------------------------+------------------------------------------------------------------------------------------------------+------+-----------------+ -| UWisc | clwvi, lwpStderr (Amon) | 3 | NCL | -+------------------------------+------------------------------------------------------------------------------------------------------+------+-----------------+ -| WOA | no3, o2, po4, si (Oyr), so, thetao (Omon) | 2 | Python | -+------------------------------+------------------------------------------------------------------------------------------------------+------+-----------------+ diff --git a/doc/sphinx/source/getting_started/install.inc b/doc/sphinx/source/getting_started/install.inc deleted file mode 100644 index d4b883fad9..0000000000 --- a/doc/sphinx/source/getting_started/install.inc +++ /dev/null @@ -1,178 +0,0 @@ -.. _installation_guide: - -********************* -Installing ESMValTool -********************* - -ESMValTool 2.0 requires a Unix(-like) operating system and Python 3.6+. - -The ESMValTool supports three different installation methods: - -* Installation through Conda package manager (see https://www.continuum.io); - -* Deployment through a Docker container (see https://www.docker.com); - -* From the source code available at https://github.com/ESMValGroup/ESMValTool. - -The next sections will detail the procedure to install ESMValTool for each of -this methods. - - -Conda installation -================== - -A conda package will be available after the release of ESMValTool 2. - - -Docker installation -=================== - -.. warning:: - Docker section to be added - - -Install from source -=================== - - - -Obtaining the source code -------------------------- - -The ESMValTool source code is available on a public GitHub repository: -https://github.com/ESMValGroup/ESMValTool - -The easiest way to obtain it is to clone the repository using git -(see https://git-scm.com/). To clone the public repository: - -.. code-block:: bash - - git clone https://github.com/ESMValGroup/ESMValTool.git - -It is also possible to work in one of the ESMValTool private repositories, e.g.: - -.. code-block:: bash - - git clone https://github.com/ESMValGroup/ESMValTool-private.git - -By default, this command will create a folder called ESMValTool containing the -source code of the tool. - -GitHub also allows to download the source code in as a tar.gz or zip file. If -you choose to use this option, download the compressed file and extract its -contents at the desired location. - - -Prerequisites -------------- - -It is recommended to use conda to manage ESMValTool dependencies. -For a minimal conda installation go to https://conda.io/miniconda.html. To -simplify the installation process, an environment definition file is provided -in the repository (``environment.yml`` in the root folder). - -.. attention:: - Some systems provides a preinstalled version of conda (e.g., via the module environment). - Several users however reported problems when installing NCL with such versions. It is - therefore preferable to use a local, fully user-controlled conda installation. - Using an older version of conda can also be a source of problems, so if you have conda - installed already, make sure it is up to date by running ``conda update -n base conda``. - -To enable the ``conda`` command, please source the appropriate configuration file -from your ``~/.bashrc`` file: - -.. code-block:: bash - - source /etc/profile.d/conda.sh - -or ``~/.cshrc``/``~/.tcshrc`` file: - -.. code-block:: bash - - source /etc/profile.d/conda.csh - -The ESMValTool conda environment file can also be used as a requirements list -for those cases in which a conda installation is not possible or advisable. -From now on, we will assume that the installation is going to be done through -conda. - -Ideally, you should create a conda environment for ESMValTool, so it is -independent from any other Python tools present in the system. - -Note that it is advisable to update conda to the latest version before -installing ESMValTool, using the command - -.. code-block:: bash - - conda update --name base conda - -To create an environment, go to the directory containing the ESMValTool source -code (called ESMValTool if you did not choose a different name) and run - -.. code-block:: bash - - conda env create --name esmvaltool --file environment.yml - -The environment is called ``esmvaltool`` by default, but it is possible to use -the option ``--name ENVIRONMENT_NAME`` to define a custom name. You can activate -the environment using the command: - -.. code-block:: bash - - conda activate esmvaltool - -It is also possible to update an existing environment from the environment -file. This may be useful when updating an older installation of ESMValTool: - -.. code-block:: bash - - conda env update --name esmvaltool --file environment.yml - -but if you run into trouble, please try creating a new environment. - -.. attention:: - From now on, we assume that the conda environment for ESMValTool is - activated. - -Software installation ---------------------- - -Once all prerequisites are fulfilled, ESMValTool can be installed by running -the following commands in the directory containing the ESMValTool source code -(called ESMValTool if you did not choose a different name): - -.. code-block:: bash - - pip install . - -If you would like to run Julia diagnostic scripts, you will also need to -`install Julia `_ and the Julia dependencies: - -.. code-block:: bash - - julia esmvaltool/install/Julia/setup.jl - -If you would like to run R diagnostic scripts, you will also need to install the R -dependencies. Install the R dependency packages: - -.. code-block:: bash - - Rscript esmvaltool/install/R/setup.R - -The next step is to check that the installation works properly. -To do this, run the tool with: - -.. code-block:: bash - - esmvaltool --help - -If everything was installed properly, ESMValTool should have printed a -help message to the console. - -For a more complete installation verification, run the automated tests and -confirm that no errors are reported: - -.. code-block:: bash - - python setup.py test --installation - diff --git a/doc/sphinx/source/getting_started/outputdata.inc b/doc/sphinx/source/getting_started/outputdata.inc deleted file mode 100644 index f73041868a..0000000000 --- a/doc/sphinx/source/getting_started/outputdata.inc +++ /dev/null @@ -1,22 +0,0 @@ -:: _outputdata: - -****** -Output -****** - -Preprocessed datasets -===================== -preproc/ - -Diagnostic output -================= -work/ - -Plots -===== -plots/ - -Log files -========= -run/ - diff --git a/doc/sphinx/source/getting_started/running.inc b/doc/sphinx/source/getting_started/running.inc deleted file mode 100644 index 79ee89c064..0000000000 --- a/doc/sphinx/source/getting_started/running.inc +++ /dev/null @@ -1,30 +0,0 @@ -:: _running: - -****************** -Running ESMValTool -****************** - -To run ESMValTool, use the command - -.. code:: bash - - esmvaltool -c /path/to/config-user.yml examples/recipe_python.yml - -This will run the example recipe_python.yml. The path to the recipe -can either be the path to a recipe file, or a path relative to the -esmvaltool/recipes directory of your installed ESMValTool. See the chapter -`User configuration file`_ for an explanation of how to create your own -config-user.yml file. - -To get help on additional commands, please use - -.. code:: bash - - esmvaltool --help - - - -Available diagnostics and metrics -================================= - -See :ref:`recipes` for a description of all available recipes. diff --git a/doc/sphinx/source/index.rst b/doc/sphinx/source/index.rst deleted file mode 100644 index 982ea45a1a..0000000000 --- a/doc/sphinx/source/index.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. ESMValTool documentation master file, created by - sphinx-quickstart on Tue Jun 2 11:34:13 2015. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Welcome to ESMValTool's documentation! -====================================== - -.. toctree:: - :maxdepth: 2 - - preface/index - getting_started/index - esmvalcore/index - esmvaldiag/index - recipes/index - codedoc2/esmvaltool - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`search` - diff --git a/doc/sphinx/source/preface/architecture.inc b/doc/sphinx/source/preface/architecture.inc deleted file mode 100644 index df5d88fe82..0000000000 --- a/doc/sphinx/source/preface/architecture.inc +++ /dev/null @@ -1,11 +0,0 @@ -************ -Architecture -************ - -:ref:`fig_schematic` shows a schematic of the ESMValTool architecture: to be written. - -.. _fig_schematic: -.. figure:: ../figures/schematic.png - :align: center - - Schematic of the system architecture. diff --git a/doc/sphinx/source/preface/core_team.inc b/doc/sphinx/source/preface/core_team.inc deleted file mode 100644 index 7a3e0ba9a4..0000000000 --- a/doc/sphinx/source/preface/core_team.inc +++ /dev/null @@ -1,52 +0,0 @@ -.. _core_team: - -************************************ -The ESMValTool core development team -************************************ - -.. _core_dev_team: - -Main contacts -============= - -A mailing list has been set up for all general and technical questions on the ESMValTool such as, for instance, -questions on installation, application or development. You are encouraged to subscribe to the ESMValTool user -mailing list by sending an email to Listserv@dlr.de with the following text: - -.. centered:: *subscribe ESMValTool-Usr* - -Core development team -===================== - -* Deutsches Zentrum für Luft- und Raumfahrt (DLR), Institut für Physik der Atmosphäre, Germany (PI) - - ESMValTool Core PI and Developer: contact for requests to use the ESMValTool and for collaboration with the - development team, access to the PRIVATE GitHub repository. - -* Alfred-Wegener-Institute Bremerhaven (AWI), Germany -* Barcelona Computing Center (BSC), Spain -* Ludwig Maximilian University of Munich, Germany -* Netherlands E-Science Center, Netherlands -* University of Reading, United Kingdom - -Contacts for specific diagnostic sets are the respective authors, as listed in the corresponding diagnostic -documentation and in the source code. - -Pull requests -============= - -This section describes the general workflow of how new diagnostics are integrated into the ESMValTool and the -responsibilities of the developer contribution to the ESMValTool. To be written for v2. - -Workflow core development team ------------------------------- - -The following workflow followed by the ESMValTool core development team takes place whenever a developer -requests integration of a diagnostics set into the *development branch*. - -To be written for v2. - -Responsibilities of ESMValTool developers ------------------------------------------ - -To be written. diff --git a/doc/sphinx/source/preface/index.rst b/doc/sphinx/source/preface/index.rst deleted file mode 100644 index 8ee438dfa7..0000000000 --- a/doc/sphinx/source/preface/index.rst +++ /dev/null @@ -1,9 +0,0 @@ -####################### -Preface -####################### - -.. include:: intro.inc -.. include:: objectives.inc -.. include:: license.inc -.. include:: architecture.inc -.. include:: core_team.inc diff --git a/doc/sphinx/source/preface/intro.inc b/doc/sphinx/source/preface/intro.inc deleted file mode 100644 index b563fd8d8c..0000000000 --- a/doc/sphinx/source/preface/intro.inc +++ /dev/null @@ -1,9 +0,0 @@ -************ -Introduction -************ - -The Earth System Model Evaluation Tool (ESMValTool) is a community-development that aims at improving diagnosing and understanding of the causes and effects of model biases and inter-model spread. The ESMValTool is open to both users and developers encouraging open exchange of diagnostic source code and evaluation results from the Coupled Model Intercomparison Project (CMIP) ensemble. This will facilitate and improve ESM evaluation beyond the state-of-the-art and aims at supporting the activities within CMIP and at individual modelling centers. We envisage running the ESMValTool routinely on the CMIP model output utilizing observations available through the Earth System Grid Federation (ESGF) in standard formats (obs4MIPs) or made available at ESGF nodes. - -The goal is to develop a benchmarking and evaluation tool that produces well-established analyses as soon as model output from CMIP simulations becomes available, e.g., at one of the central repositories of the ESGF. This is realized through standard recipes that reproduce a certain set of diagnostics and performance metrics that have demonstrated its importance in benchmarking Earth System Models (ESMs) in a paper or assessment report, such as Chapter 9 of the Intergovernmental Panel on Climate Change (IPCC) Fifth Assessment Report (AR5) (Flato et al., 2013). The expectation is that in this way a routine and systematic evaluation of model results can be made more efficient, thereby enabling scientists to focus on developing more innovative methods of analysis rather than constantly having to "reinvent the wheel". - -In parallel to standardization of model output, the ESGF also hosts observations for Model Intercomparison Projects (obs4MIPs) and reanalyses data (ana4MIPs). obs4MIPs provides open access data sets of satellite data that are comparable in terms of variables, temporal and spatial frequency, and periods to CMIP model output (Taylor et al., 2012). The ESMValTool utilizes these observations and reanalyses from ana4MIPs plus additionally available observations in order to evaluate the models performance. In many diagnostics and metrics, more than one observational data set or meteorological reanalysis is used to assess uncertainties in observations. diff --git a/doc/sphinx/source/preface/license.inc b/doc/sphinx/source/preface/license.inc deleted file mode 100644 index fe053a10fb..0000000000 --- a/doc/sphinx/source/preface/license.inc +++ /dev/null @@ -1,19 +0,0 @@ -******* -License -******* - -The ESMValTool is released under the Apache License, version 2.0 and citation -of the ESMValTool paper ("Software Documentation Paper") is kindly requested -upon use alongside with the software doi (to be added for v2) -and version number: - -* Righi et al. to be added - -Besides the above citation, users are kindly asked to register any journal -articles (or other scientific documents) that use the software at the -ESMValTool webpage (http://www.esmvaltool.org/). Citing the Software -Documentation Paper and registering your paper(s) will serve to document the -scientific impact of the Software, which is of vital importance for securing -future funding. You should consider this an obligation if you have taken -advantage of the ESMValTool, which represents the end product of considerable -effort by the development team. diff --git a/doc/sphinx/source/preface/objectives.inc b/doc/sphinx/source/preface/objectives.inc deleted file mode 100644 index 531d5d6654..0000000000 --- a/doc/sphinx/source/preface/objectives.inc +++ /dev/null @@ -1,6 +0,0 @@ -*********************** -Objectives and approach -*********************** - -The main idea of the ESMValTool is to provide a broad suite of diagnostics which can be performed easily when new model simulations are run. The suite of diagnostics needs to be broad enough to reflect the diversity and complexity of Earth System Models, but must also be robust enough to be run routinely or semi-operationally. -In order the address these challenging objectives the ESMValTool is conceived as a framework which allows community contributions to be bound into a coherent framework. diff --git a/doc/sphinx/source/recipes/figures/Index_NAO.png b/doc/sphinx/source/recipes/figures/Index_NAO.png deleted file mode 100644 index f5ed01aa9a..0000000000 Binary files a/doc/sphinx/source/recipes/figures/Index_NAO.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/capacity_factor/capacity_factor_IPSL-CM5A-LR_1980-2005.png b/doc/sphinx/source/recipes/figures/capacity_factor/capacity_factor_IPSL-CM5A-LR_1980-2005.png deleted file mode 100644 index f65013283b..0000000000 Binary files a/doc/sphinx/source/recipes/figures/capacity_factor/capacity_factor_IPSL-CM5A-LR_1980-2005.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/clouds/cloud_lweffect.png b/doc/sphinx/source/recipes/figures/clouds/cloud_lweffect.png deleted file mode 100644 index 74bb43dab2..0000000000 Binary files a/doc/sphinx/source/recipes/figures/clouds/cloud_lweffect.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/clouds/cloud_neteffect.png b/doc/sphinx/source/recipes/figures/clouds/cloud_neteffect.png deleted file mode 100644 index 79f4696245..0000000000 Binary files a/doc/sphinx/source/recipes/figures/clouds/cloud_neteffect.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/clouds/cloud_sweffect.png b/doc/sphinx/source/recipes/figures/clouds/cloud_sweffect.png deleted file mode 100644 index 52b00c8c45..0000000000 Binary files a/doc/sphinx/source/recipes/figures/clouds/cloud_sweffect.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/clouds/cloud_var_multi.png b/doc/sphinx/source/recipes/figures/clouds/cloud_var_multi.png deleted file mode 100644 index 54a85593ae..0000000000 Binary files a/doc/sphinx/source/recipes/figures/clouds/cloud_var_multi.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/clouds/liq_h2o_path_multi.png b/doc/sphinx/source/recipes/figures/clouds/liq_h2o_path_multi.png deleted file mode 100644 index 57052e850d..0000000000 Binary files a/doc/sphinx/source/recipes/figures/clouds/liq_h2o_path_multi.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/clouds/liq_h2o_taylor.png b/doc/sphinx/source/recipes/figures/clouds/liq_h2o_taylor.png deleted file mode 100644 index 7e1e27ab1b..0000000000 Binary files a/doc/sphinx/source/recipes/figures/clouds/liq_h2o_taylor.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/combined_climate_extreme_index/t90p_IPSL-CM5A-LR_rcp85_2020_2040.png b/doc/sphinx/source/recipes/figures/combined_climate_extreme_index/t90p_IPSL-CM5A-LR_rcp85_2020_2040.png deleted file mode 100644 index cb48e377ec..0000000000 Binary files a/doc/sphinx/source/recipes/figures/combined_climate_extreme_index/t90p_IPSL-CM5A-LR_rcp85_2020_2040.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/crem/crem_error_metric.png b/doc/sphinx/source/recipes/figures/crem/crem_error_metric.png deleted file mode 100644 index 98bfb8e6b2..0000000000 Binary files a/doc/sphinx/source/recipes/figures/crem/crem_error_metric.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/cvdp/nam.prreg.ann.png b/doc/sphinx/source/recipes/figures/cvdp/nam.prreg.ann.png deleted file mode 100755 index 70e788bec6..0000000000 Binary files a/doc/sphinx/source/recipes/figures/cvdp/nam.prreg.ann.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/diurnal_temp_index/rcp85_diurnal.png b/doc/sphinx/source/recipes/figures/diurnal_temp_index/rcp85_diurnal.png deleted file mode 100644 index 0747de51b0..0000000000 Binary files a/doc/sphinx/source/recipes/figures/diurnal_temp_index/rcp85_diurnal.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/ensclus/ensclus.png b/doc/sphinx/source/recipes/figures/ensclus/ensclus.png deleted file mode 100644 index 9e721eeea7..0000000000 Binary files a/doc/sphinx/source/recipes/figures/ensclus/ensclus.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/extreme_events/cdd_timeseries.png b/doc/sphinx/source/recipes/figures/extreme_events/cdd_timeseries.png deleted file mode 100644 index e67e0f0180..0000000000 Binary files a/doc/sphinx/source/recipes/figures/extreme_events/cdd_timeseries.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/extreme_events/gleckler.png b/doc/sphinx/source/recipes/figures/extreme_events/gleckler.png deleted file mode 100644 index 9120303ea0..0000000000 Binary files a/doc/sphinx/source/recipes/figures/extreme_events/gleckler.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/heatwaves/tasmax_extreme_spell_durationsummer_IPSL-CM5A-LR_rcp85_2020_2040.png b/doc/sphinx/source/recipes/figures/heatwaves/tasmax_extreme_spell_durationsummer_IPSL-CM5A-LR_rcp85_2020_2040.png deleted file mode 100644 index 04c843fc22..0000000000 Binary files a/doc/sphinx/source/recipes/figures/heatwaves/tasmax_extreme_spell_durationsummer_IPSL-CM5A-LR_rcp85_2020_2040.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/hyint/hyint_maps.png b/doc/sphinx/source/recipes/figures/hyint/hyint_maps.png deleted file mode 100644 index 7d2075514f..0000000000 Binary files a/doc/sphinx/source/recipes/figures/hyint/hyint_maps.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/hyint/hyint_timeseries.png b/doc/sphinx/source/recipes/figures/hyint/hyint_timeseries.png deleted file mode 100644 index 549678d667..0000000000 Binary files a/doc/sphinx/source/recipes/figures/hyint/hyint_timeseries.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/hyint/hyint_trends.png b/doc/sphinx/source/recipes/figures/hyint/hyint_trends.png deleted file mode 100644 index 018c0bc903..0000000000 Binary files a/doc/sphinx/source/recipes/figures/hyint/hyint_trends.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/landcover/area_treeFrac.png b/doc/sphinx/source/recipes/figures/landcover/area_treeFrac.png deleted file mode 100644 index e77017e48b..0000000000 Binary files a/doc/sphinx/source/recipes/figures/landcover/area_treeFrac.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/landcover/bias_CMIP5_MPI-ESM-LR_rcp85_r1i1p1.png b/doc/sphinx/source/recipes/figures/landcover/bias_CMIP5_MPI-ESM-LR_rcp85_r1i1p1.png deleted file mode 100644 index 16fb12cea7..0000000000 Binary files a/doc/sphinx/source/recipes/figures/landcover/bias_CMIP5_MPI-ESM-LR_rcp85_r1i1p1.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/landcover/frac_grassFrac.png b/doc/sphinx/source/recipes/figures/landcover/frac_grassFrac.png deleted file mode 100644 index 5abb1a74ee..0000000000 Binary files a/doc/sphinx/source/recipes/figures/landcover/frac_grassFrac.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/miles/miles_block.png b/doc/sphinx/source/recipes/figures/miles/miles_block.png deleted file mode 100644 index 713e1a7d1f..0000000000 Binary files a/doc/sphinx/source/recipes/figures/miles/miles_block.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/miles/miles_eof1.png b/doc/sphinx/source/recipes/figures/miles/miles_eof1.png deleted file mode 100644 index a9184599d9..0000000000 Binary files a/doc/sphinx/source/recipes/figures/miles/miles_eof1.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/modes_of_variability/DJF-psl_observed_regimes.png b/doc/sphinx/source/recipes/figures/modes_of_variability/DJF-psl_observed_regimes.png deleted file mode 100644 index fb2abe6f5b..0000000000 Binary files a/doc/sphinx/source/recipes/figures/modes_of_variability/DJF-psl_observed_regimes.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/multimodel_products/tas_JUN_multimodel-anomaly_2006_2099_1961_1990.png b/doc/sphinx/source/recipes/figures/multimodel_products/tas_JUN_multimodel-anomaly_2006_2099_1961_1990.png deleted file mode 100644 index 9ca805dd9b..0000000000 Binary files a/doc/sphinx/source/recipes/figures/multimodel_products/tas_JUN_multimodel-anomaly_2006_2099_1961_1990.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/ocean/amoc_fig_1.png b/doc/sphinx/source/recipes/figures/ocean/amoc_fig_1.png deleted file mode 100644 index 484ba66371..0000000000 Binary files a/doc/sphinx/source/recipes/figures/ocean/amoc_fig_1.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/ocean/ocean_quad_plot1.png b/doc/sphinx/source/recipes/figures/ocean/ocean_quad_plot1.png deleted file mode 100644 index 7e270e5a52..0000000000 Binary files a/doc/sphinx/source/recipes/figures/ocean/ocean_quad_plot1.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/ocean/ocean_sea_ice1.png b/doc/sphinx/source/recipes/figures/ocean/ocean_sea_ice1.png deleted file mode 100644 index 095e707705..0000000000 Binary files a/doc/sphinx/source/recipes/figures/ocean/ocean_sea_ice1.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/ocean/stream_function1.png b/doc/sphinx/source/recipes/figures/ocean/stream_function1.png deleted file mode 100644 index 7213bfa6e4..0000000000 Binary files a/doc/sphinx/source/recipes/figures/ocean/stream_function1.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/ocean/stream_function2.png b/doc/sphinx/source/recipes/figures/ocean/stream_function2.png deleted file mode 100644 index 3debf2f537..0000000000 Binary files a/doc/sphinx/source/recipes/figures/ocean/stream_function2.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/perfmetrics/perfmetrics_fig_1.png b/doc/sphinx/source/recipes/figures/perfmetrics/perfmetrics_fig_1.png deleted file mode 100644 index 87a83561f9..0000000000 Binary files a/doc/sphinx/source/recipes/figures/perfmetrics/perfmetrics_fig_1.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/perfmetrics/perfmetrics_fig_2.png b/doc/sphinx/source/recipes/figures/perfmetrics/perfmetrics_fig_2.png deleted file mode 100644 index a531e23804..0000000000 Binary files a/doc/sphinx/source/recipes/figures/perfmetrics/perfmetrics_fig_2.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/perfmetrics/perfmetrics_fig_3.png b/doc/sphinx/source/recipes/figures/perfmetrics/perfmetrics_fig_3.png deleted file mode 100644 index 24ede914b3..0000000000 Binary files a/doc/sphinx/source/recipes/figures/perfmetrics/perfmetrics_fig_3.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/perfmetrics/perfmetrics_fig_4.png b/doc/sphinx/source/recipes/figures/perfmetrics/perfmetrics_fig_4.png deleted file mode 100644 index 26b563d158..0000000000 Binary files a/doc/sphinx/source/recipes/figures/perfmetrics/perfmetrics_fig_4.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/perfmetrics/perfmetrics_fig_5.png b/doc/sphinx/source/recipes/figures/perfmetrics/perfmetrics_fig_5.png deleted file mode 100644 index 353f35e507..0000000000 Binary files a/doc/sphinx/source/recipes/figures/perfmetrics/perfmetrics_fig_5.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/runoff_et/MPI-ESM-LR_historical_r1i1p1_bias-plot_mrro.png b/doc/sphinx/source/recipes/figures/runoff_et/MPI-ESM-LR_historical_r1i1p1_bias-plot_mrro.png deleted file mode 100644 index 46c7cfcf78..0000000000 Binary files a/doc/sphinx/source/recipes/figures/runoff_et/MPI-ESM-LR_historical_r1i1p1_bias-plot_mrro.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/runoff_et/MPI-ESM-LR_historical_r1i1p1_rocoef-vs-relprbias.png b/doc/sphinx/source/recipes/figures/runoff_et/MPI-ESM-LR_historical_r1i1p1_rocoef-vs-relprbias.png deleted file mode 100644 index 57ba1ed185..0000000000 Binary files a/doc/sphinx/source/recipes/figures/runoff_et/MPI-ESM-LR_historical_r1i1p1_rocoef-vs-relprbias.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/runoff_et/catchments.png b/doc/sphinx/source/recipes/figures/runoff_et/catchments.png deleted file mode 100644 index f95c18d988..0000000000 Binary files a/doc/sphinx/source/recipes/figures/runoff_et/catchments.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/smpi/reichlerkim08bams_smpi.png b/doc/sphinx/source/recipes/figures/smpi/reichlerkim08bams_smpi.png deleted file mode 100644 index e98e69c2e7..0000000000 Binary files a/doc/sphinx/source/recipes/figures/smpi/reichlerkim08bams_smpi.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/spei/histogram_spei.png b/doc/sphinx/source/recipes/figures/spei/histogram_spei.png deleted file mode 100644 index 9aed50720f..0000000000 Binary files a/doc/sphinx/source/recipes/figures/spei/histogram_spei.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/spei/histogram_spi.png b/doc/sphinx/source/recipes/figures/spei/histogram_spi.png deleted file mode 100644 index 94cd9ea5df..0000000000 Binary files a/doc/sphinx/source/recipes/figures/spei/histogram_spi.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/thermodyn_diagtool/CanESM2_2458_lec_diagram.pdf b/doc/sphinx/source/recipes/figures/thermodyn_diagtool/CanESM2_2458_lec_diagram.pdf deleted file mode 100644 index b364d37bdd..0000000000 Binary files a/doc/sphinx/source/recipes/figures/thermodyn_diagtool/CanESM2_2458_lec_diagram.pdf and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/thermodyn_diagtool/CanESM2_wmb_transp.png b/doc/sphinx/source/recipes/figures/thermodyn_diagtool/CanESM2_wmb_transp.png deleted file mode 100644 index 9a2288c73b..0000000000 Binary files a/doc/sphinx/source/recipes/figures/thermodyn_diagtool/CanESM2_wmb_transp.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/thermodyn_diagtool/IPSL-CM5A-MR_energy_climap.png b/doc/sphinx/source/recipes/figures/thermodyn_diagtool/IPSL-CM5A-MR_energy_climap.png deleted file mode 100644 index e816d727ca..0000000000 Binary files a/doc/sphinx/source/recipes/figures/thermodyn_diagtool/IPSL-CM5A-MR_energy_climap.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/thermodyn_diagtool/meridional_transp.png b/doc/sphinx/source/recipes/figures/thermodyn_diagtool/meridional_transp.png deleted file mode 100644 index 7397d070c4..0000000000 Binary files a/doc/sphinx/source/recipes/figures/thermodyn_diagtool/meridional_transp.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/toymodel/synthetic_CMIP5_IPSL-CM5A-LR_day_historical_r1i1p1_T2M_tasmax_1999-2000.jpg b/doc/sphinx/source/recipes/figures/toymodel/synthetic_CMIP5_IPSL-CM5A-LR_day_historical_r1i1p1_T2M_tasmax_1999-2000.jpg deleted file mode 100644 index 17ad159aa8..0000000000 Binary files a/doc/sphinx/source/recipes/figures/toymodel/synthetic_CMIP5_IPSL-CM5A-LR_day_historical_r1i1p1_T2M_tasmax_1999-2000.jpg and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/zmnam/zmnam_reg.png b/doc/sphinx/source/recipes/figures/zmnam/zmnam_reg.png deleted file mode 100644 index 2251dcd883..0000000000 Binary files a/doc/sphinx/source/recipes/figures/zmnam/zmnam_reg.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/figures/zmnam/zmnam_ts.png b/doc/sphinx/source/recipes/figures/zmnam/zmnam_ts.png deleted file mode 100644 index 2997a5a4d7..0000000000 Binary files a/doc/sphinx/source/recipes/figures/zmnam/zmnam_ts.png and /dev/null differ diff --git a/doc/sphinx/source/recipes/index.rst b/doc/sphinx/source/recipes/index.rst deleted file mode 100644 index e40732e61a..0000000000 --- a/doc/sphinx/source/recipes/index.rst +++ /dev/null @@ -1,36 +0,0 @@ -.. _recipes: - -Recipes -------- - -.. toctree:: - :maxdepth: 1 - - recipe_capacity_factor - recipe_clouds - recipe_combined_climate_extreme_index - recipe_combined_indices - recipe_consecdrydays - recipe_crem - recipe_cvdp - recipe_diurnal_temperature_index - recipe_ensclus - recipe_extreme_events - recipe_flato13ipcc - recipe_heatwaves_coldwaves - recipe_hyint - recipe_landcover - recipe_miles - recipe_modes_of_variability - recipe_multimodel_products - recipe_oceans - recipe_perfmetrics - recipe_quantilebias - recipe_runoff_et - recipe_rainfarm - recipe_shapeselect - recipe_smpi - recipe_spei - recipe_toymodel - recipe_thermodyn_diagtool - recipe_zmnam diff --git a/doc/sphinx/source/recipes/recipe_capacity_factor.rst b/doc/sphinx/source/recipes/recipe_capacity_factor.rst deleted file mode 100644 index 9ad4b667a6..0000000000 --- a/doc/sphinx/source/recipes/recipe_capacity_factor.rst +++ /dev/null @@ -1,67 +0,0 @@ -.. _yml_capacity_factor: - -Capacity factor of wind power: Ratio of average estimated power to theoretical maximum power -============================================================================================ - -Overview --------- - -The goal of this diagnostic is to compute the wind capacity factor, taking as input the daily instantaneous surface wind speed, which is then extrapolated to obtain the wind speed at a height of 100 m as described in Lledó (2017). - -The capacity factor is a normalized indicator of the suitability of wind speed conditions to produce electricity, irrespective of the size and number of installed turbines. This indicator is provided for three different classes of wind turbines (IEC, 2005) that are designed specifically for low, medium and high wind speed conditions. - -The user can select the region, temporal range and season of interest. - -The output of the recipe is a netcdf file containing the capacity factor for each of the three turbine classes. -. - -Available recipes and diagnostics ---------------------------------- - -Recipes are stored in recipes/ - -* recipe_capacity_factor.yml - -Diagnostics are stored in diag_scripts/magic_bsc/ - -* capacity_factor.R: calculates the capacity factor for the three turbine classes. -* PC.r: calculates the power curves for the three turbine classes. - - -User settings -------------- - -User setting files are stored in recipes/ - -#. recipe_capacity_factor.yml - - *Required settings for script* - - * power_curves: (should not be changed) - -Variables ---------- - -* sfcWind (atmos, daily, longitude, latitude, time) - - -Observations and reformat scripts ---------------------------------- - -*None* - -References ----------- - -* IEC. (2005). International Standard IEC 61400-1, third edition, International Electrotechnical Commission. https://webstore.iec.ch/preview/info_iec61400-1%7Bed3.0%7Den.pdf - -* Lledó, L. (2017). Computing capacity factor. Technical note BSC-ESS-2017-001, Barcelona Supercomputing Center. Available online at https://earth.bsc.es/wiki/lib/exe/fetch.php?media=library:external:bsc-ess-2017-001-c4e_capacity_factor.pdf [last accessed 11 October 2018] - -Example plots -------------- - -.. _fig_capfactor1: -.. figure:: /recipes/figures/capacity_factor/capacity_factor_IPSL-CM5A-LR_1980-2005.png - :align: center - :width: 14cm - diff --git a/doc/sphinx/source/recipes/recipe_clouds.rst b/doc/sphinx/source/recipes/recipe_clouds.rst deleted file mode 100644 index ee4e1bc182..0000000000 --- a/doc/sphinx/source/recipes/recipe_clouds.rst +++ /dev/null @@ -1,317 +0,0 @@ -Clouds -====== - -Overview --------- - -The recipe recipe_lauer13jclim.yml computes the climatology and interannual -variability of climate relevant cloud variables such as cloud radiative forcing -(CRE), liquid water path (lwp), cloud amount (clt), and total precipitation (pr) -reproducing some of the evaluation results of Lauer and Hamilton (2013). The -recipe includes a comparison of the geographical distribution of multi-year -average cloud parameters from individual models and the multi-model mean with -satellite observations. Taylor diagrams are generated that show the multi-year -annual or seasonal average performance of individual models and the multi-model -mean in reproducing satellite observations. The diagnostic also facilitates the -assessment of the bias of the multi-model mean and zonal averages of individual -models compared with satellite observations. Interannual variability is -estimated as the relative temporal standard deviation from multi-year timeseries -of data with the temporal standard deviations calculated from monthly anomalies -after subtracting the climatological mean seasonal cycle. - - -Available recipes and diagnostics ---------------------------------- - -Recipes are stored in recipes/ - - * recipe_lauer13jclim.yml - -Diagnostics are stored in diag_scripts/clouds/ - - * clouds.ncl: global maps of (multi-year) annual means including multi-model - mean - * clouds_bias.ncl: global maps of the multi-model mean and the multi-model - mean bias - * clouds_interannual: global maps of the interannual variability - * clouds_isccp: global maps of multi-model mean minus observations + zonal - averages of individual models, multi-model mean and observations - * clouds_taylor.ncl: taylor diagrams - - -User settings in recipe ------------------------ - -#. Script clouds.ncl - - *Required settings (scripts)* - - none - - *Optional settings (scripts)* - - * embracesetup: true = 2 plots per line, false = 4 plots per line (default) - * explicit_cn_levels: explicit contour levels (array) - * extralegend: plot legend(s) to extra file(s) - * filename_add: optionally add this string to plot filesnames - * panel_labels: label individual panels (true, false) - * PanelTop: manual override for "@gnsPanelTop" used by panel plot(s) - * projection: map projection for plotting (default = - "CylindricalEquidistant") - * showdiff: calculate and plot differences model - reference - (default = false) - * rel_diff: if showdiff = true, then plot relative differences (%) - (default = False) - * ref_diff_min: lower cutoff value in case of calculating relative - differences (in units of input variable) - * region: show only selected geographic region given as latmin, latmax, - lonmin, lonmax - * timemean: time averaging - "seasonal" = DJF, MAM, JJA, SON), - "annual" = annual mean - * treat_var_as_error: treat variable as error when averaging (true, false); - true: avg = sqrt(mean(var*var)), false: avg = mean(var) - - *Required settings (variables)* - - none - - * Optional settings (variables) - - * long_name: variable description - * reference_dataset: reference dataset; REQUIRED when calculating - differences (showdiff = True) - * units: variable units (for labeling plot only) - - *Color tables* - - * variable "lwp": diag_scripts/shared/plot/rgb/qcm3.rgb - -#. Script clouds_bias.ncl - - *Required settings (scripts)* - - none - - *Optional settings (scripts)* - - * plot_abs_diff: additionally also plot absolute differences (true, false) - * plot_rel_diff: additionally also plot relative differences (true, false) - * projection: map projection, e.g., Mollweide, Mercator - * timemean: time averaging, i.e. "seasonalclim" (DJF, MAM, JJA, SON), - "annualclim" (annual mean) - - * Required settings (variables)* - - * reference_dataset: name of reference datatset - - *Optional settings (variables)* - - * long_name: description of variable - - *Color tables* - - * variable "tas": diag_scripts/shared/plot/rgb/ipcc-tas.rgb, - diag_scripts/shared/plot/rgb/ipcc-tas-delta.rgb - * variable "pr-mmday": diag_scripts/shared/plots/rgb/ipcc-precip.rgb, - diag_scripts/shared/plot/rgb/ipcc-precip-delta.rgb - -#. Script clouds_interannual.ncl - - *Required settings (scripts)* - - none - - *Optional settings (scripts)* - - * colormap: e.g., WhiteBlueGreenYellowRed, rainbow - * explicit_cn_levels: use these contour levels for plotting - * extrafiles: write plots for individual models to separate files - (true, false) - * projection: map projection, e.g., Mollweide, Mercator - - *Required settings (variables)* - - none - - *Optional settings (variables)* - - * long_name: description of variable - * reference_dataset: name of reference datatset - - *Color tables* - - * variable "lwp": diag_scripts/shared/plots/rgb/qcm3.rgb - -#. Script clouds_ipcc.ncl - - *Required settings (scripts)* - - none - - *Optional settings (scripts)* - - * explicit_cn_levels: contour levels - * mask_ts_sea_ice: true = mask T < 272 K as sea ice (only for variable "ts"); - false = no additional grid cells masked for variable "ts" - * projection: map projection, e.g., Mollweide, Mercator - * styleset: style set for zonal mean plot ("CMIP5", "DEFAULT") - * timemean: time averaging, i.e. "seasonalclim" (DJF, MAM, JJA, SON), - "annualclim" (annual mean) - * valid_fraction: used for creating sea ice mask (mask_ts_sea_ice = true): - fraction of valid time steps required to mask grid cell as valid data - - *Required settings (variables)* - - * reference_dataset: name of reference data set - - *Optional settings (variables)* - - * long_name: description of variable - * units: variable units - - *Color tables* - - * variables "pr", "pr-mmday": diag_scripts/shared/plot/rgb/ipcc-precip-delta.rgb - -#. Script clouds_taylor.ncl - - *Required settings (scripts)* - - none - - *Optional settings (scripts)* - - * embracelegend: false (default) = include legend in plot, max. 2 columns - with dataset names in legend; true = write extra file with legend, max. 7 - dataset names per column in legend, alternative observational dataset(s) - will be plotted as a red star and labeled "altern. ref. dataset" in legend - (only if dataset is of class "OBS") - * estimate_obs_uncertainty: true = estimate observational uncertainties - from mean values (assuming fractions of obs. RMSE from documentation of - the obs data); only available for "CERES-EBAF", "MODIS", "MODIS-L3"; - false = do not estimate obs. uncertainties from mean values - * filename_add: legacy feature: arbitrary string to be added to all - filenames of plots and netcdf output produced (default = "") - * mask_ts_sea_ice: true = mask T < 272 K as sea ice (only for variable "ts"); - false = no additional grid cells masked for variable "ts" - * styleset: "CMIP5", "DEFAULT" (if not set, clouds_taylor.ncl will create a - color table and symbols for plotting) - * timemean: time averaging; annualclim (default) = 1 plot annual mean; - seasonalclim = 4 plots (DJF, MAM, JJA, SON) - * valid_fraction: used for creating sea ice mask (mask_ts_sea_ice = true): - fraction of valid time steps required to mask grid cell as valid data - - *Required settings (variables)* - - * reference_dataset: name of reference data set - - *Optional settings (variables)* - - none - - -Variables ---------- - -* clwvi (atmos, monthly mean, longitude latitude time) -* clivi (atmos, monthly mean, longitude latitude time) -* clt (atmos, monthly mean, longitude latitude time) -* pr (atmos, monthly mean, longitude latitude time) -* rlut, rlutcs (atmos, monthly mean, longitude latitude time) -* rsut, rsutcs (atmos, monthly mean, longitude latitude time) - - -Observations and reformat scripts ---------------------------------- - -*Note: (1) obs4mips data can be used directly without any preprocessing; -(2) see headers of reformat scripts for non-obs4mips data for download -instructions.* - -* CERES-EBAF (obs4mips) - CERES TOA radiation fluxes (used for calculation of - cloud forcing) -* GPCP-SG (obs4mips) - Global Precipitation Climatology Project total - precipitation -* MODIS (obs4mips) - MODIS total cloud fraction -* UWisc - University of Wisconsin-Madison liquid water path climatology, based - on satellite observbations from TMI, SSM/I, and AMSR-E, reference: O'Dell et - al. (2008), J. Clim. - - *Reformat script:* reformat_scripts/obs/reformat_obs_UWisc.ncl - -References ----------- - -* Flato, G., J. Marotzke, B. Abiodun, P. Braconnot, S.C. Chou, W. Collins, P. - Cox, F. Driouech, S. Emori, V. Eyring, C. Forest, P. Gleckler, E. Guilyardi, - C. Jakob, V. Kattsov, C. Reason and M. Rummukainen, 2013: Evaluation of - Climate Models. In: Climate Change 2013: The Physical Science Basis. - Contribution of Working Group I to the Fifth Assessment Report of the - Intergovernmental Panel on Climate Change [Stocker, T.F., D. Qin, G.-K. - Plattner, M. Tignor, S.K. Allen, J. Boschung, A. Nauels, Y. Xia, V. Bex and - P.M. Midgley (eds.)]. Cambridge University Press, Cambridge, United Kingdom - and New York, NY, USA. - -* Lauer A., and K. Hamilton (2013), Simulating clouds with global climate - models: A comparison of CMIP5 results with CMIP3 and satellite data, J. Clim., - 26, 3823-3845, doi: 10.1175/JCLI-D-12-00451.1. - -* O’Dell, C.W., F.J. Wentz, and R. Bennartz (2008), Cloud liquid water path - from satellite-based passive microwave observations: A new climatology over - the global oceans, J. Clim., 21, 1721-1739, doi:10.1175/2007JCLI1958.1. - -* Pincus, R., S. Platnick, S.A. Ackerman, R.S. Hemler, Robert J. Patrick - Hofmann (2012), Reconciling simulated and observed views of clouds: MODIS, - ISCCP, and the limits of instrument simulators. J. Climate, 25, 4699-4720, - doi: 10.1175/JCLI-D-11-00267.1. - - -Example plots -------------- - -.. _fig_cloud_1: -.. figure:: /recipes/figures/clouds/liq_h2o_path_multi.png - :align: center - - The 20-yr average LWP (1986-2005) from the CMIP5 historical model runs and - the multi-model mean in comparison with the UWisc satellite climatology - (1988-2007) based on SSM/I, TMI, and AMSR-E (O'Dell et al. 2008). - -.. _fig_cloud_2: -.. figure:: /recipes/figures/clouds/liq_h2o_taylor.png - :align: center - :width: 7cm - - Taylor diagram showing the 20-yr annual average performance of CMIP5 models - for total cloud fraction as compared to MODIS satellite observations. - -.. _fig_cloud_3: -.. figure:: /recipes/figures/clouds/cloud_sweffect.png - :align: center - :width: 9cm - -.. figure:: /recipes/figures/clouds/cloud_lweffect.png - :align: center - :width: 9cm - -.. figure:: /recipes/figures/clouds/cloud_neteffect.png - :align: center - :width: 9cm - - 20-year average (1986-2005) annual mean cloud radiative effects of CMIP5 - models against the CERES EBAF (2001–2012). Top row shows the shortwave - effect; middle row the longwave effect, and bottom row the net effect. - Multi-model mean biases against CERES EBAF are shown on the left, whereas the - right panels show zonal averages from CERES EBAF (thick black), the - individual CMIP5 models (thin gray lines) and the multi-model mean (thick - red line). Similar to Figure 9.5 of Flato et al. (2013). - -.. _fig_cloud_4: -.. figure:: /recipes/figures/clouds/cloud_var_multi.png - :align: center - - Interannual variability of modeled and observed (GPCP) precipitation rates - estimated as relative temporal standard deviation from 20 years (1986-2005) - of data. The temporal standard devitions are calculated from monthly - anomalies after subtracting the climatological mean seasonal cycle. - diff --git a/doc/sphinx/source/recipes/recipe_combined_climate_extreme_index.rst b/doc/sphinx/source/recipes/recipe_combined_climate_extreme_index.rst deleted file mode 100644 index 4186538669..0000000000 --- a/doc/sphinx/source/recipes/recipe_combined_climate_extreme_index.rst +++ /dev/null @@ -1,92 +0,0 @@ -.. _recipes_extreme_index: - -Combined Climate Extreme Index -==================================================== - -Overview --------- - -The goal of this diagnostic is to compute time series of a number of extreme events: heatwave, coldwave, heavy precipitation, drought and high wind. Then, the user can combine these different components (with or without weights). The result is an index similar to the Climate Extremes Index (CEI; Karl et al., 1996), the modified CEI (mCEI; Gleason et al., 2008) or the Actuaries Climate Index (ACI; American Academy of Actuaries, 2018). The output consists of a netcdf file containing the area-weighted and multi-model multi-metric index. This recipe can be applied to data with any temporal resolution, and the running average is computed based on the user-defined window length (e.g. a window length of 5 would compute the 5-day running mean when applied to monthly data, or 5-month running mean when applied to monthly data). - -In recipe_extreme_index.yml, after defining the area and reference and projection period, the weigths for each metric is selected. The options are -* weight_t90p the weight of the number of days when the maximum temperature exceeds the 90th percentile, -* weight_t10p the weight of the number of days when the minimum temperature falls below the 10th percentile, -* weight_Wx the weight of the number of days when wind power (third power of wind speed) exceeds the 90th percentile, -* weight_cdd the weight of the maximum length of a dry spell, defined as the maximum number of consecutive days when the daily precipitation is lower than 1 mm, and -* weight_rx5day the weight of the maximum precipitation accumulated during 5 consecutive days. - -Available recipes and diagnostics ------------------------------------ - -Recipes are stored in recipes/ - -* recipe_extreme_index.yml - -Diagnostics are stored in diag_scripts/magic_bsc/ - -* extreme_index.r - - -User settings -------------- - -User setting files are stored in recipes/ - -#. recipe_extreme_index.yml - - *Required settings for script* - - * weight_t90p: 0.2 (from 0 to 1, the total sum of the weight should be 1) - * weight_t10p: 0.2 (from 0 to 1, the total sum of the weight should be 1) - * weight_Wx: 0.2 (from 0 to 1, the total sum of the weight should be 1) - * weight_rx5day: 0.2 (from 0 to 1, the total sum of the weight should be 1) - * weight_cdd: 0.2 (from 0 to 1, the total sum of the weight should be 1) - * running_mean: 5 (depends on the length of the future projection period selected, but recommended not greater than 11) - -Variables ---------- - -* tasmax (atmos, daily, longitude, latitude, time) -* tasmin (atmos, daily, longitude, latitude, time) -* sfcWind (atmos, daily, longitude, latitude, time) -* pr (atmos, daily, longitude, latitude, time) - - -Observations and reformat scripts ---------------------------------- - -*None* - -References ----------- - -* Alexander L.V. and Coauthors (2006). Global observed changes in daily climate extremes of temperature and precipitation. J. Geophys. Res., 111, D05109. https://doi.org/10.1029/2005JD006290 - -* American Academy of Actuaries, Canadian Institute of Actuaries, Casualty Actuarial Society and Society of Actuaries. Actuaries Climate Index. http://actuariesclimateindex.org (2018-10-06). - -* Donat, M., and Coauthors (2013). Updated analyses of temperature and precipitation extreme indices since the beginning of the twentieth century: The HadEX2 dataset. J. Geophys. Res., 118, 2098–2118, https://doi.org/10.1002/jgrd.50150. - -* Fouillet, A., Rey, G., Laurent, F., Pavillon, G. Bellec, S., Guihenneuc-Jouyaux, C., Clavel J., Jougla, E. and Hémon, D. (2006) Excess mortality related to the August 2003 heat wave in France. Int. Arch. Occup. Environ. Health, 80, 16–24. https://doi.org/10.1007/s00420-006-0089-4 - -* Gleason, K.L., J.H. Lawrimore, D.H. Levinson, T.R. Karl, and D.J. Karoly (2008). A Revised U.S. Climate Extremes Index. J. Climate, 21, 2124-2137 https://doi.org/10.1175/2007JCLI1883.1 - -* Meehl, G. A., and Coauthors (2000). An introduction to trends inextreme weather and climate events: Observations, socio-economic impacts, terrestrial ecological impacts, and model projections. Bull. Amer. Meteor. Soc., 81, 413–416. `doi: 10.1175/1520-0477(2000)081<0413:AITTIE>2.3.CO;2 `_ - -* Whitman, S., G. Good, E. R. Donoghue, N. Benbow, W. Y. Shou and S. X. Mou (1997). Mortality in Chicago attributed to the July 1995 heat wave. Amer. J. Public Health, 87, 1515–1518. https://doi.org/10.2105/AJPH.87.9.1515 - -* Zhang, Y., M. Nitschke, and P. Bi (2013). Risk factors for direct heat-related hospitalization during the 2009 Adelaide heat-wave: A case crossover study. Sci. Total Environ., 442, 1–5. https://doi.org/10.1016/j.scitotenv.2012.10.042 - -* Zhang, X. , Alexander, L. , Hegerl, G. C., Jones, P. , Tank, A. K., Peterson, T. C., Trewin, B. and Zwiers, F. W. (2011). Indices for monitoring changes in extremes based on daily temperature and precipitation data. WIREs Clim Change, 2: 851-870. doi:10.1002/wcc.147. https://doi.org/10.1002/wcc.147 - - - -Example plots -------------- - -.. _fig_combinedindices1: -.. figure:: /recipes/figures/combined_climate_extreme_index/t90p_IPSL-CM5A-LR_rcp85_2020_2040.png - :align: center - :width: 14cm - - - diff --git a/doc/sphinx/source/recipes/recipe_combined_indices.rst b/doc/sphinx/source/recipes/recipe_combined_indices.rst deleted file mode 100644 index 342356c3a2..0000000000 --- a/doc/sphinx/source/recipes/recipe_combined_indices.rst +++ /dev/null @@ -1,76 +0,0 @@ -.. _recipes_combined_indices: - -Indices based on area averages -==================================================== - -Overview --------- - -The goal of this diagnostic is to compute indices based on area averages. - -In recipe_combined_indices.yml, after defining the period (historical or -future projection), the variable is selected. The predefined indices are: - -* Nino 3 -* Nino 3.4 -* Nino 4 -* North Atlantic Oscillation (NAO) -* Southern Oscillation Index (SOI) - -Available recipes and diagnostics ------------------------------------ - -Recipes are stored in recipes/ - -* recipe_combined_indices.yml - -Diagnostics are stored in diag_scripts/magic_bsc/ - -* combined_indices.r : calculates the area-weighted means and multi-model means, with or without weights - - - -User settings -------------- - -User setting files are stored in recipes/ - -#. recipe_combined_indices.yml - - *Required settings for script* - - * region: one of the following strings Nino3, Nino3.4, Nino4, NAO, SOI - * running_mean: an integer specifying the length of the window (in months) to be used for computing the running mean. - * moninf: an integer can be given to determine the first month of the seasonal mean to be computed (from 1 to 12, corresponding to January to December respectively). - * monsup: an integer specifying the last month to be computed (from 1 to 12, corresponding to January to December respectively). - * standardized: ‘true’ or ‘false’ to specify whether to compute the standarization of the variable. - - -Variables ---------- - -* psl, tasmax, tasmin, pr or sfcWind (atmos, monthly, longitude, latitude, time) -* tos (ocean, monthly, longitude, latitude, time) - - -Observations and reformat scripts ---------------------------------- - -*None* - -References ----------- - -* Trenberth, Kevin & National Center for Atmospheric Research Staff (Eds). Last modified 11 Jan 2019. "The Climate Data Guide: Nino SST Indices (Nino 1+2, 3, 3.4, 4; ONI and TNI)." Retrieved from https://climatedataguide.ucar.edu/climate-data/nino-sst-indices-nino-12-3-34-4-oni-and-tni. - - -Example plots -------------- - -.. _fig_combinedindices1: -.. figure:: /recipes/figures/Index_NAO.png - :align: center - :width: 14cm - - - diff --git a/doc/sphinx/source/recipes/recipe_consecdrydays.rst b/doc/sphinx/source/recipes/recipe_consecdrydays.rst deleted file mode 100644 index b5d04b0ab4..0000000000 --- a/doc/sphinx/source/recipes/recipe_consecdrydays.rst +++ /dev/null @@ -1,37 +0,0 @@ -Consecutive dry days -==================== - -Overview --------- -Meteorological drought can in its simplest form be described by a lack of precipitation. First, a wet day threshold is set, which can be either a limit related to measurement accuracy, or more directly process related to an amount that would break the drought. The diagnostic calculates the longest period of consecutive dry days, which is an indicator of the worst drought in the time series. Further, the diagnostic calculates the frequency of dry periods longer than a user defined number of days. - - -Available recipes and diagnostics ---------------------------------- - -Recipes are stored in recipes/ - - * recipe_consecdrydays.yml - -Diagnostics are stored in diag_scripts/droughtindex/ - - * diag_cdd.py: calculates the longest period of consecutive dry days, and - the frequency of dry day periods longer than a user defined length - - -User settings in recipe ------------------------ - -#. Script diag_cdd.py - - *Required settings (script)* - - * plim: limit for a day to be considered dry [mm/day] - - * frlim: the shortest number of consecutive dry days for entering statistic on frequency of dry periods. - - -Variables ---------- - -* pr (atmos, daily mean, time latitude longitude) diff --git a/doc/sphinx/source/recipes/recipe_crem.rst b/doc/sphinx/source/recipes/recipe_crem.rst deleted file mode 100644 index 28838502c0..0000000000 --- a/doc/sphinx/source/recipes/recipe_crem.rst +++ /dev/null @@ -1,109 +0,0 @@ -Cloud Regime Error Metric (CREM) -================================ - -Overview --------- - -The radiative feedback from clouds remains the largest source of uncertainty -in determining the climate sensitivity. Traditionally, cloud has been -evaluated in terms of its impact on the mean top of atmosphere fluxes. -However it is quite possible to achieve good performance on these criteria -through compensating errors, with boundary layer clouds being too reflective -but having insufficient horizontal coverage being a common example (e.g., -Nam et al., 2012). Williams and Webb (2009) (WW09) propose a Cloud Regime -Error Metric (CREM) which critically tests the ability of a model to -simulate both the relative frequency of occurrence and the radiative -properties correctly for a set of cloud regimes determined by the daily -mean cloud top pressure, cloud albedo and fractional coverage at each -grid-box. WW09 describe in detail how to calculate their metrics and we -have included the CREMpd metric from their paper in ESMValTool, with clear -references in the lodged code to tables in their paper. This has been -applied to those CMIP5 models who have submitted the required diagnostics -for their AMIP simulation (see Figure 8 below). As documented by WW09, a -perfect score with respect to ISCCP would be zero. WW09 also compared -MODIS/ERBE to ISCCP in order to provide an estimate of observational -uncertainty. This was found to be 0.96 and this is marked on Figure 8, -hence a model with a CREM similar to this value could be considered to have -an error comparable with observational uncertainty, although it should be -noted that this does not necessarily mean that the model lies within the -observations for each regime. A limitation of the metric is that it requires -a model to be good enough to simulate each regime. If a model is that poor -that the simulated frequency of occurrence of a particular regime is zero, -then a NaN will be returned from the code and a bar not plotted on the -figure for that model. - - -Available recipes and diagnostics ---------------------------------- - -Recipes are stored in recipes/ - -* recipe_williams09climdyn_CREM.yml - -Diagnostics are stored in diag_scripts/crem/ - -* ww09_esmvaltool.py - - - -User settings -------------- - -None. - - -Variables ---------- - -* albisccp (atmos, daily mean, longitude latitude time) -* cltisccp (atmos, daily mean, longitude latitude time) -* pctisccp (atmos, daily mean, longitude latitude time) -* rlut (atmos, daily mean, longitude latitude time) -* rlutcs (atmos, daily mean, longitude latitude time) -* rsut (atmos, daily mean, longitude latitude time) -* rsutcs (atmos, daily mean, longitude latitude time) -* sic/siconc (seaice, daily mean, longitude latitude time) -* snc (atmos, daily mean, longitude latitude time) - -If snc is not available then snw can be used instead. For AMIP simulations, -sic/siconc is often not submitted as it a boundary condition and effectively -the same for every model. In this case the same daily sic data set can be -used for each model. - -**Note: in case of using sic/siconc data from a different model (AMIP), it has to -be checked by the user that the calendar definitions of all data sets are -compatible, in particular whether leap days are included or not.** - - - -Observations and reformat scripts ---------------------------------- - -All observational data have been pre-processed and included within the -routine. These are ISCCP, ISCCP-FD, MODIS, ERBE. No additional observational -data are required at runtime. - - - -References ----------- - -* Nam, C., Bony, S., Dufresne, J.-L., and Chepfer, H.: The 'too few, too bright' - tropical low-cloud problem in CMIP5 models, Geophys. Res. Lett., 39, L21801, - doi: 10.1029/2012GL053421, 2012. -* Williams, K.D. and Webb, M.J.: A quantitative performance assessment of - cloud regimes in climate models. Clim. Dyn. 33, 141-157, doi: - 10.1007/s00382-008-0443-1, 2009. - - -Example plots -------------- - -.. figure:: /recipes/figures/crem/crem_error_metric.png - :width: 10cm - :alt: xxxxx - - Cloud Regime Error Metrics (CREMpd) from William and Webb (2009) applied - to those CMIP5 AMIP simulations with the required data in the archive. A - perfect score with respect to ISCCP is zero; the dashed red line is an - indication of observational uncertainty. diff --git a/doc/sphinx/source/recipes/recipe_cvdp.rst b/doc/sphinx/source/recipes/recipe_cvdp.rst deleted file mode 100644 index 7e84cd8212..0000000000 --- a/doc/sphinx/source/recipes/recipe_cvdp.rst +++ /dev/null @@ -1,53 +0,0 @@ -The Climate Variability Diagnostics Package (CVDP) -================================================== - -Overview --------- -The Climate Variability Diagnostics Package (CVDP) developed by NCAR's Climate Analysis Section is an analysis tool that documents the major modes of climate variability in models and observations, including ENSO, Pacific Decadal Oscillation, Atlantic Multi-decadal Oscillation, Northern and Southern Annular Modes, North Atlantic Oscillation, Pacific North and South American teleconnection patterns. For details please refer to the [1] and [2]. - -Available recipes and diagnostics ---------------------------------- - -Recipes are stored in recipes/ - - * recipe_cvdp.yml - -Diagnostics are stored in diag_scripts/cvdp/ - - * cvdp_wrapper.py - -User settings in recipe ------------------------ - -Currently, the recipe must be used with a single dataset entry. - -Variables ---------- - -* ts (atmos, monthly mean, longitude latitude time) -* tas (atmos, monthly mean, longitude latitude time) -* pr (atmos, monthly mean, longitude latitude time) -* psl (atmos, monthly mean, longitude latitude time) - - -Observations and reformat scripts ---------------------------------- - -*Note: (1) obs4mips data can be used directly without any preprocessing; -(2) see headers of reformat scripts for non-obs4mips data for download -instructions.* - - -References ----------- -[1] http://www.cesm.ucar.edu/working_groups/CVC/cvdp/ - -[2] https://github.com/NCAR/CVDP-ncl - -Example plots -------------- - -.. figure:: /recipes/figures/cvdp/nam.prreg.ann.png - :align: center - - Atmospheric Modes of Variability; pr (annual) diff --git a/doc/sphinx/source/recipes/recipe_diurnal_temperature_index.rst b/doc/sphinx/source/recipes/recipe_diurnal_temperature_index.rst deleted file mode 100644 index b04cf039fd..0000000000 --- a/doc/sphinx/source/recipes/recipe_diurnal_temperature_index.rst +++ /dev/null @@ -1,74 +0,0 @@ -.. _recipe_diurnal_temperature_index: - -Diurnal temperature variation indicator: Difference between Tmax and Tmin for a specific day -============================================================================================ - -Overview --------- - -The goal of this diagnostic is to compute a vulnerability indicator for the diurnal temperature range (DTR); the maximum variation in temperature within a period of 24 hours at a given location. This indicator was first proposed by the energy sector, to identify locations which may experience increased diurnal temperature variation in the future, which would put additional stress on the operational management of district heating systems. This indicator was defined as the DTR exceeding 5 degrees celsius at a given location and day of the year (Deandreis et al., N.D.). Projections of this indicator currently present high uncertainties, uncertainties associated to both Tmax and Tmin in future climate projections. - -As well as being of use to the energy sector, the global‐average DTR has been evaluated using both observations and climate model simulations (Braganza et. al., 2004) and changes in the mean and variability of the DTR have been shown to have a wide range of impacts on society, such as on the transmission of diseases (Lambrechts et al., 2011; Paaijmans et al., 2010) and energy consumption (Deandreis et al., N.D.). - -The recipe recipe_diurnal_temperature_index.yml computes first a mean DTR for a reference period using historical simulations and then, the number of days when the DTR from the future climate projections exceeds that of the reference period by 5 degrees or more. The user can define both the reference and projection periods, and the region to be considered. The output produced by this recipe consists of a four panel plot showing the maps of the projected mean DTR indicator for each season and a netcdf file containing the corresponding data. - - - -Available recipes and diagnostics ---------------------------------- - -Recipes are stored in recipes/ - -* recipe_diurnal_temperature_index.yml - -Diagnostics are stored in diag_scripts/magic_bsc/ - -* diurnal_temp_index.r : calculates the diaurnal temperature vulnerability index. - - -User settings -------------- - -User setting files are stored in recipes/ - -#. recipe_diurnal_temperature_index.yml - - *Required settings for script* - - * None - -Variables ---------- - -* tasmin and tasmax (atmos, daily, longitude, latitude, time) - - -Observations and reformat scripts ---------------------------------- - -*None* - -References ----------- - -* Amiri, S. (2013). Economic and Environmental Benefits of CHP-based District Heating Systems in Sweden. Retrieved from http://www.sgc.se/ckfinder/userfiles/files/sokmotor/LiU67.pdf - -* Braganza, K., Karoly, D. J., & Arblaster, J. M. (2004). Diurnal temperature range as an index of global climate change during the twentieth century. Geophysical Research Letters, 31(13), n/a – n/a. https://doi.org/10.1029/2004GL019998 - -* Déandreis C. (IPSL), Braconnot P. (IPSL), Planton S. (CNRMGAME). Study performed for the DALKIA company. http://secif.ipsl.fr/images/SECIF/documents/Communication/fiche_invulnerable/RC_indicateur_EN.pdf - -* Lambrechts, L., Paaijmans, K. P., Fansiri, T., Carrington, L. B., Kramer, L. D., Thomas, M. B., & Scott, T. W. (2011). Impact of daily temperature fluctuations on dengue virus transmission by Aedes aegypti. Proceedings of the National Academy of Sciences of the United States of America, 108(18), 7460–7465. https://doi.org/10.1073/pnas.1101377108 - -* Paaijmans, K. P., Blanford, S., Bell, A. S., Blanford, J. I., Read, A. F., & Thomas, M. B. (2010). Influence of climate on malaria transmission depends on daily temperature variation. Proceedings of the National Academy of Sciences of the United States of America, 107(34), 15135–15139. https://doi.org/10.1073/pnas.1006422107 - -* Kalnay, E., & Cai, M. (2003). Impact of urbanization and land-use change on climate. Nature, 423(6939), 528–531. https://doi.org/10.1038/nature01675 - -* Thyholt, M., & Hestnes, A. G. (2008). Heat supply to low-energy buildings in district heating areas: Analyses of CO2 emissions and electricity supply security. Energy and Buildings, 40(2), 131–139. https://doi.org/10.1016/J.ENBUILD.2007.01.016 - -Example plots -------------- - -.. _fig_diurnal: -.. figure:: /recipes/figures/diurnal_temp_index/rcp85_diurnal.png - :align: center - :width: 14cm diff --git a/doc/sphinx/source/recipes/recipe_ensclus.rst b/doc/sphinx/source/recipes/recipe_ensclus.rst deleted file mode 100644 index 7b0f05ff1f..0000000000 --- a/doc/sphinx/source/recipes/recipe_ensclus.rst +++ /dev/null @@ -1,82 +0,0 @@ -EnsClus - Ensemble Clustering - a cluster analysis tool for climate model simulations -===================================================================================== - - -Overview --------- -EnsClus is a cluster analysis tool in Python, based on the k-means algorithm, for ensembles of climate model simulations. - -Multi-model studies allow to investigate climate processes beyond the limitations of individual models by means of inter-comparison or averages of several members of an ensemble. With large ensembles, it is often an advantage to be able to group members according to similar characteristics and to select the most representative member for each cluster. - -The user chooses which feature of the data is used to group the ensemble members by clustering: time mean, maximum, a certain percentile (e.g., 75% as in the examples below), standard deviation and trend over the time period. For each ensemble member this value is computed at each grid point, obtaining N lat-lon maps, where N is the number of ensemble members. The anomaly is computed subtracting the ensemble mean of these maps to each of the single maps. The anomaly is therefore computed with respect to the ensemble members (and not with respect to the time) and the Empirical Orthogonal Function (EOF) analysis is applied to these anomaly maps. - -Regarding the EOF analysis, the user can choose either how many Principal Components (PCs) to retain or the percentage of explained variance to keep. After reducing dimensionality via EOF analysis, k-means analysis is applied using the desired subset of PCs. - -The major final outputs are the classification in clusters, i.e. which member belongs to which cluster (in k-means analysis the number k of clusters needs to be defined prior to the analysis) and the most representative member for each cluster, which is the closest member to the cluster centroid. - -Other outputs refer to the statistics of clustering: in the PC space, the minimum and the maximum distance between a member in a cluster and the cluster centroid (i.e. the closest and the furthest member), the intra-cluster standard deviation for each cluster (i.e. how much the cluster is compact). - - -Available recipes and diagnostics ---------------------------------- - -Recipes are stored in recipes/ - -* recipe_ensclus.yml - -Diagnostics are stored in diag_scripts/ensclus/ - -* ensclus.py - -and subroutines - -* ens_anom.py -* ens_eof_kmeans.py -* ens_plots.py -* eof_tool.py -* read_netcdf.py -* sel_season_area.py - - -User settings -------------- - -*Required settings for script* - -* season: season over which to perform seasonal averaging (DJF, DJFM, NDJFM, JJA) -* area: region of interest (EAT=Euro-Atlantic, PNA=Pacific North American, NH=Northern Hemisphere, EU=Europe) -* extreme: extreme to consider: XXth_percentile (XX can be set arbitrarily, e.g. 75th_percentile), mean (mean value over the period), maximum (maximum value over the period), std (standard deviation), trend (linear trend over the period) -* numclus: number of clusters to be computed -* perc: percentage of variance to be explained by PCs (select either this or numpcs, default=80) -* numpcs: number of PCs to retain (has priority over perc unless it is set to 0 (default)) - -*Optional settings for script* - -* max_plot_panels: maximum number of panels (datasets) in a plot. When exceeded multiple plots are created. Default: 72 - - -Variables ---------- - -* chosen by user (e.g., precipitation as in the example) - - -Observations and reformat scripts ---------------------------------- - -None. - - -References ----------- - -* Straus, D. M., S. Corti, and F. Molteni: Circulation regimes: Chaotic variability vs. SST forced predictability. J. Climate, 20, 2251–2272, 2007. https://doi.org/10.1175/JCLI4070.1 - - -Example plots -------------- - -.. figure:: /recipes/figures/ensclus/ensclus.png - :width: 10cm - -Clustering based on historical JJA precipitation rate (mm/day), 75th percentile, CMIP5 models, 3 clusters, 80% variance explained by PCs. diff --git a/doc/sphinx/source/recipes/recipe_extreme_events.rst b/doc/sphinx/source/recipes/recipe_extreme_events.rst deleted file mode 100644 index 5f80794af1..0000000000 --- a/doc/sphinx/source/recipes/recipe_extreme_events.rst +++ /dev/null @@ -1,135 +0,0 @@ -Extreme Events Indices - Computation of ETCCDI extreme indices and plotting -===================================================================================== - - -Overview --------- - -This diagnostic uses the standard climdex.pcic.ncdf R library to -compute the 27 climate change indices specified by -the joint CCl/CLIVAR/JCOMM Expert Team (ET) on Climate Change Detection and Indices http://etccdi.pacificclimate.org/. -The needed input fields are daily average precipitation flux and minimum, maximum and average daily surface temperatures. -The recipe reproduces panels of figure 9.37 of the IPCC AR5 report, producing both a Gleckler plot, -with relative error metrics for the CMIP5 temperature and precipitation extreme indices, -and timeseries plots comparing the ensemble spread with observations. -For plotting 1 to 4 observational reference datasets are supported. If no observational reference datasets are given, the plotting routines do not work, however, index generation without plotting is still possible. -All datasets are regridded to a common grid and considered only over land. - -Available recipes and diagnostics ---------------------------------- - -Recipes are stored in recipes/ - -* recipe_extreme_events.yml - -Diagnostics are stored in diag_scripts/extreme_events/ - -* ExtremeEvents.r - -and subroutines - -* common_climdex_preprocessing_for_plots.r -* make_Glecker_plot2.r -* make_timeseries_plot.r -* cfg_climdex.r -* cfg_extreme.r - -User settings -------------- - -*Required settings for script* - -* reference_datasets: list containing the reference datasets to compare with -* timeseries_idx: list of indices to compute for timeseries plot. - The syntax is "XXXETCCDI_TT", where "TT" can be either "yr" or "mon" - (yearly or monthly indices are computed) and "XXX" can be one of the following: - "altcdd", "altcsdi", "altcwd", "altwsdi", "cdd", "csdi", "cwd", - "dtr", "fd", "gsl", "id", "prcptot", "r10mm", "r1mm", "r20mm", - "r95p", "r99p", "rx1day", "rx5day", "sdii", "su", "tn10p", - "tn90p", "tnn", "tnx", "tr", "tx10p", "tx90p", "txn", "txx", "wsdi". - The option "mon" for "TT" can be only used in combination with one of: - "txx", "tnx", "txn", "tnn", tn10p", "tx10p", "tn90p", "tx90p", "dtr", "rx1day", "rx5day". -* gleckler_idx: list of indices to compute for Gleckler plot. Same syntax as above. - The diagnostic computes all unique indices specified in either ``gleckler_idx`` or ``timeseries_idx``. - If at least one "mon" index is selected, the indices are computed but no plots are produced. -* base_range: a list of two years to specify the range to be used as "base range" for climdex - (the period in which for example reference percentiles are computed) - -*Optional settings for script* - -* regrid_dataset: name of dataset to be used as common target for regridding. If missing the first reference dataset is used -* mip_name: string containing the name of the model ensemble, used for titles and labels in the plots (default: "CMIP") -* analysis_range: a list of two years to specify the range to be used for the analysis in the plots. - The input data will need to cover both ``analysis_range`` and ``base_range``. If missing the full period covered by the - input datasets will be used. -* ts_plt: (logical) if to produce the timeseries or not (default: true) -* glc_plt: (logical) if to produce the Gleckler or not (default: true) -* climdex_parallel: number of parallel threads to be used for climdex calculation (default: 4). Also the logical ``false`` can be passed to switch off parallel computation. -* normalize: (logical) if to detrend and normalize with the standard deviation for the datasets for use in the timeseries plot. When this option is used the data for the following indices are detrended and normalized in the timeseries plots: "altcdd", "altcsdi", "altcwd", "altwsdi", "cdd", "cwd","dtr", "fd", "gsl", "id", "prcptot", "r10mm", "r1mm", "r20mm", "r95p", "r99p", "rx1day", "rx5day", "sdii", "su", "tnn", "tnx", "tr", "txn","txn","txx" (default: false) - -Additional optional setting controlling the plots: - -* Timeseries plots: - - * ts_png_width: width for png figures (dafult: 640) - * ts_png_height: height for png figures (default: 480) - * ts_png_units: units for figure size (default: "px") - * ts_png_pointsize: fontsize (default: 12) - * ts_png_bg: background color (default: "white") - * ts_col_list: list of colors for lines (default: ["dodgerblue2", "darkgreen", "firebrick2", "darkorchid", "aquamarine3"]``) - * ts_lty_list: list of linetypes (default: [1, 4, 2, 3, 5]) - * ts_lwd_list: list of linewidths (default: [2, 2, 2, 2, 2]) - -* Gleckler plot: - - * gl_png_res: height for png figures (default: 480). - The width of the figure is computed automatically. - * gl_png_units: units for figure size (default: "px") - * gl_png_pointsize: fontsize (default: 12) - * gl_png_bg: background color (default: "white") - * gl_mar_par: page margins vector (default: [10, 4, 3, 14]) - * gl_rmsespacer: spacing of RMSE column (default: 0.01) - * gl_scaling_factor: scaling factor for colorscale height (default: 0.9) - * gl_text_scaling_factor: scaling factor for text size (default: 1.0) - * gl_xscale_spacer_rmse: horizontal posizion of coloured colorbar (default: 0.05) - * gl_xscale_spacer_rmsestd: horizontal posizion of gray colorbar (default: 0.05) - * gl_symb_scaling_factor: scaling factor for white "symbol" square explaining the partition (default: 1.0) - * gl_symb_xshift: horizontal position of the symbol box (default: 0.2) - * gl_symb_yshift: vertical position of the symbol box (default: 0.275) - * gl_text_symb_scaling_factor: scaling factor for text to be used for symbol box (default: 0.5) - -Variables ---------- - -* tas (atmos, daily mean, longitude latitude time) -* tasmin (atmos, daily minimum, longitude latitude time) -* tasmax (atmos, daily maximum, longitude latitude time) -* pr (atmos, daily mean, longitude latitude time) - - -Observations and reformat scripts ---------------------------------- - -None. - - -References ----------- - -* Zhang, X., Alexander, L., Hegerl, G. C., Jones, P., Klein Tank, A., Peterson, T. C., Trewin, B., Zwiers, F. W., Indices for monitoring changes in extremes based on daily temperature and precipitation data, WIREs Clim. Change, doi:10.1002/wcc.147, 2011 - -* Sillmann, J., V. V. Kharin, X. Zhang, and F. W. Zwiers, Climate extreme indices in the CMIP5 multi-model ensemble. Part 1: Model evaluation in the present climate. J. Geophys. Res., doi:10.1029/2012JD018390, 2013 - - -Example plots -------------- - -.. figure:: /recipes/figures/extreme_events/gleckler.png - :width: 10cm - -Portrait plot of relative error metrics for the CMIP5 temperature and precipitation extreme indices. Reproduces Fig. 9.37 of the IPCC AR5 report, Chapter 9. - -.. figure:: /recipes/figures/extreme_events/cdd_timeseries.png - :width: 10cm - -Timeseries of Consecutive Dry Days index for CMIP5 models. diff --git a/doc/sphinx/source/recipes/recipe_flato13ipcc.rst b/doc/sphinx/source/recipes/recipe_flato13ipcc.rst deleted file mode 100644 index 80f1d19f11..0000000000 --- a/doc/sphinx/source/recipes/recipe_flato13ipcc.rst +++ /dev/null @@ -1,4 +0,0 @@ -IPCC AR5 Chapter 9 -================== - -Description will be ported from v1 diff --git a/doc/sphinx/source/recipes/recipe_heatwaves_coldwaves.rst b/doc/sphinx/source/recipes/recipe_heatwaves_coldwaves.rst deleted file mode 100644 index 91b372a160..0000000000 --- a/doc/sphinx/source/recipes/recipe_heatwaves_coldwaves.rst +++ /dev/null @@ -1,71 +0,0 @@ -.. _recipes_heatwaves_coldwaves: - -Heat wave and cold wave duration -==================================================== - -Overview --------- - -The goal of this diagnostic is to estimate the relative change in heat/cold wave characteristics in future climates compared to a reference period using daily maximum or minimum temperatures. - -The user can select whether to compute the frequency of exceedances or non-exceedances, which corresponds to extreme high or extreme low temperature events, respectively. The user can also select the minimum duration for an event to be classified as a heat/cold wave and the season of interest. - -The diagnostic calculates the number of days in which the temperature exceeds or does not exceeds the necessary threshold for a consecutive number of days in future climate projections. The result is an annual time series of the total number of heat/cold wave days for the selected season at each grid point. The final output is the average number of heat/cold wave days for the selected season in the future climate projections. - -Available recipes and diagnostics ------------------------------------ - -Recipes are stored in recipes/ - -* recipe_heatwaves_coldwaves.yml - -Diagnostics are stored in diag_scripts/magic_bsc/ - -* extreme_spells.r: calculates the heatwave or coldwave duration. - - -User settings -------------- - -User setting files are stored in recipes/ - -#. recipe_heatwaves_coldwaves.yml - - *Required settings for script* - - * quantile: quantile defining the exceedance/non-exceedance threshold - * min_duration: Min duration in days of a heatwave/coldwave event - * Operator: either '>' for exceedances or '<' for non-exceedances - * season: 'summer' or 'winter - -Variables ---------- - -* tasmax or tasmin (atmos, daily, longitude, latitude, time) - - -Observations and reformat scripts ---------------------------------- - -*None* - -References ----------- - -* Cardoso, S., Marta-Almeida, M., Carvalho, A.C., & Rocha, A. (2017). Heat wave and cold spell changes in Iberia for a future climate scenario. International Journal of Climatology, 37(15), 5192-5205. https://doi.org/10.1002/joc.5158 - -* Ouzeau, G., Soubeyroux, J.-M., Schneider, M., Vautard, R., & Planton, S. (2016). Heat waves analysis over France in present and future climate: Application of a new method on the EURO-CORDEX ensemble. Climate Services, 4, 1-12. https://doi.org/10.1016/J.CLISER.2016.09.002 - -* Wang, Y., Shi, L., Zanobetti, A., & Schwartz, J. D. (2016). Estimating and projecting the effect of cold waves on mortality in 209 US cities. Environment International, 94, 141-149. https://doi.org/10.1016/j.envint.2016.05.008 - -* Zhang, X., Hegerl, G., Zwiers, F. W., & Kenyon, J. (2005). Avoiding inhomogeneity in percentile-based indices of temperature extremes. Journal of Climate, 18(11), 1641-1651. https://doi.org/10.1175/JCLI3366.1 - - -Example plots -------------- - -.. _fig_heatwaves: -.. figure:: /recipes/figures/heatwaves/tasmax_extreme_spell_durationsummer_IPSL-CM5A-LR_rcp85_2020_2040.png - :align: center - :width: 14cm - diff --git a/doc/sphinx/source/recipes/recipe_hyint.rst b/doc/sphinx/source/recipes/recipe_hyint.rst deleted file mode 100644 index 70c90392c9..0000000000 --- a/doc/sphinx/source/recipes/recipe_hyint.rst +++ /dev/null @@ -1,128 +0,0 @@ -Hydroclimatic intensity and extremes (HyInt) -============================================== - - -Overview --------- -The Earth’s hydrological cycle is of key importance both for the climate system and society. For example, the intensity and distribution of precipitation determines the availability or scarcity of fresh water in a certain region, and it is also related to the severity of hazardous events such as flooding or droughts. The simple investigation of average precipitation quantities can clearly hide some of the most relevant aspects of the hydrological cycle and its extremes (e.g., Giorgi et al., 2014). More in general, temperature and precipitation extremes have been the focus of recent climate studies attempting to capture the most relevant component of climate variability and impact on society in a changing climate (e.g., Alexander, 2016. A particular effort has been dedicated to developing and standardising indices that can be adopted for investigation studies with observations and climate models. This tool was developed to calculate a number of hydroclimatic and climate extremes indices and allow a multi-index evaluation of climate models. The tool firstly computes a set of 6 indices that allow to evaluate the response of the hydrological cycle to global warming with a joint view of both wet and dry extremes. The indices were selected following Giorgi et al. (2014) and include the simple precipitation intensity index (SDII), the maximum dry spell length (DSL) and wet spell length (WSL), the hydroclimatic intensity index (HY-INT), which is a measure of the overall behaviour of the hydroclimatic cycle (Giorgi et al., 2011), and the precipitation area (PA), i.e. the area over which at any given day precipitation occurs, (Giorgi et al., 2014). Secondly, also a selection of the 27 temperature and precipitation -based indices of extremes from the Expert Team on Climate Change Detection and Indices (ETCCDI) produced by the climdex (https://www.climdex.org) library can be ingested to produce a multi-index analysis. The tool allows then to perform a subsequent analysis of the selected indices calculating timeseries and trends over predefined continental areas, normalized to a reference period. Trends are calculated using the R `lm` function and significance testing performed with a Student T test on non-null coefficients hypothesis. Trend coefficients are stored together with their statistics which include standard error, t value and Pr(>|t|). The tool can then produce a variety of types of plots including global and regional maps, maps of comparison between models and a reference dataset, timeseries with their spread, trend lines and summary plots of trend coefficients. - -The hydroclimatic indices calculated by the diagnostic and included in the output are defined as follows: - -* PRY = mean annual precipitation -* INT = mean annual precipitation intensity (intensity during wet days, or simple precipitation intensity index SDII) -* WSL = mean annual wet spell length (number of consecutive days during each wet spell) -* DSL = mean annual dry spell lenght (number of consecutive days during each dry spell) -* PA = precipitation area (area over which of any given day precipitation occurs) -* R95 = heavy precipitation index (percent of total precipitation above the 95% percentile of the reference distribution) -* HY-INT = hydroclimatic intensity. HY-INT = normalized(INT) x normalized(DSL). - - - -Available recipes and diagnostics ---------------------------------- - -Recipes are stored in recipes/ - -* recipe_hyint.yml (evaluating the 6 hydroclimatic indices) - -Diagnostics are stored in diag_scripts/hyint/ - -* hyint.R - -and subroutines - -* hyint_diagnostic.R -* hyint_functions.R -* hyint_parameters.R -* hyint_plot_trends.R -* hyint_etccdi_preproc.R -* hyint_metadata.R -* hyint_plot_maps.R -* hyint_preproc.R -* hyint_trends.R - - -User settings -------------- - -*Required settings for script* - - -* norm_years: first and last year of reference normalization period to be used for normalized indices - -* select_indices: indices to be analysed and plotted. Select one or more fields from the following list (order-sensitive): "pa_norm", "hyint", "int_norm", "r95_norm", "wsl_norm", "dsl_norm", "int", "dsl", "wsl" - -* select_regions: Select regions for timeseries and maps from the following list: GL=Globe, GL60=Global 60S/60N, TR=Tropics (30S/30N), SA=South America, AF=Africa, NA=North America, IN=India, EU=Europe, EA=East-Asia, AU=Australia - -* plot_type: type of figures to be plotted. Select one or more from: 1=lon/lat maps per individual field/exp/multi-year mean, 2=lon/lat maps per individual field exp-ref-diff/multi-year mean, 3=lon/lat maps multi-field/exp-ref-diff/multi-year mean, 11=timeseries over required individual region/exp, 12=timeseries over multiple regions/exp, 13=timeseries with multiple models, 14=summary trend coefficients multiple regions, 15=summary trend coefficients multiple models - -*Optional settings for script (with default setting)* - -#. Data - - * rgrid (false): Define whether model data should be regridded. (a) false to keep original resolution; (b) set desired regridding resolution in cdo format e.g., "r320x160"; (c) "REF" to use resolution of reference model - -#. Plotting - - * npancol (2): number of columns in timeseries/trends multipanel figures - * npanrow (3): number of rows in timeseries/trends multipanel figures - * autolevels (true): select automated (true) or pre-set (false) range of values in plots - * autolevels_scale (1): factor multiplying automated range for maps and timeseries - * autolevels_scale_t (1.5): factor multiplying automated range for trend coefficients - -#. Maps - - * oplot_grid (false): plot grid points over maps - * boxregion (false): !=0 plot region boxes over global maps with thickness = abs(boxregion); white (>0) or grey (<0). - * removedesert (false) remove (flag as NA) grid points with mean annual pr < 0.5 mm/day (deserts, Giorgi2014). This affects timeseries and trends calculations too. - -#. Timeseries and trends - - * weight_tseries (true): adopt area weights in timeseries - * trend_years (false): (a) false = apply trend to all years in dataset; (b) [year1, year2] to apply trend calculation and plotting only to a limited time interval - * add_trend (true): add linear trend to plot - * add_trend_sd (false): add dashed lines of stdev range to timeseries - * add_trend_sd_shade (false): add shade of stdev range to timeseries - * add_tseries_lines (true): plot lines connecting timeseries points - * add_zeroline (true): plot a dashed line at y=0 - * trend_years_only (false): limit timeseries plotting to the time interval adopted for trend calculation (excluding the normalization period) - * scale100years (true): plot trends scaled as 1/100 years - * scalepercent (false): plot trends as percent change - - -Variables ---------- - -* pr (atmos, daily mean, longitude latitude time) - - -Observations and reformat scripts ---------------------------------- - -None. - - -References ----------- - -* Giorgi et al., 2014, J. Geophys. Res. Atmos., 119, 11,695–11,708, doi:10.1002/ 2014JD022238 -* Giorgi et al., 2011, J. Climate 24, 5309-5324, doi:10.1175/2011JCLI3979.1 - - -Example plots -------------- - -.. figure:: figures/hyint/hyint_maps.png - :width: 10cm - -Mean hydroclimatic intensity (figure type 1) for the EC-EARTH model historical + rcp8.5 projection over 1976-2099. - -.. figure:: figures/hyint/hyint_timeseries.png - :width: 10cm - -Timeseries for multiple indices and regions (figure type 12) for the ACCESS1-0 model historical + RCP8.5 projection over 1976-2099. - -.. figure:: figures/hyint/hyint_trends.png - :width: 10cm - -Multi-model trend coefficients over selected indices (figure type 14) for rcp85 2006-2099 future projection normalized to the 1976-2005 historical period. diff --git a/doc/sphinx/source/recipes/recipe_landcover.rst b/doc/sphinx/source/recipes/recipe_landcover.rst deleted file mode 100644 index 97528f1b46..0000000000 --- a/doc/sphinx/source/recipes/recipe_landcover.rst +++ /dev/null @@ -1,127 +0,0 @@ -Landcover -========= - - -Overview --------- - -The diagnostic computes the accumulated and fractional extent of major land cover classes, -namely bare soil, crops, grasses, shrubs and trees. The numbers are compiled for the whole -land surface as well as separated into Tropics, northern Extratropics and southern Extratropics. -The cover fractions are compared to ESA-CCI land cover data. - - -Available recipes and diagnostics ---------------------------------- - -Recipes are stored in recipes/ - - * recipe_landcover.yml - -Diagnostics are stored in diag_scripts/landcover/ - - * landcover.py: bar plots showing the accumulated area and mean fractional coverage for five land - cover classes for all experiments as well as their bias compared to observations. - - -User settings -------------- - -script landcover.py - - *Required settings for script* - - * reference_dataset: land cover extent dataset for comparison. The script was developed using - ESACCI-LANDCOVER observations. - - *Optional settings for script* - - * comparison: [variable, model] Choose whether one plot per land cover class is generated comparing - the different experiments (default) or one plot per model comparing the different - land cover classes. - * colorscheme: Plotstyle used for the bar plots. A list of available style is found at - https://matplotlib.org/gallery/style_sheets/style_sheets_reference.html. Seaborn is used as default. - - -Variables ---------- - -* baresoilFrac (land, monthly mean, time latitude longitude) -* grassFrac (land, monthly mean, time latitude longitude) -* treeFrac (land, monthly mean, time latitude longitude) -* shrubFrac (land, monthly mean, time latitude longitude) -* cropFrac (land, monthly mean, time latitude longitude) - - -Observations and reformat scripts ---------------------------------- - -ESA-CCI land cover data (Defourny et al., 2015) needs to be downloaded manually by the user and converted to netCDF files -containing the grid cell fractions for the five major land cover types. The data and a conversion tool -are available at https://maps.elie.ucl.ac.be/CCI/viewer/ upon registration. After obtaining the data and the user -tool, the remapping to 0.5 degree can be done with:: - - ./bin/aggregate-map.sh - -PgridName=GEOGRAPHIC_LAT_LON - -PnumRows=360 - -PoutputLCCSClasses=true - -PnumMajorityClasses=0 - ESACCI-LC-L4-LCCS-Map-300m-P1Y-2015-v2.0.7b.nc - -Next, the data needs to be aggregated into the five major classes (PFT) similar to the study of Georgievski & Hagemann (2018) -and converted from grid cell fraction into percentage. - -+--------------+-------------------------------------------------------------------------------------------------------------+ -| PFT | ESA-CCI Landcover Classes | -+==============+=============================================================================================================+ -| baresoilFrac | Bare_Soil | -+--------------+-------------------------------------------------------------------------------------------------------------+ -| cropFrac | Managed_Grass | -+--------------+-------------------------------------------------------------------------------------------------------------+ -| grassFrac | Natural_Grass | -+--------------+-------------------------------------------------------------------------------------------------------------+ -| shrubFrac | Shrub_Broadleaf_Deciduous + Shrub_Broadleaf_Evergreen + Shrub_Needleleaf_Evergreen | -+--------------+-------------------------------------------------------------------------------------------------------------+ -| treeFrac | Tree_Broadleaf_Deciduous + Tree_Broadleaf_Evergreen + Tree_Needleleaf_Deciduous + Tree_Needleleaf_Evergreen | -+--------------+-------------------------------------------------------------------------------------------------------------+ - -Finally, it might be necessary to adapt the grid structure to the experiments files, e.g converting the -180 --> 180 degree grid -to 0 --> 360 degree and inverting the order of latitudes. Note, that all experiments will be regridded onto the grid of the land -cover observations, thus it is recommended to convert to the coarses resolution which is sufficient for the planned study. -For the script development, ESA-CCI data on 0.5 degree resolution was used with land cover data averaged over the -2008-2012 period. - - -References ----------- - -* Defourny et al. (2015): ESA Land Cover Climate Change Initiative (ESA LC_cci) data: - ESACCI-LC-L4-LCCS-Map-300m-P5Y-[2000,2005,2010]-v1.6.1 via Centre for Environmental Data Analysis -* Georgievski, G. & Hagemann, S. Characterizing uncertainties in the ESA-CCI land cover map of the epoch 2010 and their impacts on MPI-ESM climate simulations, - Theor Appl Climatol (2018). https://doi.org/10.1007/s00704-018-2675-2 - - -Example plots -------------- - -.. _fig_landcover_1: -.. figure:: /recipes/figures/landcover/area_treeFrac.png - :align: center - :width: 14cm - - Accumulated tree covered area for different regions and experiments. - -.. _fig_landcover_2: -.. figure:: /recipes/figures/landcover/frac_grassFrac.png - :align: center - :width: 14cm - - Average grass cover fraction for different regions and experiments - -.. _fig_landcover_3: -.. figure:: /recipes/figures/landcover/bias_CMIP5_MPI-ESM-LR_rcp85_r1i1p1.png - :align: center - :width: 14cm - - Biases in five major land cover fractions for different regions and one experiment. - diff --git a/doc/sphinx/source/recipes/recipe_miles.rst b/doc/sphinx/source/recipes/recipe_miles.rst deleted file mode 100644 index c8ddbefd10..0000000000 --- a/doc/sphinx/source/recipes/recipe_miles.rst +++ /dev/null @@ -1,131 +0,0 @@ -Blocking metrics and indices, teleconnections and weather regimes (MiLES) -========================================================================= - - -Overview --------- - -Atmospheric blocking is a recurrent mid-latitude weather pattern identified by a large-amplitude, quasi-stationary, long-lasting, high-pressure anomaly that ‘‘blocks’’ the westerly flow forcing the jet stream to split or meander -`(Rex, 1950) `_. - -It is typically initiated by the breaking of a Rossby wave in a diffluence region at the exit of the storm track, where it amplifies the underlying stationary ridge `(Tibaldi and Molteni, 1990) `_. -Blocking occurs more frequently in the Northern Hemisphere cold season, with larger frequencies observed over the Euro-Atlantic and North Pacific sectors. Its lifetime oscillates from a few days up to several weeks `(Davini et al., 2012) `_ sometimes leading to winter cold spells or summer heat waves. - -To this end, the MId-Latitude Evaluation System (MiLES) was developed as stand-alone package (https://github.com/oloapinivad/MiLES) to support analysis of mid-latitude weather patterns in terms of atmospheric blocking, teleconnections and weather regimes. The package was then implemented as recipe for ESMValTool. - -The tool works on daily 500hPa geopotential height data (with data interpolated on a common 2.5x2.5 grid) and calculates the following diagnostics: - -1D Atmospheric Blocking -*********************** -`Tibaldi and Molteni (1990) `_ index for Northern Hemisphere. Computed at fixed latitude of 60N, with delta of -5,-2.5,0,2.5,5 deg, fiN=80N and fiS=40N. Full timeseries and climatologies are provided in NetCDF4 Zip format. - -2D Atmospheric blocking -*********************** -Following the index by `Davini et al. (2012) `_. It is a 2D version of `Tibaldi and Molteni (1990) `_ for Northern Hemisphere atmospheric blocking evaluating meridional gradient reversal at 500hPa. It computes both Instantaneous Blocking and Blocking Events frequency, where the latter allows the estimation of the each blocking duration. It includes also two blocking intensity indices, i.e. the Meridional Gradient Index and the Blocking Intensity index. In addition the orientation (i.e. cyclonic or anticyclonic) of the Rossby wave breaking is computed. A supplementary Instantaneous Blocking index with the GHGS2 condition (see `Davini et al., 2012 `_) is also evaluated. -Full timeseries and climatologies are provided in NetCDF4 Zip format. - -Z500 Empirical Orthogonal Functions -*********************************** -Based on SVD. The first 4 EOFs for North Atlantic (over the 90W-40E 20N-85N box) and Northern Hemisphere (20N-85N) or a custom region are computed. North Atlantic Oscillation, East Atlantic Pattern, and Arctic Oscillation can be evaluated. -Figures showing linear regression of PCs on monthly Z500 are provided. PCs and eigenvectors, as well as the variances explained are provided in NetCDF4 Zip format. - -North Atlantic Weather Regimes -****************************** -Following k-means clustering of 500hPa geopotential height. 4 weather regimes over North Atlantic (80W-40E 30N-87.5N) are evaluated using anomalies from daily seasonal cycle. This is done retaining the first North Atlantic EOFs which explains the 80% of the variance to reduce the phase-space dimensions and then applying k-means clustering using Hartigan-Wong algorithm with k=4. Figures report patterns and frequencies of occurrence. NetCDF4 Zip data are saved. Only 4 regimes and DJF supported so far. - - -Available recipes and diagnostics ---------------------------------- - -Recipes are stored in recipes/ - -* recipe_miles_block.yml -* recipe_miles_eof.yml -* recipe_miles_regimes.yml - -Diagnostics are stored in diag_scripts/miles/ - -* miles_block.R -* miles_eof.R -* miles_regimes.R - -and subroutines - -* basis_functions.R -* block_figures.R -* eof_figures.R -* regimes_figures.R -* block_fast.R -* eof_fast.R -* miles_parameters.R -* regimes_fast.R - -`miles_parameters.R` contains additional internal parameters which affect plot sizes, colortables etc. - - -User settings -------------- - -#. miles_block.R - - *Required settings for variables* - - * reference_dataset: reference dataset for comparison - - *Required settings for script* - - * seasons: Selected season('DJF','MAM','JJA','SON','ALL') or your period as e.g. 'Jan_Feb_Mar' - -#. miles_eof.R - - *Required settings for variables* - - * reference_dataset: reference dataset for comparison - - *Required settings for script* - - * seasons: Selected season('DJF','MAM','JJA','SON','ALL') or your period as e.g. 'Jan_Feb_Mar' - * teles: Select EOFs ('NAO','AO','PNA') or specify custom area as "lon1_lon2_lat1_lat2" - -#. miles_regimes.R - - *Required settings for variables* - - * reference_dataset: reference dataset - - *Required or optional settings for script* - - * None (the two parameters seasons and nclusters in the recipe should not be changed) - - -Variables ---------- - -* zg (atmos, daily mean, longitude latitude time) - - -Observations and reformat scripts ---------------------------------- -* ERA-INTERIM - - -References ----------- -* REX, D. F. (1950), Blocking Action in the Middle Troposphere and its Effect upon Regional Climate. Tellus, 2: 196-211. doi: http://doi.org/10.1111/j.2153-3490.1950.tb00331.x -* Davini, P., C. Cagnazzo, S. Gualdi, and A. Navarra (2012): Bidimensional Diagnostics, Variability, and Trends of Northern Hemisphere Blocking. J. Climate, 25, 6496–6509, doi: http://doi.org/10.1175/JCLI-D-12-00032.1. -* Tibaldi S, Molteni F.: On the operational predictability of blocking. Tellus A 42(3): 343–365, doi: 10.1034/j.1600- 0870.1990.t01- 2- 00003.x, 1990. https://doi.org/10.1034/j.1600-0870.1990.t01-2-00003.x -* Paolo Davini. (2018, April 30). MiLES - Mid Latitude Evaluation System (Version v0.51). Zenodo. http://doi.org/10.5281/zenodo.1237838 - - -Example plots -------------- - -.. figure:: /recipes/figures/miles/miles_block.png - :width: 10cm - - Blocking events frequency for EC-Earth model 1980-1989, compared to ERA-Interim. - -.. figure:: /recipes/figures/miles/miles_eof1.png - :width: 10cm - - Teleconnection indices as Z500 empirical orthogonal functions for the North Atlantic (the figure shows EOF1) diff --git a/doc/sphinx/source/recipes/recipe_modes_of_variability.rst b/doc/sphinx/source/recipes/recipe_modes_of_variability.rst deleted file mode 100644 index c7d8b76596..0000000000 --- a/doc/sphinx/source/recipes/recipe_modes_of_variability.rst +++ /dev/null @@ -1,91 +0,0 @@ -.. _recipes_modes_of_variability: - -Modes of variability -==================== - -Overview --------- - -The goal of this recipe is to compute modes of variability from a reference or observational dataset and from a set of climate projections and calculate the root-mean-square error between the mean anomalies obtained for the clusters from the reference and projection data sets. -This is done through K-means or hierarchical clustering applied either directly to the spatial data or after computing the EOFs. - -The user can specify the number of clusters to be computed. - -The recipe's output consist of three netcdf files for both the observed and projected weather regimes and the RMSE between them. - - -Available recipes and diagnostics ---------------------------------- - -Recipes are stored in recipes/ - -* recipe_modes_of_variability.yml - - -Diagnostics are stored in diag_scripts/magic_bsc/ - -* WeatherRegime.r - function for computing the EOFs and k-means and hierarchical clusters. - -* weather_regime.r - applies the above weather regimes function to the datasets - - - -User settings -------------- - -User setting files are stored in recipes/ - -#. recipe_modes_of_variability.yml - - *Required settings for script* - - * plot type: rectangular or polar - * ncenters: number of centers to be computed by the clustering algorithm (maximum 4) - * cluster_method: kmeans (only psl variable) or hierarchical clustering (for psl or sic variables) - * detrend_order: the order of the polynomial detrending to be applied (0, 1 or 2) - * EOFs: logical indicating wether the k-means clustering algorithm is applied directly to the spatial data ('false') or to the EOFs ('true') - * frequency: select the month (format: JAN, FEB, ...) or season (format: JJA, SON, MAM, DJF) for the diagnostic to be computed for (does not work yet for MAM with daily data). - - -Variables ---------- - -* psl (atmos, monthly/daily, longitude, latitude, time) - - -Observations and reformat scripts ---------------------------------- - -*None* - -References ----------- - -* Dawson, A., T. N. Palmer, and S. Corti, 2012: Simulating regime structures in weather and climate prediction models. Geophysical Research Letters, 39 (21), https://doi.org/10.1029/2012GL053284. - -* Ferranti, L., S. Corti, and M. Janousek, 2015: Flow-dependent verification of the ECMWF ensemble over the Euro-Atlantic sector. Quarterly Journal of the Royal Meteorological Society, 141 (688), 916-924, https://doi.org/10.1002/qj.2411. - -* Grams, C. M., Beerli, R., Pfenninger, S., Staffell, I., & Wernli, H. (2017). Balancing Europe's wind-power output through spatial deployment informed by weather regimes. Nature climate change, 7(8), 557, https://doi.org/10.1038/nclimate3338. - -* Hannachi, A., D. M. Straus, C. L. E. Franzke, S. Corti, and T. Woollings, 2017: Low Frequency Nonlinearity and Regime Behavior in the Northern Hemisphere Extra-Tropical Atmosphere. Reviews of Geophysics, https://doi.org/10.1002/2015RG000509. - -* Michelangeli, P.-A., R. Vautard, and B. Legras, 1995: Weather regimes: Recurrence and quasi stationarity. Journal of the atmospheric sciences, 52 (8), 1237-1256, doi: `10.1175/1520-0469(1995)052<1237:WRRAQS>2.0.CO `_. - -* Vautard, R., 1990: Multiple weather regimes over the North Atlantic: Analysis of precursors and successors. Monthly weather review, 118 (10), 2056-2081, doi: `10.1175/1520-0493(1990)118<2056:MWROTN>2.0.CO;2 `_. - -* Yiou, P., K. Goubanova, Z. X. Li, and M. Nogaj, 2008: Weather regime dependence of extreme value statistics for summer temperature and precipitation. Nonlinear Processes in Geophysics, 15 (3), 365-378, https://doi.org/10.5194/npg-15-365-2008. - - - - -Example plots -------------- - -.. _fig_modesofvar: -.. figure:: /recipes/figures/modes_of_variability/DJF-psl_observed_regimes.png - :align: center - :width: 14cm - - - - diff --git a/doc/sphinx/source/recipes/recipe_multimodel_products.rst b/doc/sphinx/source/recipes/recipe_multimodel_products.rst deleted file mode 100644 index 20d1219c24..0000000000 --- a/doc/sphinx/source/recipes/recipe_multimodel_products.rst +++ /dev/null @@ -1,78 +0,0 @@ -.. _recipes_multimodel_products: - -Generic multi-model products -==================================================== - -Overview --------- - -The goal of this diagnostic is to compute the multi-model ensemble mean for a set of models selected by the user for individual variables and different temporal resolutions (annual, seasonal, monthly). - -After selecting the region (defined by the lowermost and uppermost longitudes and latitudes), the mean for the selected reference period is subtracted from the projections in order to obtain the anomalies for the desired period. In addition, the recipe computes the percentage of models agreeing on the sign of this anomaly, thus providing some indication on the robustness of the climate signal. - -The output of the recipe consists of a colored map showing the time average of the multi-model mean anomaly and stippling to indicate locations where the percentage of models agreeing on the sign of the anomaly exceeds a threshold selected by the user. Furthermore, a time series of the area-weighted mean anomaly for the projections is plotted. For the plots, the user can select the length of the running window for temporal smoothing and choose to display the ensemble mean with a light shading to represent the spread of the ensemble or choose to display each individual models. - - - -Available recipes and diagnostics ------------------------------------ - -Recipes are stored in recipes/ - -* recipe_multimodel_products.yml - - -Diagnostics are stored in diag_scripts/magic_bsc/ - -* multimodel_products.r - script for computing multimodel anomalies and their agreement. - - - - -User settings -------------- - -User setting files are stored in recipes/ - -#. recipe_multimodel_products.yml - - *Required settings for script* - - * moninf: integer specifying the first month of the seasonal mean period to be computed - * monsup: integer specifying the last month of the seasonal mean period to be computed, if it's null the anomaly of month indicated in moninf will be computed - * agreement_threshold: integer between 0 and 100 indicating the threshold in percent for the minimum agreement between models on the sign of the multi-model mean anomaly for the stipling to be plotted - * running_mean: integer indictating the length of the window for the running mean to be computed - * time_series_plot: Either single or maxmin (plot the individual or the mean with shading between the max and min). - - -Variables ---------- - -* any Amon variable (atmos, monthly mean, longitude latitude time) - - -Observations and reformat scripts ---------------------------------- - -*None* - -References ----------- - -* Hagedorn, R., Doblas-Reyes, F. J., Palmer, T. N., Nat E H Ag E D O R N, R. E., & Pa, T. N. (2005). The rationale behind the success of multi-model ensembles in seasonal forecasting-I. Basic concept, 57, 219–233. https://doi.org/10.3402/tellusa.v57i3.14657 - -* Weigel, A. P., Liniger, M. A., & Appenzeller, C. (2008). Can multi-model combination really enhance the prediction skill of probabilistic ensemble forecasts? Quarterly Journal of the Royal Meteorological Society, 134(630), 241–260. https://doi.org/10.1002/qj.210 - - - - - - -Example plots -------------- - -.. _fig_multimodprod: -.. figure:: /recipes/figures/multimodel_products/tas_JUN_multimodel-anomaly_2006_2099_1961_1990.png - - - diff --git a/doc/sphinx/source/recipes/recipe_oceans.rst b/doc/sphinx/source/recipes/recipe_oceans.rst deleted file mode 100644 index 9567cc5d6d..0000000000 --- a/doc/sphinx/source/recipes/recipe_oceans.rst +++ /dev/null @@ -1,780 +0,0 @@ -.. _XML_oceans: - -Recipes for evaluating models of the ocean -========================================== - -Overview -........ - -These recipes are used for evaluating the marine component of models of the -earth system. Using these recipes, it should be possible to evaluate both the -physical models and biogeochemistry models. All these recipes use the -ocean diagnostics package. - -The ocean diagnostics package contains several diagnostics which produce -figures and statistical information of models of the ocean. The datasets have -been pre-processed by ESMValTool, based on recipes in the recipes directory. -Most of the diagnostics produce two or less types of figure, and several -diagnostics are called by multiple recipes. - -Each diagnostic script expects a metadata file, automatically generated by -ESMValTool, and one or more pre-processed dataset. These are passed to the -diagnostic by ESMValTool in the settings.yml and metadata.yml files. - -The ocean diagnostics toolkit can not figure out how to plot data by itself. -The current version requires the recipe to produce the correct pre-processed -data for each diagnostic script. ie: to produce a time series plot, -the preprocessor must produce a time-dimensional dataset. - -While these tools were built to evaluate the ocean component models, they also -can be used to produce figures for other domains. However, there are some ocean -specific elements, such as the z-direction being positive and reversed, and -some of the map plots have the continents coloured in by default. - -As elsewhere, both the model and observational datasets need to be -compliant with the CMOR data. - -Available recipes -................. - -* recipe_ocean_amoc.yml_ -* recipe_ocean_example.yml_ -* recipe_ocean_scalar_fields.yml_ -* recipe_ocean_bgc.yml_ -* recipe_ocean_quadmap.yml_ -* recipe_ocean_Landschutzer2014.yml_ - - -recipe_ocean_amoc.yml ---------------------- - -The recipe_ocean_amoc.yml_ is an recipe that produces figures describing the -Atlantic Meridional Overturning Circulation (AMOC) and the drake passage -current. - -The recipes produces time series of the AMOC at 26 north and the -drake passage current. - -.. centered:: |pic_amoc| - -.. |pic_amoc| image:: /recipes/figures/ocean/amoc_fig_1.png - - -This figure shows the multi model comparison of the AMOC from several CMIP5 -historical simulations, with a 6 year moving average (3 years either side of the -central value). A similar figure is produced for each individual model, and -for the Drake Passage current. - -This recipe also produces a contour transect and a coloured transect plot -showing the Atlantic stream function for each individual model, and a -multi-model contour is also produced: - -.. centered:: |pic_ocean_sf3| |pic_ocean_sf4| - -.. |pic_ocean_sf3| image:: /recipes/figures/ocean/stream_function1.png -.. |pic_ocean_sf4| image:: /recipes/figures/ocean/stream_function2.png - - -recipe_ocean_example.yml ------------------------- - -The recipe_ocean_example.yml_ is an example recipe which shows several examples -of how to manipulate marine model data using the ocean diagnostics tools. - -While several of the diagnostics here have specific uses in evaluating models, -it is meant to be a catch-all recipe demonstrating many different ways to -evaluate models. - -All example calculations are performed using the ocean temperature in a three -dimensional field (thetao), or at the surface (tos). This recipe demonstrates -the use of a range of preprocessors in a marine context, and also shows many -of the standard model-only diagnostics (no observational component is included.) - -This recipe includes examples of how to manipulate both 2D and 3D fields to -produce: - -* Time series: - - * Global surface area weighted mean time series - * Volume weighted average time series within a specific depth range - * Area weighted average time series at a specific depth - * Area weighted average time series at a specific depth in a specific region. - * Global volume weighted average time series - * Regional volume weighted average time series - -* Maps: - - * Global surface map (from 2D ad 3D initial fields) - * Global surface map using re-gridding to a regular grid - * Global map using re-gridding to a regular grid at a specific depth level - * Regional map using re-gridding to a regular grid at a specific depth level - -* Transects: - - * Produce various transect figure showing a re-gridded transect plot, and multi model comparisons - -* Profile: - - * Produce a Global area-weighted depth profile figure - * Produce a regional area-weighted depth profile figure - -All the these fields can be expanded using a - -recipe_ocean_bgc.yml --------------------- - -The recipe_ocean_bgc.yml_ is an example recipe which shows a several simple examples of how to -manipulate marine biogeochemical model data. - -This recipe includes the following fields: - -* Global total volume-weighted average time series: - - * temperature, salinity, nitrate, oxygen, silicate (vs WOA data) `*` - * chlorophyll, iron, total alkalinity (no observations) - -* Surface area-weighted average time series: - - * temperature, salinity, nitrate, oxygen, silicate (vs WOA data) `*` - * fgco2 (global total), integrated primary production, chlorophyll, - iron, total alkalinity (no observations) - -* Scalar fields time series: - - * mfo (including stuff like drake passage) - -* Profiles: - - * temperature, salinity, nitrate, oxygen, silicate (vs WOA data) `*` - * chlorophyll, iron, total alkalinity (no observations) - -* Maps + contours: - - * temperature, salinity, nitrate, oxygen, silicate (vs WOA data) `*` - * chlorophyll, iron, total alkalinity (no observations) - -* Transects + contours: - - * temperature, salinity, nitrate, oxygen, silicate (vs WOA data) `*` - * chlorophyll, iron, no observations) - -`*` Note that Phosphate is also available as a WOA diagnostic, but I haven't -included it as HadGEM2-ES doesn't include a phosphate field. - -This recipe uses the World Ocean Atlas data, which can be downloaded from: -https://www.nodc.noaa.gov/OC5/woa13/woa13data.html -(last access 10/25/2018) - -Instructions: Select the "All fields data links (1° grid)" netCDF file, -which contain all fields. - - -.. recipe_OxygenMinimumZones.yml -.. ------------------------------------------ -.. This recipe will appear in a future version. - -.. This recipe produces an analysis of Marine oxygen. The diagnostics are based on -.. figure 1 of the following work: -.. Cabré, A., Marinov, I., Bernardello, R., and Bianchi, D.: Oxygen minimum zones -.. in the tropical Pacific across CMIP5 models: mean state differences and climate -.. change trends, Biogeosciences, 12, 5429-5454, -.. https://doi.org/10.5194/bg-12-5429-2015, 2015. - - -recipe_ocean_quadmap.yml ------------------------- - -The recipe_ocean_quadmap.yml_ is an example recipe showing the -diagnostic_maps_quad.py_ diagnostic. -This diagnostic produces an image showing four maps. Each of these four maps -show latitude vs longitude and the cube value is used as the colour scale. -The four plots are: - -================= ==================== -model1 model 1 minus model2 ------------------ -------------------- -model2 minus obs model1 minus obs -================= ==================== - -These figures are also known as Model vs Model vs Obs plots. - - -The figure produced by this recipe compares two versions of the HadGEM2 model -against ATSR sea surface temperature: - -.. centered:: |pic_quad_plot| - -.. |pic_quad_plot| image:: /recipes/figures/ocean/ocean_quad_plot1.png - -This kind of figure can be very useful when developing a model, as it -allows model developers to quickly see the impact of recent changes -to the model. - - -recipe_ocean_ice_extent.yml ---------------------------- - -The recipe_ocean_ice_extent.yml_ recipe produces several metrics describing -the behaviour of sea ice in a model, or in multiple models. - -This recipe has four preprocessors, a combinatorial combination of - -* Regions: Northern or Southern Hemisphere -* Seasons: December-January-February or June-July-August - -Once these seasonal hemispherical fractional ice cover is processed, -the resulting cube is passed 'as is' to the diagnostic_seaice.py_ -diagnostic. - -This diagnostic produces the plots: - -* Polar Stereographic projection Extent plots of individual models years. -* Polar Stereographic projection maps of the ice cover and ice extent for - individual models. -* A time series of Polar Stereographic projection Extent plots - see below. -* Time series plots of the total ice area and the total ice extent. - - -The following image shows an example of the sea ice extent plot, showing the -Summer Northern hemisphere ice extent for the HadGEM2-CC model, in the -historical scenario. - -.. centered:: |pic_sea_ice1| - -.. |pic_sea_ice1| image:: /recipes/figures/ocean/ocean_sea_ice1.png - - -The sea ice diagnostic is unlike the other diagnostics in the ocean diagnostics -toolkit. The other tools are build to be generic plotting tools which -work with any field (ie ``diagnostic_timeseries.py`` works fine for Temperature, -Chlorophyll, or any other field. On the other hand, the -sea ice diagnostic is the only tool that performs a field specific evaluation. - -The diagnostic_seaice.py_ diagnostic is more fully described below. - - - -Available diagnostics -........................ - -Diagnostics are stored in the diag_scripts directory: ocean_. - -The following python modules are included in the ocean diagnostics package. -Each module is described in more detail both below and inside the module. - -- diagnostic_maps.py -- diagnostic_maps_quad.py -- diagnostic_model_vs_obs.py -- diagnostic_profiles.py -- diagnostic_seaice.py -- diagnostic_timeseries.py -- diagnostic_tools.py -- diagnostic_transects.py - - -diagnostic_maps.py ------------------- - -The diagnostic_maps.py_ produces a spatial map from a NetCDF. It requires the -input netCDF to have the following dimensions. Either: - -- A two dimensional file: latitude, longitude. -- A three dimensional file: depth, latitude, longitude. - -In the case of a 3D netCDF file, this diagnostic produces a map for EVERY layer. -For this reason, we recommend extracting a small number of specific layers in -the preprocessor, using the `extract_layer` preprocessor. - -This script can not process NetCDFs with multiple time steps. Please use the -`time_average` preprocessor to collapse the time dimension. - -This diagnostic also includes the optional arguments, `threshold` and -`thresholds`. - -- threshold: a single float. -- thresholds: a list of floats. - -Only one of these arguments should be provided at a time. These two arguments -produce a second kind of diagnostic map plot: a contour map showing the spatial -distribution of the threshold value, for each dataset. Alternatively, if the -thresholds argument is used instead of threshold, the single-dataset contour -map shows the contours of all the values in the thresholds list. - -If multiple datasets are provided, in addition to the single dataset contour, -a multi-dataset contour map is also produced for each value in the thresholds -list. - -Some appropriate preprocessors for this diagnostic would be: - -For a Global 2D field: - - .. code-block:: yaml - - prep_map_1: - time_average: - - -For a regional 2D field: - - .. code-block:: yaml - - prep_map_2: - extract_region: - start_longitude: -80. - end_longitude: 30. - start_latitude: -80. - end_latitude: 80. - time_average: - -For a Global 3D field at the surface and 10m depth: - - .. code-block:: yaml - - prep_map_3: - custom_order: true - extract_levels: - levels: [0., 10.] - scheme: linear_horizontal_extrapolate_vertical - time_average: - - -For a multi-model comparison mean of 2D global fields including contour thresholds. - - .. code-block:: yaml - - prep_map_4: - custom_order: true - time_average: - regrid: - target_grid: 1x1 - scheme: linear - -And this also requires the threshold key in the diagnostic: - - .. code-block:: yaml - - diagnostic_map: - variables: - tos: # Temperature ocean surface - preprocessor: prep_map_4 - field: TO2M - scripts: - Ocean_regrid_map: - script: ocean/diagnostic_maps.py - thresholds: [5, 10, 15, 20] - - -diagnostic_maps_quad.py --------------------------------- - -The diagnostic_maps_quad.py_ diagnostic produces an image showing four maps. -Each of these four maps show latitude vs longitude and the cube value is used -as the colour scale. The four plots are: - -================= ==================== -model1 model 1 minus model2 ------------------ -------------------- -model2 minus obs model1 minus obs -================= ==================== - - -These figures are also known as Model vs Model vs Obs plots. - -This diagnostic assumes that the preprocessors do the bulk of the -hard work, and that the cubes received by this diagnostic (via the settings.yml -and metadata.yml files) have no time component, a small number of depth layers, -and a latitude and longitude coordinates. - -An appropriate preprocessor for a 2D field would be: - - .. code-block:: yaml - - prep_quad_map: - time_average: - -and an example of an appropriate diagnostic section of the recipe would be: - - .. code-block:: yaml - - diag_map_1: - variables: - tos: # Temperature ocean surface - preprocessor: prep_quad_map - field: TO2Ms - mip: Omon - additional_datasets: - # filename: tos_ATSR_L3_ARC-v1.1.1_199701-201112.nc - # download from: https://datashare.is.ed.ac.uk/handle/10283/536 - - {dataset: ATSR, project: obs4mips, level: L3, version: ARC-v1.1.1, start_year: 2001, end_year: 2003, tier: 3} - scripts: - Global_Ocean_map: - script: ocean/diagnostic_maps_quad.py - control_model: {dataset: HadGEM2-CC, project: CMIP5, mip: Omon, exp: historical, ensemble: r1i1p1} - exper_model: {dataset: HadGEM2-ES, project: CMIP5, mip: Omon, exp: historical, ensemble: r1i1p1} - observational_dataset: {dataset: ATSR, project: obs4mips,} - -Note that the details about the control model, the experiment models -and the observational dataset are all provided in the script section of the -recipe. - - - -diagnostic_model_vs_obs.py --------------------------------- - -The diagnostic_model_vs_obs.py_ diagnostic makes model vs observations maps -and scatter plots. The map plots shows four latitude vs longitude maps: - -======================== ======================= -Model Observations ------------------------- ----------------------- -Model minus Observations Model over Observations -======================== ======================= - -Note that this diagnostic assumes that the preprocessors do the bulk of the -hard work, and that the cube received by this diagnostic (via the settings.yml -and metadata.yml files) has no time component, a small number of depth layers, -and a latitude and longitude coordinates. - -This diagnostic also includes the optional arguments, `maps_range` and -`diff_range` to manually define plot ranges. Both arguments are a list of two floats -to set plot range minimun and maximum values respectively for Model and Observations -maps (Top panels) and for the Model minus Observations panel (bottom left). -Note that if input data have negative values the Model over Observations map -(bottom right) is not produced. - -The scatter plots plot the matched model coordinate on the x axis, and the -observational dataset on the y coordinate, then performs a linear -regression of those data and plots the line of best fit on the plot. -The parameters of the fit are also shown on the figure. - -An appropriate preprocessor for a 3D+time field would be: - - .. code-block:: yaml - - preprocessors: - prep_map: - extract_levels: - levels: [100., ] - scheme: linear_extrap - time_average: - regrid: - target_grid: 1x1 - scheme: linear - - - -diagnostic_profiles.py --------------------------------- - -The diagnostic_profiles.py_ diagnostic produces images of the profile over time from a cube. -These plots show cube value (ie temperature) on the x-axis, and depth/height -on the y axis. The colour scale is the annual mean of the cube data. -Note that this diagnostic assumes that the preprocessors do the bulk of the -hard work, and that the cube received by this diagnostic (via the settings.yml -and metadata.yml files) has a time component, and depth component, but no -latitude or longitude coordinates. - -An appropriate preprocessor for a 3D+time field would be: - - .. code-block:: yaml - - preprocessors: - prep_profile: - extract_volume: - long1: 0. - long2: 20. - lat1: -30. - lat2: 30. - z_min: 0. - z_max: 3000. - area_statistics: - operator: mean - - - -diagnostic_timeseries.py --------------------------------- - -The diagnostic_timeseries.py_ diagnostic produces images of the time development -of a metric from a cube. These plots show time on the x-axis and cube value -(ie temperature) on the y-axis. - -Two types of plots are produced: individual model timeseries plots and -multi model time series plots. The individual plots show the results from a -single cube, even if this cube is a multi-model mean made by the `multimodel` -preprocessor. - -The multi model time series plots show several models on the same axes, where -each model is represented by a different line colour. The line colours are -determined by the number of models, their alphabetical order and the `jet` -colour scale. Observational datasets and multimodel means are shown as black -lines. - -This diagnostic assumes that the preprocessors do the bulk of the work, -and that the cube received by this diagnostic (via the settings.yml -and metadata.yml files) is time-dimensional cube. This means that the pre-processed -netcdf has a time component, no depth component, and no latitude or longitude -coordinates. - -Some appropriate preprocessors would be : - -For a global area-weighted average 2D field: - - .. code-block:: yaml - - area_statistics: - operator: mean - -For a global volume-weighted average 3D field: - - .. code-block:: yaml - - volume_statistics: - operator: mean - -For a global area-weighted surface of a 3D field: - - .. code-block:: yaml - - extract_levels: - levels: [0., ] - scheme: linear_horizontal_extrapolate_vertical - area_statistics: - operator: mean - - -An example of the multi-model time series plots can seen here: - -.. centered:: |pic_amoc2| - -.. |pic_amoc2| image:: /recipes/figures/ocean/amoc_fig_1.png - - - -diagnostic_transects.py --------------------------------- - - - -The diagnostic_transects.py_ diagnostic produces images of a transect, -typically along a constant latitude or longitude. - -These plots show 2D plots with either latitude or longitude along the x-axis, -depth along the y-axis and and the cube value is used as the colour scale. - - -This diagnostic assumes that the preprocessors do the bulk of the hard work, -and that the cube received by this diagnostic (via the settings.yml and -metadata.yml files) has no time component, and one of the latitude or -longitude coordinates has been reduced to a single value. - -An appropriate preprocessor for a 3D+time field would be: - - .. code-block:: yaml - - time_average: - extract_slice: - latitude: [-50.,50.] - longitude: 332. - -Here is an example of the transect figure: -.. centered:: |pic_ocean_sf1| - -.. |pic_ocean_sf1| image:: /recipes/figures/ocean/stream_function1.png - -And here is an example of the multi-model transect contour figure: - -.. centered:: |pic_ocean_sf2| - -.. |pic_ocean_sf2| image:: /recipes/figures/ocean/stream_function2.png - - - -diagnostic_seaice.py --------------------------------- - - - -The diagnostic_seaice.py_ diagnostic is unique in this module, as it produces -several different kinds of images, including time series, maps, and contours. -It is a good example of a diagnostic where the preprocessor does very little -work, and the diagnostic does a lot of the hard work. - -This was done purposely, firstly to demonstrate the flexibility of ESMValTool, -and secondly because Sea Ice is a unique field where several Metrics can be -calculated from the sea ice cover fraction. - -The recipe Associated with with diagnostic is the recipe_SeaIceExtent.yml. -This recipe contains 4 preprocessors which all perform approximately the same -calculation. All four preprocessors extract a season: -- December, January and February (DJF) -- June, July and August (JJA) -and they also extract either the North or South hemisphere. The four -preprocessors are combinations of DJF or JJA and North or South hemisphere. - -One of the four preprocessors is North Hemisphere Winter ice extent: - -.. code-block:: yaml - - timeseries_NHW_ice_extent: # North Hemisphere Winter ice_extent - custom_order: true - extract_time: &time_anchor # declare time here. - start_year: 1960 - start_month: 12 - start_day: 1 - end_year: 2005 - end_month: 9 - end_day: 31 - extract_season: - season: DJF - extract_region: - start_longitude: -180. - end_longitude: 180. - start_latitude: 0. - end_latitude: 90. - -Note that the default settings for ESMValTool assume that the year starts on the -first of January. This causes a problem for this preprocessor, as the first -DJF season would not include the first Month, December, and the final would not -include both January and February. For this reason, we also add the -`extract_time` preprocessor. - -This preprocessor group produces a 2D field with a time component, allowing -the diagnostic to investigate the time development of the sea ice extend. - -The diagnostic section of the recipe should look like this: - -.. code-block:: yaml - - diag_ice_NHW: - description: North Hemisphere Winter Sea Ice diagnostics - variables: - sic: # surface ice cover - preprocessor: timeseries_NHW_ice_extent - field: TO2M - mip: OImon - scripts: - Global_seaice_timeseries: - script: ocean/diagnostic_seaice.py - threshold: 15. - -Note the the threshold here is 15%, which is the standard cut of for the -ice extent. - -The sea ice diagnostic script produces three kinds of plots, using the -methods: - -- `make_map_extent_plots`: extent maps plots of individual models using a Polar Stereographic project. -- `make_map_plots`: maps plots of individual models using a Polar Stereographic project. -- `make_ts_plots`: time series plots of individual models - -There are no multi model comparisons included here (yet). - - - -diagnostic_tools.py -------------------- - - - -The diagnostic_tools.py_ is a module that contains several python tools used -by the ocean diagnostics tools. - -These tools are: - -- folder: produces a directory at the path provided and returns a string. -- get_input_files: loads a dictionary from the input files in the metadata.yml. -- bgc_units: converts to sensible units where appropriate (ie Celsius, mmol/m3) -- timecoord_to_float: Converts time series to decimal time ie: Midnight on January 1st 1970 is 1970.0 -- add_legend_outside_right: a plotting tool, which adds a legend outside the axes. -- get_image_format: loads the image format, as defined in the global user config.yml. -- get_image_path: creates a path for an image output. -- make_cube_layer_dict: makes a dictionary for several layers of a cube. - -We just show a simple description here, each individual function is more fully -documented in the diagnostic_tools.py_ module. - - -A note on the auxiliary data directory -...................................... - -Some of these diagnostic scripts may not function on machines with no access -to the internet, as cartopy may try to download the shape files. The solution -to this issue is the put the relevant cartopy shapefiles in a directory which -is visible to esmvaltool, then link that path to ESMValTool via -the `auxiliary_data_dir` variable in your config-user.yml file. - -The cartopy masking files can be downloaded from: -https://www.naturalearthdata.com/downloads/ - - -In these recipes, cartopy uses the 1:10, physical coastlines and land files:: - - 110m_coastline.dbf - 110m_coastline.shp - 110m_coastline.shx - 110m_land.dbf - 110m_land.shp - 110m_land.shx - - -Associated Observational datasets -........................................ - -The following observations datasets are used by these recipes: - -World Ocean ATLAS ------------------ -These data can be downloaded from: -https://www.nodc.noaa.gov/OC5/woa13/woa13data.html -(last access 10/25/2018) -Select the "All fields data links (1° grid)" netCDF file, which contain all -fields. - -The following WOA datasets are used by the ocean diagnostics: - - Temperature - - Salinity - - Nitrate - - Phosphate - - Silicate - - Dissolved Oxygen - -These files need to be reformatted using the `cmorize_obs_py` script with output name `WOA`. - - -Landschutzer 2014 ------------------ -These data can be downloaded from: -ftp://ftp.nodc.noaa.gov/nodc/archive/arc0105/0160558/1.1/data/0-data/spco2_1998-2011_ETH_SOM-FFN_CDIAC_G05.nc -(last access 02/28/2019) - -The following variables are used by the ocean diagnostics: - - fgco2, Surface Downward Flux of Total CO2 - - spco2, Surface Aqueous Partial Pressure of CO2 - - dpco2, Delta CO2 Partial Pressure - -The file needs to be reformatted using the `cmorize_obs_py` script with output name `Landschutzer2014`. - - - -.. Links: - -.. Recipes: -.. _recipe_ocean_amoc.yml: https://github.com/ESMValGroup/ESMValTool/tree/version2_development/esmvaltool/recipes/recipe_ocean_amoc.yml -.. _recipe_ocean_example.yml: https://github.com/ESMValGroup/ESMValTool/tree/version2_development/esmvaltool/recipes/recipe_ocean_example.yml -.. _recipe_ocean_scalar_fields.yml: https://github.com/ESMValGroup/ESMValTool/tree/version2_development/esmvaltool/recipes/recipe_ocean_scalar_fields.yml -.. _recipe_ocean_bgc.yml: https://github.com/ESMValGroup/ESMValTool/tree/version2_development/esmvaltool/recipes/recipe_ocean_bgc.yml -.. _recipe_ocean_quadmap.yml: https://github.com/ESMValGroup/ESMValTool/tree/version2_development/esmvaltool/recipes/recipe_ocean_quadmap.yml -.. _recipe_ocean_Landschutzer2014.yml: https://github.com/ESMValGroup/ESMValTool/tree/version2_development/esmvaltool/recipes/recipe_ocean_Landschutzer2014.yml - -.. Diagnostics: -.. _ocean: https://github.com/ESMValGroup/ESMValTool/tree/version2_development/esmvaltool/diag_scripts/ocean/: -.. _diagnostic_maps.py: https://github.com/ESMValGroup/ESMValTool/tree/version2_development/esmvaltool/diag_scripts/ocean/diagnostic_maps.py -.. _diagnostic_maps_quad.py: https://github.com/ESMValGroup/ESMValTool/tree/version2_development/esmvaltool/diag_scripts/ocean/diagnostic_maps_quad.py -.. _diagnostic_model_vs_obs.py: https://github.com/ESMValGroup/ESMValTool/tree/version2_development/esmvaltool/diag_scripts/ocean/diagnostic_model_vs_obs.py -.. _diagnostic_profiles.py: https://github.com/ESMValGroup/ESMValTool/tree/version2_development/esmvaltool/diag_scripts/ocean/diagnostic_profiles.py -.. _diagnostic_timeseries.py: https://github.com/ESMValGroup/ESMValTool/tree/version2_development/esmvaltool/diag_scripts/ocean/diagnostic_timeseries.py -.. _diagnostic_transects.py: https://github.com/ESMValGroup/ESMValTool/tree/version2_development/esmvaltool/diag_scripts/ocean/diagnostic_transects.py -.. _diagnostic_seaice.py: https://github.com/ESMValGroup/ESMValTool/tree/version2_development/esmvaltool/diag_scripts/ocean/diagnostic_seaice.py -.. _diagnostic_tools.py: https://github.com/ESMValGroup/ESMValTool/tree/version2_development/esmvaltool/diag_scripts/ocean/diagnostic_tools.py diff --git a/doc/sphinx/source/recipes/recipe_perfmetrics.rst b/doc/sphinx/source/recipes/recipe_perfmetrics.rst deleted file mode 100644 index 81ea101d28..0000000000 --- a/doc/sphinx/source/recipes/recipe_perfmetrics.rst +++ /dev/null @@ -1,160 +0,0 @@ -.. _nml_perfmetrics: - -Performance metrics for essential climate parameters -==================================================== - -Overview --------- - -The goal is to create a standard recipe for the calculation of performance metrics to quantify the ability of the models to reproduce the climatological mean annual cycle for selected "Essential Climate Variables" (ECVs) plus some additional corresponding diagnostics and plots to better understand and interpret the results. - -The recipe can be used to calculate performance metrics at different vertical levels (e.g., 5, 30, 200, 850 hPa as in `Gleckler et al. (2008) `_ and in different regions. As an additional reference, we consider `Righi et al. (2015) `_. - -Available recipes and diagnostics ------------------------------------ - -Recipes are stored in recipes/ - -* recipe_perfmetrics_CMIP5.yml - -Diagnostics are stored in diag_scripts/perfmetrics/ - -* main.ncl: calculates and (optionally) plots annual/seasonal cycles, zonal means, lat-lon fields and time-lat-lon fields. The calculated fields can also be plotted as difference w.r.t. a given reference dataset. main.ncl also calculates RMSD, bias and taylor metrics. Input data have to be regridded to a common grid in the preprocessor. Each plot type is created by a separated routine, as detailed below. -* cycle.ncl: creates an annual/seasonal cycle plot. -* zonal.ncl: creates a zonal (lat-pressure) plot. -* latlon.ncl: creates a lat-lon plot. -* cycle_latlon.ncl: precalculates the metrics for a time-lat-lon field, with different options for normalization. -* collect.ncl: collects and plots the metrics previously calculated by cycle_latlon.ncl. - -User settings in recipe ------------------------ - -#. Script main.ncl - - *Required settings (scripts)* - - * plot_type: cycle (time), zonal (plev, lat), latlon (lat, lon), cycle_latlon (time, lat, lon), cycle_zonal (time, plev, lat) - * time_avg: type of time average (monthlyclim, seasonalclim, annualclim) - * region: selected region (global, trop, nhext, shext, nhtrop, shtrop, nh, sh, nhmidlat, shmidlat, nhpolar, shpolar, eq) - - *Optional settings (scripts)* - - * styleset: for plot_type cycle only (cmip5, righi15gmd, cmip6, default) - * plot_stddev: for plot_type cycle only, plots standard deviation as shading - * legend_outside: for plot_type cycle only, plots the legend in a separate file - * t_test: for plot_type zonal or latlon, calculates t-test in difference plots (default: False) - * conf_level: for plot_type zonal or latlon, adds the confidence level for the t-test to the plot (default: False) - * projection: map projection for plot_type latlon (default: CylindricalEquidistant) - * plot_diff: draws difference plots (default: False) - * calc_grading: calculates grading metrics (default: False) - * stippling: uses stippling to mark statistically significant differences (default: False = mask out non-significant differences in gray) - * show_global_avg: diplays the global avaerage of the input field as string at the top-right of lat-lon plots (default: False) - * metric: chosen grading metric(s) (if calc_grading is True) - * normalization: metric normalization (for RMSD and BIAS metrics only) - * abs_levs: list of contour levels for absolute plot - * diff_levs: list of contour levels for difference plot - * zonal_cmap: for plot_type zonal only, chosen color table (default: "amwg_blueyellowred") - * zonal_ymin: for plot_type zonal only, minimum pressure level on the y-axis (default: 5. hPa) - * latlon_cmap: for plot_type latlon only, chosen color table (default: "amwg_blueyellowred") - * plot_units: plotting units (if different from standard CMOR units) - - *Required settings (variables)* - - * reference_dataset: reference dataset to compare with (usually the observations). - - *Optional settings (variables)* - - * alternative_dataset: a second dataset to compare with. - - These settings are passed to the other scripts by main.ncl, depending on the selected plot_type. - -#. Script collect.ncl - - *Required settings (scripts)* - - * metric: selected metric (RMSD, BIAS or taylor) - * label_bounds: for RMSD and BIAS metrics, min and max of the labelbar - * label_scale: for RMSD and BIAS metrics, bin width of the labelbar - * colormap: for RMSD and BIAS metrics, color table of the labelbar - - *Optional settings (scripts)* - - * label_lo: adds lower triange for values outside range - * label_hi: adds upper triange for values outside range - * cm_interval: min and max color of the color table - * cm_reverse: reverses the color table - * sort: sorts datasets in alphabetic order (excluding MMM) - * diag_order: sort diagnostics in a specific order (name = 'diagnostic'-'region') - * title: plots title - * scale_font: scaling factor applied to the default font size - * disp_values: switches on/off the grading values on the plot - * disp_rankings: switches on/off the rankings on the plot - * rank_order: displays rankings in increasing (1) or decreasing (-1) order - -Variables ---------- - -* clt (atmos, monthly mean, longitude latitude time) -* hus (atmos, monthly mean, longitude latitude lev time) -* od550aer, od870aer, od550abs, od550lt1aer (aero, monthly mean, longitude latitude time) -* pr (atmos, monthly mean, longitude latitude time) -* rlut, rlutcs, rsut, rsutcs (atmos, monthly mean, longitude latitude time) -* sm (land, monthly mean, longitude latitude time) -* ta (atmos, monthly mean, longitude latitude lev time) -* tas (atmos, monthly mean, longitude latitude time) -* toz (atmos, monthly mean, longitude latitude time) -* ts (atmos, monthly mean, longitude latitude time) -* ua (atmos, monthly mean, longitude latitude lev time) -* va (atmos, monthly mean, longitude latitude lev time) -* zg (atmos, monthly mean, longitude latitude lev time) - -Observations and reformat scripts ---------------------------------- - -*Note: (1) obs4mips data can be used directly without any preprocessing; (2) see headers of cmorization scripts (in esmvaltool/utils/cmorizers/obs) for non-obs4mips data for download instructions.* - -* AIRS (hus - obs4mips) -* CERES-EBAF (rlut, rlutcs, rsut, rsutcs - obs4mips) -* ERA-Interim (tas, ta, ua, va, zg, hus - esmvaltool/utils/cmorizers/obs/cmorize_obs_ERA-Interim.ncl) -* ESACCI-AEROSOL (od550aer, od870aer, od550abs, od550lt1aer - esmvaltool/utils/cmorizers/obs/cmorize_obs_ESACCI-AEROSOL.ncl) -* ESACCI-CLOUD (clt - esmvaltool/utils/cmorizers/obs/cmorize_obs_ESACCI-CLOUD.ncl) -* ESACCI-OZONE (toz - esmvaltool/utils/cmorizers/obs/cmorize_obs_ESACCI-OZONE.ncl) -* ESACCI-SOILMOISTURE (sm - esmvaltool/utils/cmorizers/obs/cmorize_obs_ESACCI-SOILMOISTURE.ncl) -* ESACCI-SST (ts - esmvaltool/utils/cmorizers/obs/cmorize_obs_ESACCI-SST.ncl) -* GPCP-SG (pr - obs4mips) -* HadISST (ts - esmvaltool/utils/cmorizers/obs/cmorize_obs_HadISST.ncl) -* MODIS (od550aer - esmvaltool/utils/cmorizers/obs/cmorize_obs_MODIS.ncl) -* NCEP (tas, ta, ua, va, zg - esmvaltool/utils/cmorizers/obs/cmorize_obs_NCEP.ncl) -* NIWA-BS (toz - esmvaltool/utils/cmorizers/obs/cmorize_obs_NIWA-BS.ncl) -* PATMOS-x (clt - esmvaltool/utils/cmorizers/obs/cmorize_obs_PATMOS-x.ncl) - -References ----------- - -* Gleckler, P. J., K. E. Taylor, and C. Doutriaux, Performance metrics for climate models, J. Geophys. Res., 113, D06104, doi: 10.1029/2007JD008972 (2008). - -* Righi, M., Eyring, V., Klinger, C., Frank, F., Gottschaldt, K.-D., Jöckel, P., and Cionni, I.: Quantitative evaluation of oone and selected climate parameters in a set of EMAC simulations, Geosci. Model Dev., 8, 733, doi: 10.5194/gmd-8-733-2015 (2015). - -Example plots -------------- - -.. centered:: |pic_permetrics1| |pic_permetrics2| - -.. |pic_permetrics1| image:: /recipes/figures/perfmetrics/perfmetrics_fig_1.png - :width: 50% - -.. |pic_permetrics2| image:: /recipes/figures/perfmetrics/perfmetrics_fig_2.png - :width: 30% - -.. centered:: |pic_permetrics3| |pic_permetrics4| - -.. |pic_permetrics3| image:: /recipes/figures/perfmetrics/perfmetrics_fig_3.png - :width: 30% - -.. |pic_permetrics4| image:: /recipes/figures/perfmetrics/perfmetrics_fig_4.png - :width: 52% - -.. figure:: /recipes/figures/perfmetrics/perfmetrics_fig_5.png - :width: 75% - :align: center - diff --git a/doc/sphinx/source/recipes/recipe_quantilebias.rst b/doc/sphinx/source/recipes/recipe_quantilebias.rst deleted file mode 100644 index 0d72457bba..0000000000 --- a/doc/sphinx/source/recipes/recipe_quantilebias.rst +++ /dev/null @@ -1,46 +0,0 @@ -Precipitation quantile bias -=========================== - - -Overview --------- - -Precipitation is a dominant component of the hydrological cycle, and as such a main driver of the climate system and human development. The reliability of climate projections and water resources strategies therefore depends on how well precipitation can be reproduced by the models used for simulations. While global circulation models from the CMIP5 project observations can reproduce the main patterns of mean precipitation, they often show shortages and biases in the ability to reproduce the strong precipitation tails of the distribution. Most models underestimate precipitation over arid regions and overestimate it over regions of complex topography, and these shortages are amplified at high quantile precipitation. The quantilebias recipe implements calculation of the quantile bias to allow evaluation of the precipitation bias based on a user defined quantile in models as compared to a reference dataset following Mehran et al. (2014). The quantile bias (QB) is defined as the ratio of monthly precipitation amounts in each simulation to that of the reference dataset (GPCP observations in the example) above a specified threshold t (e.g., the 75th percentile of all the local monthly values). A quantile bias equal to 1 indicates no bias in the simulations, whereas a value above (below) 1 corresponds to a climate model's overestimation (underestimation) of the precipitation amount above the specified threshold t, with respect to that of the reference dataset. - - -Available recipes and diagnostics ---------------------------------- - -Recipes are stored in recipes/ - -* recipe_quantilebias.yml - -Diagnostics are stored in diag_scripts/quantilebias/ - -* quantilebias.R - - -User settings -------------- - -*Required settings for script* - -* perc_lev: quantile (in %), e.g. 50 - - -Variables ---------- - -* pr (atmos, monthly, longitude latitude time) - - -Observations and reformat scripts ---------------------------------- - -* GPCP-SG observations (accessible via the obs4mips project) - - -References ----------- - -* Mehran, A. et al.: Journal of Geophysical Research: Atmospheres, Volume 119, Issue 4, pp. 1695-1707, 2014. diff --git a/doc/sphinx/source/recipes/recipe_rainfarm.rst b/doc/sphinx/source/recipes/recipe_rainfarm.rst deleted file mode 100644 index 8c12734409..0000000000 --- a/doc/sphinx/source/recipes/recipe_rainfarm.rst +++ /dev/null @@ -1,53 +0,0 @@ -RainFARM stochastic downscaling -=============================== - - -Overview --------- - -Precipitation extremes and small-scale variability are essential drivers in many climate change impact studies. However, the spatial resolution currently achieved by global and regional climate models is still insufficient to correctly identify the fine structure of precipitation intensity fields. In the absence of a proper physically based representation, this scale gap can be at least temporarily bridged by adopting a stochastic rainfall downscaling technique (Rebora et al, 2006). With this aim, the Rainfall Filtered Autoregressive Model (RainFARM)was developed to apply the stochastic precipitation downscaling method to climate models. The RainFARM Julia library and command-line tool version (https://github.com/jhardenberg/RainFARM.jl) was implemented as recipe. The stochastic method allows to predict climate variables at local scale from information simulated by climate models at regional scale: It first evaluates the statistical distribution of precipitation fields at regional scale and then applies the relationship to the boundary conditions of the climate model to produce synthetic fields at the requested higher resolution. RainFARM exploits the nonlinear transformation of a Gaussian random precipitation field, conserving the information present in the fields at larger scale (Rebora et al., 2006; D’Onofrio et al., 2014). - - -Available recipes and diagnostics ---------------------------------- - -Recipes are stored in recipes/ - -* recipe_rainfarm.yml - -Diagnostics are stored in diag_scripts/rainfarm/ - -* rainfarm.R - - -User settings -------------- - -*Required settings for script* - -* slope: spatial spectral slope (set to 0 to compute automatically from large scales) -* nens: number of ensemble members to be calculated -* nf: number of subdivisions for downscaling (e.g. 8 will produce output fields with linear resolution increased by a factor 8) -* conserv_glob: logical, if to conserve precipitation over full domain -* conserv_smooth: logical, if to conserve precipitation using convolution (if neither conserv_glob or conserv_smooth is chosen, box conservation is used) -* weights_climo: set to false if no orographic weights are to be used, else set it to the full path to a fine-scale precipitation climatology file. The file is expected to be in NetCDF format and should contain at least one precipitation field. If several fields at different times are provided, a climatology is derived by time averaging. Suitable climatology files could be for example a fine-scale precipitation climatology from a high-resolution regional climate model (see e.g. Terzago et al. 2018), a local high-resolution gridded climatology from observations, or a reconstruction such as those which can be downloaded from the WORLDCLIM (http://www.worldclim.org) or CHELSA (http://chelsa-climate.org) websites. The latter data will need to be converted to NetCDF format before being used (see for example the GDAL tools (https://www.gdal.org). - - -Variables ---------- - -* pr (atmos, daily mean, longitude latitude time) - - -Observations and reformat scripts ---------------------------------- - -None. - - -References ----------- - -* Terzago et al. 2018, Nat. Hazards Earth Syst. Sci., 18, 2825-2840 -* D'Onofrio et al. 2014, J of Hydrometeorology 15, 830-843 -* Rebora et. al 2006, JHM 7, 724 diff --git a/doc/sphinx/source/recipes/recipe_runoff_et.rst b/doc/sphinx/source/recipes/recipe_runoff_et.rst deleted file mode 100644 index 3ce3fdc5bb..0000000000 --- a/doc/sphinx/source/recipes/recipe_runoff_et.rst +++ /dev/null @@ -1,130 +0,0 @@ -Runoff_ET -========= - -Overview --------- -This diagnostic calculates biases of long-term climatological annual means of total runoff R, -precipitation P and evapotranspiration E for 12 large-scale catchments on different continents -and climates. For total runoff, catchment averaged model values are compared to climatological -GRDC station observations of river runoff (Duemenil Gates et al., 2000). Due to the incompleteness -of these station data, a year-to-year correspondence of data cannot be achieved in a generalized way, -so that only climatological data are considered, such it has been done in Hagemann, et al. (2013). -For precipitation, catchment-averaged WFDEI precipitation data (Weedon et al., 2014) from 1979-2010 -is used as reference. For evapotranspiration, observations are estimated using the difference of the -above mentioned precipitation reference minus the climatological GRDC river runoff. - -The catchments are Amazon, Congo, Danube, Ganges-Brahmaputra, Lena, Mackenzie, Mississippi, Murray, -Niger, Nile, Parana and Yangtze-Kiang. Variable names are expected to follow CMOR standard, e.g. -precipitation as pr, total runoff as mrro and evapotranspiration as evspsbl with all fluxes given in -kg m-2 s-1 . Evapotranspiration furthermore has to be defined positive upwards. - -The diagnostic produces text files with absolute and relative bias to the observations, as well as the -respective absolute values. Furthermore it creates a bar plot for relative and absolute bias, -calculates and plots biases in runoff coefficient (R/P) and evapotranspiration coefficient (E/P) and -saves everything as one pdf file per model or one png file per model and analysis. - -The bias of the runoff coefficient is calculated via: -:math:`C_R = \frac{R_{model}}{P_{model}} - \frac{R_{GRDC}}{P_{WFDEI}}` and similar for the -evapotranspiration coefficient. In a very first approximation, evapotranspiration -and runoff are determined only by precipitation. In other words :math:`R = P - E`. Hence, the runoff coefficient -(and similar the evapotranspiration coefficient) tells you how important runoff (or evapotranspiration) -is in this region. By plotting the bias of the runoff coefficient against the evapotranspiration coefficient -we can immediately see whether there is a shift from runoff to evapotranspiration. On the other hand, by -plotting the bias of the runoff coefficient against the relative bias of precipitation we can see whether -an error in runoff is due to an error in precipitation. - - -Available recipes and diagnostics ---------------------------------- - -Recipes are stored in recipes/ - - * recipe_runoff_et.yml - -Diagnostics are stored in diag_scripts/runoff_et/ - - * catchment_analysis.py: bar and scatter plots for catchment averages of - runoff, evapotranspiration and precipitation - - -User settings in recipe ------------------------ - -#. Script catchment_analysis.py - - *Required settings (scripts)* - - * catchmentmask: netCDF file indicating the grid cell for a specific catchment. Modus of - distribution not yet clearified. ESGF? - - *Optional settings (variables)* - - * reference_dataset: dataset_name - Datasets can be used as reference instead of defaults provided with the diagnostics. - Must be identical for all variables. - - -Variables ---------- - -* evspsbl (atmos, monthly mean, time latitude longitude) -* pr (atmos, monthly mean, time latitude longitude) -* mrro (land, monthly mean, time latitude longitude) - - -Observations and reformat scripts ---------------------------------- - -Default reference data based on GRDC and WFDEI are included in the diagnostic script -as catchment averages. They can be replaced with any gridded dataset by defining a -reference_dataset. The necessary catchment mask is available at - -.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.2025776.svg - :target: https://doi.org/10.5281/zenodo.2025776 - -All other datasets are remapped onto the catchment mask grid as part -of the diagnostics. - - -References ----------- -* Duemenil Gates, L., S. Hagemann and C. Golz, - Observed historical discharge data from major rivers for climate model validation. - Max Planck Institute for Meteorology Report 307, Hamburg, Germany, 2000. - -* Hagemann, S., A. Loew, A. Andersson, - Combined evaluation of MPI-ESM land surface water and energy fluxes - J. Adv. Model. Earth Syst., 5, doi:10.1029/2012MS000173, 2013. - -* Weedon, G. P., G. Balsamo, N. Bellouin, S. Gomes, M. J. Best, and P. Viterbo, - The WFDEI meteorological forcing data set: WATCH Forcing Data methodology applied - to ERA‐Interim reanalysis data, - Water Resour. Res., 50, 7505–7514, doi: 10.1002/2014WR015638, 2014 - - -Example plots -------------- - -.. _fig_runoff_et_1: -.. figure:: /recipes/figures/runoff_et/catchments.png - :align: center - :width: 14cm - - Catchment definitions used in the diagnostics. - -.. _fig_runoff_et_2: -.. figure:: /recipes/figures/runoff_et/MPI-ESM-LR_historical_r1i1p1_bias-plot_mrro.png - :align: center - :width: 14cm - - Barplot indicating the absolute and relative bias in annual runoff between MPI-ESM-LR (1970-2000) - and long term GRDC data for specific catchments. - -.. _fig_runoff_et_3: -.. figure:: /recipes/figures/runoff_et/MPI-ESM-LR_historical_r1i1p1_rocoef-vs-relprbias.png - :align: center - :width: 14cm - - Biases in runoff coefficient (runoff/precipitation) and precipitation for major catchments of - the globe. The MPI-ESM-LR historical simulation (1970-2000) is used as an example. - diff --git a/doc/sphinx/source/recipes/recipe_shapeselect.rst b/doc/sphinx/source/recipes/recipe_shapeselect.rst deleted file mode 100644 index 91be26c549..0000000000 --- a/doc/sphinx/source/recipes/recipe_shapeselect.rst +++ /dev/null @@ -1,42 +0,0 @@ -Shapeselect -=========== - -Overview --------- -Impact modelers are often interested in data for irregular regions best defined by a shapefile. With the shapefile selector tool, the user can extract time series or CII data for a user defined region. The region is defined by a user provided shapefile that includes one or several polygons. For each polygon, a new timeseries, or CII, is produced with only one time series per polygon. The spatial information is reduced to a representative point for the polygon ('representative') or as an average of all grid points within the polygon boundaries ('mean_inside'). If there are no grid points strictly inside the polygon, the 'mean_inside' method defaults to 'representative' for that polygon. An option for displaying the grid points together with the shapefile polygon allows the user to assess which method is most optimal. In case interpolation to a high input grid is necessary, this can be provided in a pre-processing stage. Outputs are in the form of a NetCDF file, or as ascii code in csv format. - - -Available recipes and diagnostics ---------------------------------- - -Recipes are stored in recipes/ - - * recipe_shapeselect.yml - - -Diagnostics are stored in diag_scripts/shapeselect/ - - * diag_shapeselect.py: calculate the average of grid points inside the - user provided shapefile and returns the result as a NetCDF or Excel sheet. - - -User settings in recipe ------------------------ - -#. Script diag_shapeselect.py - - *Required settings (scripts)* - - * shapefile: path to the user provided shapefile. A relative path is relative to the auxiliary_data_dir as configured in config-user.yml. - - * weighting_method: the preferred weighting method 'mean_inside' - mean of all grid points inside polygon; 'representative' - one point inside or close to the polygon is used to represent the complete area. - - * write_xlsx: true or false to write output as Excel sheet or not. - - * write_netcdf: true or false to write output as NetCDF or not. - -Variables ---------- - -* pr,tas (daily) - diff --git a/doc/sphinx/source/recipes/recipe_smpi.rst b/doc/sphinx/source/recipes/recipe_smpi.rst deleted file mode 100644 index c0f8cb0f31..0000000000 --- a/doc/sphinx/source/recipes/recipe_smpi.rst +++ /dev/null @@ -1,90 +0,0 @@ -Single Model Perfomance Index (SMPI) -==================================== - -Overview --------- - -This diagnostic calculates the Single Model Performance Index (SMPI) following Reichler and Kim (2008). The SMPI (called "I\ :sup:`2`") is based on the comparison of several different climate variables (atmospheric, surface and oceanic) between climate model simulations and observations or reanalyses, and it focuses on the validation of the time-mean state of climate. For I\ :sup:`2` to be determined, the differences between the climatological mean of each model variable and observations at each of the available data grid points are calculated, and scaled to the interannual variance from the validating observations. This interannual variability is determined by performing a bootstrapping method (random selection with replacement) for the creation of a large synthetic ensemble of observational climatologies. The results are then scaled to the average error from a reference ensemble of models, and in a final step the mean over all climate variables and one model is calculated. The plot shows the I\ :sup:`2` values for each model (orange circles) and the multi-model mean (black circle), with the diameter of each circle representing the range of I\ :sup:`2` values encompassed by the 5th and 95th percentiles of the bootstrap ensemble. The I\ :sup:`2` values vary around one, with values greater than one for underperforming models, and values less than one for more accurate models. - -Note: The SMPI diagnostic needs all indicated variables from all added models for exactly the same time period to be calculated correctly. If one model does not provide a specific variable, either that model cannot be added to the SMPI calculations, or the missing variable has to be removed from the diagnostics all together. - -Available recipes and diagnostics ------------------------------------ - -Recipes are stored in recipes/ - -* recipe_smpi.yml -* recipe_smpi_4cds.yml - -Diagnostics are stored in diag_scripts/perfmetrics/ - -* main.ncl: calculates and (optionally) plots annual/seasonal cycles, zonal means, lat-lon fields and time-lat-lon fields. The calculated fields can also be plotted as difference w.r.t. a given reference dataset. main.ncl also calculates RMSD, bias and taylor metrics. Input data have to be regridded to a common grid in the preprocessor. Each plot type is created by a separated routine, as detailed below. -* cycle_zonal.ncl: calculates single model perfomance index (Reichler and Kim, 2008). It requires fields precalculated by main.ncl. -* collect.ncl: collects the metrics previously calculated by cycle_latlon.ncl and passes them to the plotting functions. - -User settings -------------- - -#. perfmetrics/main.ncl - - *Required settings for script* - - * plot_type: only "cycle_latlon (time, lat, lon)" and "cycle_zonal (time, plev, lat)" available for SMPI; usage is defined in the recipe and is dependent on the used variable (2D variable: cycle_latlon, 3D variable: cycle_zonal) - * time_avg: type of time average (only "yearly" allowed for SMPI, any other settings are not supported for this diagnostic) - * region: selected region (only "global" allowed for SMPI, any other settings are not supported for this diagnostic) - * normalization: metric normalization ("CMIP5" for analysis of CMIP5 simulations; to be adjusted accordingly for a different CMIP phase) - * calc_grading: calculates grading metrics (has to be set to "true" in the recipe) - * metric: chosen grading metric(s) (if calc_grading is True; has to be set to "SMPI") - * smpi_n_bootstrap: number of bootstrapping members used to determine uncertainties on model-reference differences (typical number of bootstrapping members: 100) - - *Required settings for variables* - - * reference_dataset: reference dataset to compare with (usually the observations). - -These settings are passed to the other scripts by main.ncl, depending on the selected plot_type. - -#. collect.ncl - - *Required settings for script* - - * metric: selected metric (has to be "SMPI") - - -Variables ---------- - -* hfds (ocean, monthly mean, longitude latitude time) -* hus (atmos, monthly mean, longitude latitude lev time) -* pr (atmos, monthly mean, longitude latitude time) -* psl (atmos, monthly mean, longitude latitude time) -* sic (ocean-ice, monthly mean, longitude latitude time) -* ta (atmos, monthly mean, longitude latitude lev time) -* tas (atmos, monthly mean, longitude latitude time) -* tauu (atmos, monthly mean, longitude latitude time) -* tauv (atmos, monthly mean, longitude latitude time) -* tos (ocean, monthly mean, longitude latitude time) -* ua (atmos, monthly mean, longitude latitude lev time) -* va (atmos, monthly mean, longitude latitude lev time) - - -Observations and reformat scripts ---------------------------------- - -*Note: (1) obs4mips data can be used directly without any preprocessing; (2) see headers of reformat scripts for non-obs4mips data for download instructions.* - -* ERA-Interim (hfds, hus, psl, ta, tas, tauu, tauv, ua, va - esmvaltool/utils/cmorizers/obs/cmorize_obs_ERA-Interim.ncl) -* HadISST (sic, tos - reformat_scripts/obs/reformat_obs_HadISST.ncl) -* GPCP-SG (pr - obs4mips) - -References ----------- - -* Reichler, T. and J. Kim, How well do coupled models simulate today's climate? Bull. Amer. Meteor. Soc., 89, 303-311, doi: 10.1175/BAMS-89-3-303, 2008. - -Example plots -------------- - -.. figure:: /recipes/figures/smpi/reichlerkim08bams_smpi.png - :width: 70 % - - Performance index I\ :sup:`2` for individual models (circles). Circle sizes indicate the length of the 95% confidence intervals. The black circle indicates the I\ :sup:`2` of the multi-model mean (similar to Reichler and Kim (2008), Figure 1). diff --git a/doc/sphinx/source/recipes/recipe_spei.rst b/doc/sphinx/source/recipes/recipe_spei.rst deleted file mode 100644 index ff71c4a594..0000000000 --- a/doc/sphinx/source/recipes/recipe_spei.rst +++ /dev/null @@ -1,77 +0,0 @@ -SPEI -==== - -Overview --------- -Droughts can be separated into three main types: meteorological, hydrological, and agricultural drought. - -Common for all types is that a drought needs to be put in context of local and seasonal characteristics, i.e. a drought should not be defined with an absolute threshold, but as an anomalous condition. - -Meteorological droughts are often described using the standardized precipitation index (SPI; McKee et al, 1993), which in a standardized way describes local precipitation anomalies. It is calculated on monthly mean precipitation, and is therefore not accounting for the intensity of precipitation and the runoff process. Because SPI does not account for evaporation from the ground, it lacks one component of the water fluxes at the surface and is therefore not compatible with the concept of hydrological drought. - -A hydrological drought occurs when low water supply becomes evident, especially in streams, reservoirs, and groundwater levels, usually after extended periods of meteorological drought. GCMs normally do not simulate hydrological processes in sufficient detail to give deeper insights into hydrological drought processes. Neither do they properly describe agricultural droughts, when crops become affected by the hydrological drought. However, hydrological drought can be estimated by accounting for evapotranspiration, and thereby estimate the surface retention of water. The standardized precipitation-evapotranspiration index (SPEI; Vicente-Serrano et al., 2010) has been developed to also account for temperature effects on the surface water fluxes. Evapotranspiration is not normally calculated in GCMs, so SPEI often takes other inputs to estimate the evapotranspiration. Here, the Thornthwaite (Thornthwaite, 1948) method based on temperature is applied. - - -Available recipes and diagnostics ---------------------------------- - -Recipes are stored in recipes/ - - * recipe_spei.yml - - -Diagnostics are stored in diag_scripts/droughtindex/ - - * diag_spi.r: calculate the SPI index - - * diag_spei.r: calculate the SPEI index - - -User settings -------------- - -#. Script diag_spi.py - - *Required settings (script)* - - * reference_dataset: dataset_name - The reference data set acts as a baseline for calculating model bias. - -#. Script diag_spei.py - - *Required settings (script)* - - * reference_dataset: dataset_name - The reference data set acts as a baseline for calculating model bias. - - -Variables ---------- - -* pr (atmos, monthly mean, time latitude longitude) -* tas (atmos, monthly mean, time latitude longitude) - - -References ----------- -* McKee, T. B., Doesken, N. J., & Kleist, J. (1993). The relationship of drought frequency and duration to time scales. In Proceedings of the 8th Conference on Applied Climatology (Vol. 17, No. 22, pp. 179-183). Boston, MA: American Meteorological Society. - -* Vicente-Serrano, S. M., Beguería, S., & López-Moreno, J. I. (2010). A multiscalar drought index sensitive to global warming: the standardized precipitation evapotranspiration index. Journal of climate, 23(7), 1696-1718. - - -Example plots -------------- - -.. _fig_spei: -.. figure:: /recipes/figures/spei/histogram_spei.png - :align: center - :width: 14cm - - (top) Probability distribution of the standardized precipitation-evapotranspiration index of a sub-set of the CMIP5 models, and (bottom) bias relative to the CRU reference data set. - -.. _fig_spi: -.. figure:: /recipes/figures/spei/histogram_spi.png - :align: center - :width: 14cm - - (top) Probability distribution of the standardized precipitation index of a sub-set of the CMIP5 models, and (bottom) bias relative to the CRU reference data set. diff --git a/doc/sphinx/source/recipes/recipe_template.rst.template b/doc/sphinx/source/recipes/recipe_template.rst.template deleted file mode 100644 index 99bef29df5..0000000000 --- a/doc/sphinx/source/recipes/recipe_template.rst.template +++ /dev/null @@ -1,75 +0,0 @@ -Title -===== - -Overview --------- - -Brief description of the diagnostic. - - -Available recipes and diagnostics ---------------------------------- - -Recipes are stored in esmvaltool/recipes/ - - * recipe_.yml - -Diagnostics are stored in esmvaltool/diag_scripts// - - * : one line scription - - -User settings in recipe ------------------------ - -#. Script - - *Required settings for script* - - * xxx: zzz - - *Optional settings for script* - - *Required settings for variables* - - *Optional settings for variables* - - *Required settings for preprocessor* - - *Optional settings for preprocessor* - - *Color tables* - - * list required color tables (if any) here - - -Variables ---------- - -* var1 (realm, frequency, dimensions), e.g. pr (atmos, monthly mean, longitude latitude time) - - -Observations and reformat scripts ---------------------------------- - -*Note: (1) obs4mips data can be used directly without any preprocessing; -(2) see headers of reformat scripts for non-obs4mips data for download -instructions.* - -* xxx - - *Reformat script:* - -References ----------- - -* xxx - -Example plots -------------- - -.. _fig_mynewdiag_1: -.. figure:: /recipes/figures//awesome1.png - :align: center - - Add figure caption here. diff --git a/doc/sphinx/source/recipes/recipe_thermodyn_diagtool.rst b/doc/sphinx/source/recipes/recipe_thermodyn_diagtool.rst deleted file mode 100644 index da8352b37b..0000000000 --- a/doc/sphinx/source/recipes/recipe_thermodyn_diagtool.rst +++ /dev/null @@ -1,123 +0,0 @@ -TheDiaTo v1.0 - A Diagnostic Tool for the Thermodynamics of the Climate System -============================================================================== - -Overview --------- - -The tool allows to compute TOA, atmospheric and surface energy budgets, latent energy and water mass budgets, -meridional heat transports, the Lorenz Energy Cycle (LEC), the material entropy production with the direct -and indirect method. - -The energy budgets are computed from monthly mean radiative and heat fluxes at the TOA and at the surface -(cfr. Wild et al., 2013). The meridional heat transports are obtained from the latitudinal integration -of the zonal mean energy budgets. When a land-sea mask is provided, results are also available for -land and oceans, separately. - -The water mass budget is obtained from monthly mean latent heat fluxes (for evaporation), total and snowfall -precipitation (cfr. Liepert et al., 2012). The latent energy budget is obtained multiplying each component of -the water mass budget by the respective latent heat constant. When a land-sea mask is provided, results are -also available for land and oceans, separately. - -The LEC is computed from 3D fields of daily mean velocity and temperature fields in the troposphere over -pressure levels. The analysis is carried on in spectral fields, converting lonlat grids in Fourier coefficients. -The components of the LEC are computed as in Ulbrich and Speth, 1991. In order to account for possible gaps -in pressure levels, the daily fields of 2D near-surface temperature and horizontal velocities. - -The material entropy production is computed by using the indirect or the direct method (or both). The former -method relies on the convergence of radiative heat in the atmosphere (cfr. Lucarini et al., 2011; Pascale et al., 2011), -the latter on all viscous and non-viscous dissipative processes occurring in the atmosphere -(namely the sensible heat fluxes, the hydrological cycle with its components and the kinetic energy dissipation). - -For a comprehensive report on the methods used and some descriptive results, please refer to Lembo et al., 2019. - - - -Available recipes and diagnostics ---------------------------------- - -Recipes are stored in recipes/ - - * recipe_thermodyn_diagtool.yml - -Diagnostics are stored in diag_scripts/thermodyn_diagtool/ - - * thermodyn_diagnostics.py: the main script, handling input files, calling computation and plotting scricpts; - - * computations.py: a module containing all the main computations that are carried out by the program; - - * fluxogram.py: a module for the retrieval of the block diagrams displaying the reservoirs and conversion terms of the LEC - - * fourier_coefficients.py: a module for the computation of the Fourier coefficients from the lonlat input grid - - * lorenz_cycle.py: a module for the computation of the LEC components in Fourier coefficients - - * mkthe.py: a module for the computation of indirect variables obtained from the input fields, such as LCL height, boundary layer top height and temperature, potential temperature - - * plot_script.py: a module for the computation of maps, scatter plots, time series and meridional sections of some derived quantities for each model in the ensemble. The meridional heat and water mass transports are also computed here, as well as the peak magnitudes and locations; - - * provenance_meta.py: a module for collecting metadata and writing them to produced outputs; - -User settings -------------- - -Besides the datasets, to be set according to usual ESMValTool convention, the user can set the following optional variables in the recipe_Thermodyn_diagtool.yml: - - * wat: if set to 'true', computations are performed of the water mass and latent energy budgets and transports - * lsm: if set to true, the computations of the energy budgets, meridional energy transports, water mass and latent energy budgets and transports are performed separately over land and oceans - * lec: if set to 'true', computation of the LEC are performed - * entr: if set to 'true', computations of the material entropy production are performed - * met (1, 2 or 3): the computation of the material entropy production must be performed with the indirect method (1), the direct method (2), or both methods. If 2 or 3 options are chosen, the intensity of the LEC is needed for the entropy production related to the kinetic energy dissipation. If lec is set to 'false', a default value is provided. - - These options apply to all models provided for the multi-model ensemble computations - - -Variables ---------- - -* hfls (atmos, monthly mean, time latitude longitude) -* hfss (atmos, monthly mean, time latitude longitude) -* hus (atmos, monthly mean, time plev latitude longitude) -* pr (atmos, monthly mean, time latitude longitude) -* prsn (atmos, monthly mean, time latitude longitude) -* ps (atmos, monthly mean, time latitude longitude) -* rlds (atmos, monthly mean, time latitude longitude) -* rlus (atmos, monthly mean, time latitude longitude) -* rlut (atmos, monthly mean, time latitude longitude) -* rsds (atmos, monthly mean, time latitude longitude) -* rsdt (atmos, monthly mean, time latitude longitude) -* rsus (atmos, monthly mean, time latitude longitude) -* rsut (atmos, monthly mean, time latitude longitude) -* ta (atmos, daily mean, time plev latitude longitude) -* tas (atmos, daily mean, time latitude longitude) -* ts (atmos, monthly mean, time latitude longitude) -* ua (atmos, daily mean, time plev latitude longitude) -* uas (atmos, daily mean, time latitude longitude) -* va (atmos, daily mean, time plev latitude longitude) -* vas (atmos, daily mean, time latitude longitude) -* wap (atmos, daily mean, time plev latitude longitude) - - -References ----------- -* Lembo V, Lunkeit F, Lucarini V (2019) A new diagnostic tool for diagnosing water, energy and entropy budgets in climate models. Geophys Mod Dev Disc. doi:10.5194/gmd-2019-37. in review. -* Liepert BG, Previdi M (2012) Inter-model variability and biases of the global water cycle in CMIP3 coupled climate models. Environ Res Lett 7:014006. doi: 10.1088/1748-9326/7/1/014006 -* Lorenz EN (1955) Available Potential Energy and the Maintenance of the General Circulation. Tellus 7:157–167. doi: 10.1111/j.2153-3490.1955.tb01148.x -* Lucarini V, Fraedrich K, Ragone F (2010) New Results on the Thermodynamical Properties of the Climate System. J Atmo 68:. doi: 10.1175/2011JAS3713.1 -* Lucarini V, Blender R, Herbert C, et al (2014) Reviews of Geophysics Mathematical and physical ideas for climate science. doi: 10.1002/2013RG000446 -* Pascale S, Gregory JM, Ambaum M, Tailleux R (2011) Climate entropy budget of the HadCM3 atmosphere–ocean general circulation model and of FAMOUS, its low-resolution version. Clim Dyn 36:1189–1206. doi: 10.1007/s00382-009-0718-1 -* Ulbrich U, Speth P (1991) The global energy cycle of stationary and transient atmospheric waves: Results from ECMWF analyses. Meteorol Atmos Phys 45:125–138. doi: 10.1007/BF01029650 -* Wild M, Folini D, Schär C, et al (2013) The global energy balance from a surface perspective. Clim Dyn 40:3107–3134. doi: 10.1007/s00382-012-1569-8 - - -Example plots -------------- - -.. _fig_1: -.. figure:: /recipes/figures/thermodyn_diagtool/meridional_transp.png - :align: left - :width: 14cm - -.. _fig_2: -.. figure:: /recipes/figures/thermodyn_diagtool/CanESM2_wmb_transp.png - :align: right - :width: 14cm diff --git a/doc/sphinx/source/recipes/recipe_toymodel.rst b/doc/sphinx/source/recipes/recipe_toymodel.rst deleted file mode 100644 index f830380458..0000000000 --- a/doc/sphinx/source/recipes/recipe_toymodel.rst +++ /dev/null @@ -1,79 +0,0 @@ -.. _recipes_toymodel: - -Toymodel -==================================================== - -Overview --------- - -The goal of this diagnostic is to simulate single-model ensembles from an observational dataset to investigate the effect of observational uncertain. For further discussion of this synthetic value generator, its general application to forecasts and its limitations, see Weigel et al. (2008). The output is a netcdf file containing the synthetic observations. Due to the sampling of the perturbations from a Gaussian distribution, running the recipe multiple times, with the same observation dataset and input parameters, will result in different outputs. - - -Available recipes and diagnostics ------------------------------------ - -Recipes are stored in recipes/ - -* recipe_toymodel.yml - - -Diagnostics are stored in diag_scripts/magic_bsc/ - -* toymodel.R: generates a single model ensemble of synthetic observations - - - - -User settings -------------- - -User setting files are stored in recipes/ - -#. recipe_toymodel.yml - - *Required settings for preprocessor* - - extract_region: - - * start_longitude: minimum longitude - * end_longitude: maximum longitude - * start_latitude: minimum longitude - * end_latitude: maximum latitude - - *Required settings for script* - - * number_of_members: integer specifying the number of members to be generated - * beta: the user defined underdispersion (beta >= 0) - - -Variables ---------- - -* psl(atmos, daily-monthly, longitude, latitude, time) -* tas(atmos, daily-monthly, longitude, latitude, time) - - -Observations and reformat scripts ---------------------------------- - -*None* - -References ----------- - -* Bellprat, O., Massonnet, F., Siegert, S., Prodhomme, C., Macias-Gómez, D., Guemas, V., & Doblas-Reyes, F. (2017). Uncertainty propagation in observational references to climate model scales. Remote Sensing of Environment, 203, 101-108. - -* Massonet, F., Bellprat, O. Guemas, V., & Doblas-Reyes, F. J. (2016). Using climate models to estimate the quality of global observational data sets. Science, aaf6369. - -* Weigel, A. P., Liniger, M. A., & Appenzeller, C. (2008). Can multi-model combinations really enhance the prediction skill of probabilistic ensemble forecasts? Quarterly Journal of the Royal Meteorological Society, 134(630), 241-260. - - -Example plots -------------- - -.. _fig_toymodel: -.. figure:: /recipes/figures/toymodel/synthetic_CMIP5_IPSL-CM5A-LR_day_historical_r1i1p1_T2M_tasmax_1999-2000.jpg - - - - diff --git a/doc/sphinx/source/recipes/recipe_zmnam.rst b/doc/sphinx/source/recipes/recipe_zmnam.rst deleted file mode 100644 index b3303d195c..0000000000 --- a/doc/sphinx/source/recipes/recipe_zmnam.rst +++ /dev/null @@ -1,76 +0,0 @@ -Stratosphere-troposphere coupling and annular modes indices (ZMNAM) -=================================================================== - - -Overview --------- - -The current generation of climate models include the representation of stratospheric processes, as the vertical coupling with the troposphere is important for the weather and climate at the surface (e.g., `Baldwin and Dunkerton, 2001 `_). - -The recipe recipe_zmnam.yml can be used to evaluate the representation of the Northern Annular Mode (NAM, e.g., `Wallace, 2000 `_) in climate simulations, using reanalysis datasets as reference. - -The calculation is based on the “zonal mean algorithm” of `Baldwin and Thompson (2009) `_, and is alternative to pressure based or height-dependent methods. - -This approach provides a robust description of the stratosphere-troposphere coupling on daily timescales, requiring less subjective choices and a reduced amount of input data. -Starting from daily mean geopotential height on pressure levels, the leading empirical orthogonal function/principal component are computed from zonal mean daily anomalies, with the leading principal component representing the zonal mean NAM index. The regression of the monthly mean geopotential height onto this monthly averaged index represents the NAM pattern for each selected pressure level. - -The outputs of the procedure are the monthly time series and the histogram of the daily zonal-mean NAM index, and the monthly regression maps for selected pressure levels. The users can select the specific datasets (climate model simulation and/or reanalysis) to be evaluated, and a subset of pressure levels of interest. - - -Available recipes and diagnostics ---------------------------------- - -Recipes are stored in recipes/ - -* recipe_zmnam.yml - -Diagnostics are stored in diag_scripts/zmnam/ - -* zmnam.py - -and subroutines - -* zmnam_calc.py -* zmnam_plot.py -* zmnam_preproc.py - - -User settings -------------- - -None. - - -Variables ---------- - -* zg (atmos, daily mean, longitude latitude time) - - -Observations and reformat scripts ---------------------------------- - -None. - - -References ----------- - -* Baldwin, M. P. and Thompson, D. W. (2009), A critical comparison of stratosphere–troposphere coupling indices. Q.J.R. Meteorol. Soc., 135: 1661-1672. `doi:10.1002/qj.479 `_. -* Baldwin, M. P and Dunkerton, T. J. (2001), Stratospheric Harbingers of Anomalous Weather Regimes. Science 294 (5542): 581-584. `doi:10.1126/science.1063315 `_. -* Wallace, J. M. (2000), North Atlantic Oscillation/annular mode: Two paradigms-one phenomenon. Q.J.R. Meteorol. Soc., 126 (564): 791-805. `doi:10.1002/qj.49712656402 `_. - - - -Example plots -------------- - -.. figure:: /recipes/figures/zmnam/zmnam_reg.png - :width: 10cm - - Example output: time series of the zonal-mean NAM index. - -.. figure:: /recipes/figures/zmnam/zmnam_ts.png - :width: 10cm - - Example output: regression map for a selected pressure level. diff --git a/doc/sphinx/source/requirements.txt b/doc/sphinx/source/requirements.txt deleted file mode 100644 index f5b4b9c226..0000000000 --- a/doc/sphinx/source/requirements.txt +++ /dev/null @@ -1,17 +0,0 @@ -cdo -cython -matplotlib<3 -nc-time-axis -netCDF4 -numba -numpy -pillow -prov[dot] -psutil -pyyaml -shapely -xarray -yamale -sklearn -pandas -eofs diff --git a/doc/sphinx/source/esmvaldiag/config_developer.inc b/esmvalcore/utils/__init__.py similarity index 100% rename from doc/sphinx/source/esmvaldiag/config_developer.inc rename to esmvalcore/utils/__init__.py diff --git a/esmvalcore/utils/doc/__init__.py b/esmvalcore/utils/doc/__init__.py new file mode 100644 index 0000000000..e69de29bb2 diff --git a/esmvalcore/utils/doc/gensidebar.py b/esmvalcore/utils/doc/gensidebar.py new file mode 100644 index 0000000000..23f53bc78a --- /dev/null +++ b/esmvalcore/utils/doc/gensidebar.py @@ -0,0 +1,68 @@ +"""Generates sidebar/toctree. + +Generates the common sidebar/toctree for the sphinx/ReadTheDocs +documentation of the ESMValTool and its subprojects. +""" + +import os + + +def _write_if_changed(fname, contents): + """Write/update file only if changed.""" + try: + with open(fname, "r") as stream: + old_contents = stream.read() + except IOError: + old_contents = "" + + if old_contents != contents: + with open(fname, "w") as stream: + stream.write(contents) + + +def generate_sidebar(conf, conf_api): + """Generate sidebar. + + Generate sidebar for ReadTheDocs with links to subprojects and + superprojects accordingly. + """ + # determine 'latest' or 'stable' + # if not conf.do_gen: + do_gen = os.environ.get("SIDEBAR", None) == "1" or conf["on_rtd"] + + lines = ["", ".. DO NOT MODIFY! THIS PAGE IS AUTOGENERATED!", ""] + + def _toctree(): + lines.extend([".. toctree::", " :maxdepth: 1", ""]) + + def _endl(): + lines.append("") + + def _write(project, desc, link, mapping=conf['intersphinx_mapping']): + if project != conf_api: + if do_gen: + args = desc, mapping[project][0], link + lines.append(" %s <%s%s.html>" % args) + else: + args = desc, link + lines.append(" %s <%s>" % args) + + # + # Specify the sidebar contents here + # + + _toctree() + _write("esmvaltool", "Preface", "preface/index") + _write("esmvaltool", "Gallery", "gallery") + _write("esmvaltool", "Getting started", "getting_started/index") + _write("esmvaltool", "Recipes", "recipes/index") + _write("esmvalcore", "Core", "esmvalcore/index") + _write("esmvaltool", "Guidelines for diagnostic developers", + "esmvaldiag/index") + _write("esmvalcore", "Core API Reference", + "api/esmvalcore") + _write("esmvaltool", "Diagnostics API Reference", + "api/esmvaltool") + _endl() + + _write_if_changed("_sidebar.rst.inc", "\n".join(lines)) diff --git a/setup.cfg b/setup.cfg index 147f0c5b91..ea055e1bdc 100644 --- a/setup.cfg +++ b/setup.cfg @@ -2,8 +2,8 @@ test=pytest [build_sphinx] -source-dir = doc/sphinx/source -build-dir = doc/sphinx/build +source-dir = doc/ +build-dir = doc/build all_files = 1 builder = html @@ -21,7 +21,7 @@ addopts = env = MPLBACKEND = Agg flake8-ignore = - doc/sphinx/source/conf.py ALL + doc/conf.py ALL esmvalcore/cmor/_fixes/*/*.py N801 log_level = WARNING diff --git a/setup.py b/setup.py index 6cbb87b3e7..c5f554c6fe 100755 --- a/setup.py +++ b/setup.py @@ -29,6 +29,7 @@ # Use with pip install . to install from source 'install': [ 'cf-units', + 'dask[array]', 'nc-time-axis', # needed by iris.plot 'netCDF4', 'numba',