Using Atlas Explorer (original) (raw)

(in progress)

Atlas Explorer is a working space of the C-ESM-EP. In other words, it is not a pre-defined, community validated set of specific scientific diagnostics. It is a way to create html pages with lines of plots:

first plot (on the left) is the climatology of the reference
subsequent plots are the difference maps of the datasets specified in datasets_setup.py with the reference Each line is a variable (potentially with custom analysis or plot specifications).

Most of the bias maps in the C-ESM-EP (Atmosphere_Surface, NEMO_main, PISCES, ORCHIDEE...) are generated using the Atlas Explorer mechanism. This page can be very helpful if you want to customize those atlases.

Check this page to see how you can add new variables to your atlas.

General specifications in AtlasExplorer/params_AtlasExplorer.py

The first block of instructions in params_AtlasExplorer.py is the same in all the C-ESM-EP parameter files.

The variable verbose controls the verbosity of CliMAF. This controls the amount of informations output by CliMAF in the .e files (or during an interactive execution). 'debug' is the most verby mode, and 'critical' is the minimum. (we advise to leave it to 'debug')

# -- Safe Mode (set to False and verbose='debug' if you want to debug)
safe_mode = True

The safe_mode is a mechanism that allows the execution of the atlas to go on even if you encounter an error on a given plot on the way. It will return a blank image if the C-ESM-EP was not able to do the plot (file not available, problem with the plot...). Set it to False if you want to force the atlas to stop and return the error message on a given failed plot to debug.

# -- Set to 'True' (string) to clean the CliMAF cache
clean_cache = 'False'

Set it to 'True' (string, not boolean!) to clean the cache (it will execute a craz() CliMAF command and totally clean the cache).

# -- Patterns to clean the cache at the end of the execution of the atlas
routine_cache_cleaning = [dict(age='+20')]

This is an important functionality: it cleans the cache at the end of the execution of the atlas by making a loop on the dictionaries of the list routine_cache_cleaning to provide those lists of arguments to CliMAF crm()

# -- Set the reference against which we plot the diagnostics
# -- If you set it in the parameter file, it will overrule
# -- the reference set in datasets_setup.py
# ---------------------------------------------------------------------------- >
# --    -> 'default' uses variable2reference to point to a default
# --       reference dataset (obs and reanalyses)
# --    -> you can set reference to a dictionary that will point any other
# --       climaf dataset
# --       For instance, you can set it to models[0] if you want to see the
# --       differences relative to the first simulation of the list 'models'
#reference = 'default'

You can set a reference specifically for this atlas (and not for the other atlases of your C-ESM-EP comparison) with the variable 'reference'. See the pages on datasets_setup.py to see how to use it.

# -- Set the overall season, region and geographical domain
# --> season, region and domain do not overwrite the values that are pre-defined with some diagnostics
# ---------------------------------------------------------------------------- >
season = 'ANM'  # -> Choose among all the possible values taken by clim_average (see help(clim_average)) like JFM, December,...
proj = 'GLOB'   # -> Set to a value taken by the argument 'proj' of plot(): GLOB, NH, SH, NH20, SH30...
domain = dict() # -> set domain = dict(lonmin=X1, lonmax=X2, latmin=Y1, latmax=Y2)

The variables season, proj and domain allow you to set respectively a season, projection and geographical domain (domain) for the whole atlas. Note that the potential season, proj and domain specified with a given variable (see below) will be used in place of those ones (only for the variable associated with them).

Variable-dependant specifications in AtlasExplorer/params_AtlasExplorer.py

The user provides the list of variables, potentially with custom specifications, via the atlas_explorer_variables python list:

atlas_explorer_variables = ['tas','pr',
                            'tos','sos',
                            dict(variable='ua', season='DJF', add_climato_contours=True),
                            dict(variable='ua', season='JJA', add_climato_contours=True),
                            dict(variable='tos',domain=dict(lonmin=-80,lonmax=40,latmin=10,latmax=85)),
                            dict(variable='sic', proj='NH50', season='March'),
                            dict(variable='lai', season='MAM'),
                           ]

Here is the list of arguments you can add with a variable in a dictionary to customize your plot/diagnostic:

scale, offset: a scale and offset to apply to the field before plotting (converting K to °C, kg.m-2.s-1 to mm/day...)
table: the MIP table for CMIP5/CMIP6 projects
realm: realm for MIP
grid: grid for MIPs (gr or gn)
project_specs: a dictionary to pass those previous arguments (and potential project-specific arguments) specifically to given projects: Ex: project_specs = dict(IGCM_OUT=dict(DIR='ATM', OUT='Output'), CMIP5=dict(table='Amon'))
display_field_stats: True/False; set to True to show min, max, mean value of the field
season: provide a season (see the CliMAF documentation on clim_average)
spatial_anomalies: True/False; set to True if you want to remove the spatial average (used for zos - the SSH)
cdogrid: provide the CDO grid name you want to regrid your data for the comparison
proj: name of the projection (NH50, SH30, GLOB or any ncl projection name
domain: a dictionary with the boundaries of a geographical domain (Ex: domain=dict(lonmin=[], lonmax=[], latmin=[], latmax=[]))
zonmean_variable: set to True if your variable is 3D variable on regular grid and you want to plot the zonal average
regrid_option: the CDO regridding method (remapbil, remapdis...)
add_climato_contours: set to True if you want to add the contours of the climatology of the reference to your bias plots (Note: this functionality will use the isolines specified in the plot_params (or your custom_plot_params) for 'full_field'; provide either 'min', 'max' and 'delta' (linear intervals between the isolines) or 'colors' (provide the isolines manually: Ex: colors='-50 -20 -10 -5 -2 -1 1 2 5 10 20 50')
add_aux_contours: add contours of an auxiliary field
plot_params_aux: plot parameters for the auxiliary field (supercedes the default plot parameters for the auxiliary field)
plot_context_suffix: in custom_plot_params, it is possible to specify plot parameters for, say, a region, a section, for a given variable; we do this by adding a suffix to the variable (Ex: 'tas_NAtl', 'pr_myregion'). You can target those kind of plot parameters specification by providing this kind of suffix to plot_context_suffix (NAtl, my_region)
vectors: adding a vector field to your plot vectors is a dictionary: vectors = dict(u_comp='zonal_component', v_comp='meridional_component', grid, table, [...]) u_comp and v_comp are the variable names of the zonal component and meridional component of the vector field (Ex: u_comp='uas', v_comp='vas'). grid, table are optional arguments to specify the access to your files [...] means that you can add optional plot parameters for the vector fields
options, aux_options: any other ncl ressource (i.e. plot parameter) you want to pass to the CliMAF plot function with the arguments options or aux_options (options or aux_options)
and any argument taken by the [CliMAF plot function](https://climaf.readthedocs.io/en/latest/scripts/plot.html)): mpCenterLonF, min, max...