API Reference

This section provides a detailed reference for AQUA’s Application Programming Interface (API).

AQUA module

class aqua.Fixer(fixer_name=None, fixes_dictionary=None, convention=None, metadata=None, loglevel='WARNING')

Bases: object

Fixer module

Parameters:

  • fixer_name (str) – The fixer name defined in the fixes dictionary

  • datamodel (str) – The target datamodel name

  • fixes_dictionary (dict) – The dictionary of fixes

  • convention (name) – The convention name

  • metadata (dict) – The metadata dictionary

  • loglevel (str) – The log level

find_fixes()

Get the fixes for the required model, experiment and source. A convention dictionary is loaded and merged with the fixer_name. The default convention is eccodes-2.39.0.

If not found, looks for default fixes for the model. Then source_fixes are loaded and merged with base_fixes.

This second block of search is deprecated and will be removed in the future.

Parameters:

class (The fixer)

Returns:

The fixer dictionary

fixer(data, destvar, apply_unit_fix=True)

Perform fixes (var name, units, coord name adjustments) of the input dataset.

Parameters:

  • data (xr.Dataset) – the input dataset

  • destvar (list of str) – the name of the desired variables to be fixed, if None all available variables are fixed

  • apply_unit_fix (bool) – if to perform immediately unit conversions (which requite a product or an addition). The fixer sets anyway an offset or a multiplicative factor in the data attributes. These can be applied also later with the method apply_unit_fix. (true)

Returns:

A xarray.Dataset containing the fixed data and target units, factors and offsets in variable attributes.

get_fixer_varname(var)

Load the fixes and check if the variable requested is there

Parameters:

var (str or list) – The variable to be checked

Returns:

A list of variables to be loaded

class aqua.FldStat(area: Dataset | DataArray | None = None, horizontal_dims: list[str] | None = None, grid_name: str | None = None, loglevel: str = 'WARNING')

Bases: object

AQUA class for field statitics

Initialize the FldStat.

Parameters:

  • area (xr.Dataset, xr.DataArray, optional) – The area to calculate the statistics for.

  • horizontal_dims (list, optional) – The horizontal dimensions of the data.

  • grid_name (str, optional) – The name of the grid, used for logging history.

  • loglevel (str, optional) – The logging level.

align_area_coordinates(data)

Check if the coordinates of the area and data are aligned. If they are not aligned, try to flip the coordinates.

Parameters:

data (xr.DataArray or xr.Dataset) – The input data to align with the area.

Returns:

The area with aligned coordinates.

Return type:

xr.DataArray or xr.Dataset

align_area_dimensions(data)

Align the area dimensions with the data dimensions. If the area and data have different number of horizontal dimensions, try to rename them.

Parameters:

data (xr.DataArray or xr.Dataset) – The input data to align with the area.

fldmean(data, **kwargs)

Perform a weighted global average. Builds on fldstat.

Parameters:

  • data (xr.DataArray or xarray.DataDataset) – the input data

  • **kwargs – additional arguments passed to fldstat

Returns:

the value of the averaged field

fldstat(data, stat='mean', lon_limits=None, lat_limits=None, **kwargs)

Perform a weighted global average. If a subset of the data is provided, the average is performed only on the subset.

Parameters:

  • data (xr.DataArray or xarray.DataDataset) – the input data

  • stat (str) – the statistic to compute, only supported is “mean”

  • lon_limits (list, optional) – the longitude limits of the subset

  • lat_limits (list, optional) – the latitude limits of the subset

Kwargs:
  • box_brd (bool,opt): choose if coordinates are comprised or not in area selection.

    Default is True

Returns:

The value of the averaged field

class aqua.GridBuilder(outdir: str = '.', model_name: str | None = None, grid_name: str | None = None, original_resolution: str | None = None, vert_coord: str | None = None, loglevel: str = 'warning')

Bases: object

Class to build automatically grids from data sources. Currently supports HEALPix grids and can be extended for other grid types.

Initialize the GridBuilder with a reader instance.

Parameters:

  • outdir (str) – The output directory for the grid files.

  • model_name (str, optional) – The name of the model, if different from the model argument.

  • grid_name (str, optional) – The name of the grid, to specify extra information in the grid file

  • original_resolution (str, optional) – The original resolution of the grid if using an interpolated source.

  • vert_coord (str, optional) – The vertical coordinate to consider for the grid build, to override the one detected by the GridInspector.

  • loglevel (str, optional) – The logging level for the logger. Defaults to ‘warning’.

GRIDTYPE_REGISTRY = {'Curvilinear': <class 'aqua.gridbuilder.extragridbuilder.CurvilinearGridBuilder'>, 'GaussianRegular': <class 'aqua.gridbuilder.extragridbuilder.GaussianRegularGridBuilder'>, 'HEALPix': <class 'aqua.gridbuilder.extragridbuilder.HealpixGridBuilder'>, 'Regular': <class 'aqua.gridbuilder.extragridbuilder.RegularGridBuilder'>, 'Unstructured': <class 'aqua.gridbuilder.extragridbuilder.UnstructuredGridBuilder'>}
build(data, rebuild=False, version=None, verify=True, create_yaml=True)

Retrieve and build the grid data for all gridtypes available.

Parameters:

  • rebuild (bool) – Whether to rebuild the grid file if it already exists. Defaults to False.

  • fix (bool) – Whether to fix the original source. Might be useful for some models. Defaults to False.

  • version (int, optional) – The version number to append to the grid file name. Defaults to None.

  • verify (bool) – Whether to verify the grid file after creation. Defaults to True.

  • create_yaml (bool) – Whether to create the grid entry in the grid file. Defaults to True.

class aqua.LRAgenerator(catalog=None, model=None, exp=None, source=None, var=None, configdir=None, resolution=None, frequency=None, fix=True, outdir=None, tmpdir=None, nproc=1, loglevel=None, region=None, drop=False, overwrite=False, definitive=False, performance_reporting=False, rebuild=False, exclude_incomplete=False, stat='mean', compact='xarray', cdo_options=['-f', 'nc4', '-z', 'zip_1'], **kwargs)

Bases: object

Class to generate LRA data at required frequency/resolution

Initialize the LRA_Generator class

Parameters:

  • catalog (string) – The catalog you want to reader. If None, guessed by the reader.

  • model (string) – The model name from the catalog

  • exp (string) – The experiment name from the catalog

  • source (string) – The sourceid name from the catalog

  • var (str, list) – Variable(s) to be processed and archived in LRA.

  • resolution (string) – The target resolution for the LRA. If None, no regridding is performed.

  • frequency (string,opt) – The target frequency for averaging the LRA, if no frequency is specified, no time average is performed

  • fix (bool, opt) – True to fix the data, default is True

  • outdir (string) – Where the LRA is stored.

  • tmpdir (string) – Where to store temporary files, default is None. Necessary for dask.distributed

  • configdir (string) – Configuration directory where the catalog are found

  • nproc (int, opt) – Number of processors to use. default is 1

  • loglevel (string, opt) – Logging level

  • region (dict, opt) – Region to be processed, default is None, meaning ‘global’. Requires ‘name’ (str), ‘lon’ (list) and ‘lat’ (list)

  • drop (bool, opt) – Drop the missing values in the region selection.

  • overwrite (bool, opt) – True to overwrite existing files in LRA, default is False

  • definitive (bool, opt) – True to create the output file, False to just explore the reader operations, default is False

  • performance_reporting (bool, opt) – True to save an html report of the dask usage, default is False. This will run a single month to collect the performance data.

  • exclude_incomplete (bool,opt) – True to remove incomplete chunk when averaging, default is false.

  • rebuild (bool, opt) – Rebuild the weights when calling the reader

  • stat (string, opt) – Statistic to compute. Can be ‘mean’, ‘std’, ‘max’, ‘min’.

  • compact (string, opt) – Compact the data into yearly files using xarray or cdo. If set to None, no compacting is performed. Default is “xarray”

  • cdo_options (list, opt) – List of options to be passed to cdo, default is [“-f”, “nc4”, “-z”, “zip_1”]

  • **kwargs – kwargs to be sent to the Reader, as ‘zoom’ or ‘realization’

check_integrity(varname)

To check if the LRA entry is fine before running

create_catalog_entry()

Create an entry in the catalog for the LRA

create_zarr_entry(verify=True)

Create a Zarr entry in the catalog for the LRA

Parameters:

verify – open the LRA source and verify it can be read by the reader

property dask

Check if dask is needed

generate_lra()

Generate LRA data

get_filename(var, year=None, month=None, tmp=False)

Create output filenames

retrieve()

Retrieve data from the catalog

write_chunk(data, outfile)

Write a single chunk of data - Xarray Dataset - to a specific file using dask if required and monitoring the progress

class aqua.Reader(model=None, exp=None, source=None, catalog=None, fix=True, regrid=None, regrid_method=None, areas=True, streaming=False, startdate=None, enddate=None, rebuild=False, loglevel=None, nproc=4, aggregation=None, chunks=None, preproc=None, convention='eccodes', engine='fdb', **kwargs)

Bases: object

General reader for climate data.

Initializes the Reader class, which uses the catalog config/config.yaml to identify the required data.

Parameters:

  • model (str) – Model ID. Mandatory

  • exp (str) – Experiment ID. Mandatory.

  • source (str) – Source ID. Mandatory

  • catalog (str, optional) – Catalog where to search for the triplet. Default to None will allow for autosearch in the installed catalogs.

  • regrid (str, optional) – Perform regridding to grid regrid, as defined in config/regrid.yaml. Defaults to None.

  • regrid_method (str, optional) – CDO Regridding regridding method. Read from grid configuration. If not specified anywhere, using “ycon”.

  • fix (bool, optional) – Activate data fixing

  • areas (bool, optional) – Compute pixel areas if needed. Defaults to True.

  • streaming (bool, optional) – If to retrieve data in a streaming mode. Defaults to False.

  • startdate (str, optional) – The starting date for reading/streaming the data (e.g. ‘2020-02-25’). Defaults to None.

  • enddate (str, optional) – The final date for reading/streaming the data (e.g. ‘2020-03-25’). Defaults to None.

  • rebuild (bool, optional) – Force rebuilding of area and weight files. Defaults to False.

  • loglevel (str, optional) – Level of logging according to logging module. Defaults to log_level_default of loglevel().

  • nproc (int, optional) – Number of processes to use for weights generation. Defaults to 4.

  • aggregation (str, optional) – the streaming frequency in pandas style (1M, 7D etc. or ‘monthly’, ‘daily’ etc.) Defaults to None (using default from catalog, recommended).

  • chunks (str or dict, optional) – chunking to be used for GSV access. Defaults to None (using default from catalog, recommended). If it is a string time chunking is assumed. If it is a dictionary the keys ‘time’ and ‘vertical’ are looked for. Time chunking can be one of S (step), 10M, 15M, 30M, h, 1h, 3h, 6h, D, 5D, W, M, Y. Vertical chunking is expressed as the number of vertical levels to be used.

  • preproc (function, optional) – a function to be applied to the dataset when retrieved. Defaults to None.

  • convention (str, optional) – convention to be used for reading data. Defaults to ‘eccodes’. (Only one supported so far)

  • engine (str, optional) – Engine to be used for GSV retrieval: ‘polytope’ or ‘fdb’. Defaults to ‘fdb’.

Keyword Arguments:

  • zoom (int, optional) – HEALPix grid zoom level (e.g. zoom=10 is h1024). Allows for multiple gridname definitions.

  • realization (int, optional) – The ensemble realization number, included in the output filename.

  • **kwargs – Additional arbitrary keyword arguments to be passed as additional parameters to the intake catalog entry.

Returns:

A Reader class object.

Return type:

Reader

detrend(data, dim='time', degree=1, skipna=False)

Remove the trend from an xarray object using polynomial fitting.

Parameters:

  • data (DataArray or Dataset) – The input data.

  • dim (str) – Dimension to apply detrend along. Defaults to ‘time’.

  • degree (int) – Degree of the polynomial. Defaults to 1.

  • skipna (bool) – Whether to skip NaNs. Defaults to False.

Returns:

The detrended data.

Return type:

DataArray or Dataset

fldmean(data, lon_limits=None, lat_limits=None, **kwargs)

Fldmean average on the data. If regridded, it will use the target grid areas.

histogram(data, **kwargs)

Wrapper for the histogram function.

instance = None
reader_esm(esmcat, var)

Reads intake-esm entry. Returns a dataset.

reader_fdb(esmcat, var, startdate, enddate, dask=False, level=None)

Read fdb data. Returns a dask array.

Parameters:

  • esmcat (intake catalog) – the intake catalog to read

  • var (str, int or list) – the variable(s) to read

  • startdate (str) – a starting date and time in the format YYYYMMDD:HHTT

  • enddate (str) – an ending date and time in the format YYYYMMDD:HHTT

  • dask (bool) – return directly a dask array

  • level (list, float, int) – level to be read, overriding default in catalog

Returns:

An xarray.Dataset

reader_intake(esmcat, var, loadvar, keep='first')

Read regular intake entry. Returns dataset.

Parameters:

  • esmcat (intake.catalog.Catalog) – your catalog

  • var (list or str) – Variable to load

  • loadvar (list of str) – List of variables to load

  • keep (str, optional) – which duplicate entry to keep (“first” (default), “last” or None)

Returns:

Dataset

regrid(data)

Call the regridder function returning container or iterator

retrieve(var=None, level=None, startdate=None, enddate=None, history=True, sample=False)

Perform a data retrieve.

Parameters:

  • var (str, list) – the variable(s) to retrieve. Defaults to None. If None, all variables are retrieved.

  • level (list, float, int) – Levels to be read, overriding default in catalog source (only for FDB) .

  • startdate (str) – The starting date for reading/streaming the data (e.g. ‘2020-02-25’). Defaults to None.

  • enddate (str) – The final date for reading/streaming the data (e.g. ‘2020-03-25’). Defaults to None.

  • history (bool) – If you want to add to the metadata history information about retrieve. Defaults to True.

  • sample (bool) – read only one default variable (used only if var is not specified). Defaults to False.

Returns:

A xarray.Dataset containing the required data.

set_default()

Sets this reader as the default for the accessor.

timmax(data, **kwargs)
timmean(data, **kwargs)
timmin(data, **kwargs)
timstat(data, stat, freq=None, exclude_incomplete=False, time_bounds=False, center_time=False)

Time averaging wrapper which is calling the timstat module

Parameters:

  • data (xr.DataArray or xarray.Dataset) – the input data

  • stat (str) – the statistical function to be applied

  • freq (str) – the frequency of the time average

  • exclude_incomplete (bool) – exclude incomplete time averages

  • time_bounds (bool) – produce time bounds after averaging

  • center_time (bool) – center time for averaging

timstd(data, **kwargs)
timsum(data, **kwargs)
vertinterp(data, levels=None, vert_coord='plev', units=None, method='linear')

A basic vertical interpolation based on interp function of xarray within AQUA. Given an xarray object, will interpolate the vertical dimension along the vert_coord. If it is a Dataset, only variables with the required vertical coordinate will be interpolated.

Parameters:

  • data (DataArray, Dataset) – your dataset

  • levels (float, or list) – The level you want to interpolate the vertical coordinate

  • units (str, optional,) – The units of your vertical axis. Default ‘Pa’

  • vert_coord (str, optional) – The name of the vertical coordinate. Default ‘plev’

  • method (str, optional) – The type of interpolation method supported by interp()

Return

A DataArray or a Dataset with the new interpolated vertical dimension

class aqua.Regridder(cfg_grid_dict: dict = None, src_grid_name: str = None, data: Dataset = None, cdo: str = None, loglevel: str = 'WARNING')

Bases: object

AQUA Regridder class

The (new) Regridder class. Can be initialized with a data (xr.Dataset/DataArray) or a src_grid_name It provides methods to generate areas and weights, and to regrid a dataset.

Parameters:

  • cfg_grid_dict (dict) – The dictionary containing the full AQUA grid configuration.

  • src_grid_name (str, optional) – The name of the source grid in the AQUA convention.

  • data (xarray.Dataset, optional) – The dataset to be regridded if src_grid_name is not provided.

  • cdo (str, optional) – The path to the CDO executable. If None, guess it from the system.

  • loglevel (str) – The logging level.

loglevel

The logging level.

Type:

str

logger

The logger.

Type:

logging.Logger

cfg_grid_dict

The full AQUA grid dictionary.

Type:

dict

src_grid_name

The source grid name.

Type:

str

handler

The grid dictionary handler.

Type:

GridDictHandler

src_grid_dict

The normalized source grid dictionary.

Type:

dict

src_horizontal_dims

The source horizontal dimensions.

Type:

str

src_vertical_dim

The source vertical dimension.

Type:

str

tgt_horizontal_dims

The target horizontal dimensions.

Type:

str

error

The error message to be used by the Reader.

Type:

str

cdo

The CDO path.

Type:

str

smmregridder

The SMMregrid regridder object for each vertical coordinate.

Type:

dict

src_grid_area

The source grid area.

Type:

xarray.Dataset

tgt_grid_area

The target grid area.

Type:

xarray.Dataset

masked_attrs

The masked attributes.

Type:

dict

masked_vars

The masked variables.

Type:

list

extra_dims

The extra dimensions (from cfg_grid_dict) to be sent to smmregrid.

Type:

dict

areas(tgt_grid_name=None, rebuild=False, reader_kwargs=None)

Load or generate regridding areas for the source or target grid.

Parameters:

  • tgt_grid_name (str, optional) – Name of the target grid. If None, the self.src_grid_name is used.

  • rebuild (bool, optional) – If True, forces regeneration of the area.

  • reader_kwargs (dict, optional) – Additional parameters for the reader.

Returns:

The computed grid area.

Return type:

xr.Dataset

static configure_masked_fields(src_grid_dict)

if the grids has the ‘masked’ option, this can be based on generic attribute or alternatively of a series of specific variables using the ‘vars’ key

Parameters:

source_grid (dict) – Dictionary containing the grid information

Returns:

Dict with name and proprierty of the attribute to be used for masking masked_vars (list): List of variables to mask

Return type:

masked_attr (dict)

regrid(data)

Actual regridding core function. Regrid the dataset or dataarray using common gridtypes Firstly, expand the dimensions of the dataset to include the vertical dimensions if necessary. Then, group variables that share the same dimensions. Finally, apply regridding on the different vertical coordinates, including 2d and 2dm.

Parameters:

data (xarray.Dataset, xarray.DataArray) – The dataset to be regridded.

weights(tgt_grid_name, regrid_method=None, nproc=1, rebuild=False, reader_kwargs=None)

Load or generate regridding weights calling smmregrid

Parameters:

  • tgt_grid_name (str) – The destination grid name.

  • regrid_method (str) – The regrid method.

  • nproc (int) – The number of processors to use.

  • rebuild (bool) – If True, rebuild the weights.

  • reader_kwargs (dict) – The reader kwargs for filename definition, including info on model, exp, source, etc.

class aqua.Streaming(aggregation='S', startdate=None, enddate=None, loglevel=None)

Bases: object

Streaming class to be used in Reader and elsewhere

The Streaming constructor. The streamer is used to stream data by either a specific time interval or by a specific number of samples. If the unit parameter is specified, the data is streamed by the specified unit and stream_step (e.g. 1 month). If the unit parameter is not specified, the data is streamed by stream_step steps of the original time resolution of input data.

If the stream function is called a second time, it will return the subsequent chunk of data in the sequence. The function keeps track of the state of the streaming process through the use of an internal counter. This allows the user to stream through the entire dataset in multiple calls to the function, retrieving consecutive chunks of data each time.

If startdate is not specified, the method will use the first date in the dataset.

Parameters:

  • startdate (str) – the starting date for streaming the data (e.g. ‘2020-02-25’) (None)

  • enddate (str) – the ending date for streaming the data (e.g. ‘2021-01-01’) (None)

  • aggregation (str) – the streaming frequency in pandas style (1M, 7D etc.)

  • loglevel (string) – Level of logging according to logging module (default: log_level_default of loglevel())

Returns:

A Streaming class object.

reset()

Reset the state of the streaming process. This means that if the stream function is called again after calling reset_stream, it will start streaming the input data from the beginning.

stream(data, startdate=None, enddate=None, aggregation=None, timechunks=None, reset=False)

Stream a chunk of a dataset using startdate, enddate and aggregation defined by the constructor.

Parameters:

  • data (xr.Dataset) – the input xarray.Dataset

  • startdate (str) – the starting date for streaming the data (e.g. ‘2020-02-25’) (None)

  • enddate (str) – the ending date for streaming the data (e.g. ‘2021-01-01’) (None)

  • aggregation (str) – the streaming frequency in pandas style (1M, 7D etc.)

  • timechunks (DataArrayResample, optional) – a precomputed chunked time axis

  • reset (bool, optional) – reset the streaming

Returns:

A xarray.Dataset containing the subset of the input data that has been streamed.

stream_chunk(data, startdate=None, enddate=None, aggregation=None)

Compute chunks for a dataset using startdate, enddate and aggregation defined by the constructor.

Parameters:

  • data (xr.Dataset) – the input xarray.Dataset

  • startdate (str) – the starting date for streaming the data (e.g. ‘2020-02-25’) (None)

  • enddate (str) – the ending date for streaming the data (e.g. ‘2021-01-01’) (None)

  • aggregation (str) – the streaming frequency in pandas style (1M, 7D etc.)

Returns:

A DataArrayResample object for the time axis

aqua.catalog(verbose=True, configdir=None, catalog_name=None)

Catalog of available data.

Parameters:

  • verbose (bool, optional) – If True, prints the catalog information to the console. Defaults to True.

  • configdir (str, optional) – The directory containing the configuration files. If not provided, get_config_dir is used to find it.

Returns:

The catalog object

containing the data.

Return type:

cat (intake.catalog.local.LocalCatalog)

aqua.histogram(data: DataArray, bins=10, range=None, units=None, weighted=True, loglevel='WARNING', dask=True, check=False, density=False)

Function to calculate a histogram of a DataArray.

Parameters:

  • data (xarray.Dataset) – The input DataArray. If it is a Dataset, the first variable is used.

  • bins (int, optional) – The number of bins for the histogram. Defaults to 10.

  • range (tuple, optional) – The lower and upper range of the bins. Defaults to None (in that case it is determined automatically).

  • weighted (bool, optional) – Use latitudinal weights for the histogram. Defaults to True.

  • dask (bool, optional) – If True, uses Dask for parallel computation. Defaults to True.

  • units (str, optional) – Convert data to these units. Defaults to None.

  • check (bool, optional) – Checks if the sum of counts in the histogram is equal to the size of the data. Defaults to False. This forces the histogram to be computed.

  • density (bool, optional) – Returns a probability density function, normalized such that the integral over the range is 1. Defaults to False.

  • loglevel (str, optional) – Logging level. Defaults to ‘WARNING’.

Raises:

TypeError – If the input data is not an xarray DataArray.

Returns:

The histogram of the input data.

Return type:

xarray.DataArray

aqua.inspect_catalog(catalog_name=None, model=None, exp=None, source=None, verbose=True)

Basic function to simplify catalog inspection. If a partial match between model, exp and source is provided, then it will return a list of models, experiments or possible sources. If all three are specified it returns False if that combination does not exist, a list of variables if the source is a FDB/GSV source and it exists and True if it exists but is not a FDB source.

Parameters:

  • catalog_name (str, optional) – A string containing the catalog name.

  • model (str, optional) – The model ID to filter the catalog. If None, all models are returned. Defaults to None.

  • exp (str, optional) – The experiment ID to filter the catalog. If None, all experiments are returned. Defaults to None.

  • source (str, optional) – The source ID to filter the catalog. If None, all sources are returned. Defaults to None.

  • verbose (bool, optional) – Print the catalog information to the console. Defaults to True.

Returns:

A list of available items in the catalog, depending on the

specified model and/or experiment, a list of variables or True/False.

Return type:

list

Raises:

KeyError – If the input specifications are incorrect.

aqua.plot_hovmoller(data: DataArray, invert_axis=False, invert_time=False, sym=False, contour=True, save=False, dim='lon', figsize=(8, 13), vmin=None, vmax=None, cmap='PuOr_r', nlevels=8, cbar_label=None, outputdir='.', filename='hovmoller.pdf', display=True, return_fig=False, loglevel: str = 'WARNING', **kwargs)

” Plot a hovmoller diagram of a DataArray.

Parameters:

  • data (xr.DataArray) – xr.DataArray to be plot

  • invert_axis (bool,opt) – enable or disable axis inversion, default is False

  • invert_time (bool,opt) – enable or disable time inversion, if False, time will increase with the increasing axis direction.

  • sym (bool,opt) – center the cbar around zero, default is False

  • contour (bool,opt) – True for contour plot, False for pcolormesh, default is True

  • save (bool,opt) – save the figure, default is False

  • dim (str,opt) – dimension to be averaged over, default is ‘lon’

  • figsize (tuple,opt) – figure size, default is (11, 8.5)

  • vmin (float,opt) – minimum value for the colorbar

  • vmax (float,opt) – maximum value for the colorbar

  • cmap (str,opt) – colormap, default is ‘RdBu_r’

  • nlevels (int,opt) – number of contour levels, default is 8

  • cbar_label (str,opt) – colorbar label, default is None

  • outputdir (str,opt) – output directory, default is ‘.’

  • filename (str,opt) – output filename, default is ‘hovmoller.png’

  • show_dim_values (bool,opt) – show the values of the dimension over which the mean was taken (round them to int) Default is True

  • display (bool, optional) – If True, display the figure. Defaults to True.

  • return_fig (bool, optional) – If True, return the figure (fig, ax). Defaults to False.

  • loglevel (str,opt) – log level for the logger, default is ‘WARNING’

Keyword Arguments:

  • format (str, optional) – Format of the figure. Defaults to ‘pdf’.

  • dpi (int, optional) – Dots per inch. Defaults to 100 for pcolormesh and 300 for contour plots.

Returns:

tuple with the figure and axes

Return type:

fig, ax

aqua.plot_maps(maps: list, contour: bool = True, sym: bool = False, proj: ~cartopy.crs.Projection = <Projected CRS: +proj=robin +a=6378137.0 +lon_0=0 +no_defs +type=c ...> Name: unknown Axis Info [cartesian]: - E[east]: Easting (metre) - N[north]: Northing (metre) Area of Use: - undefined Coordinate Operation: - name: unknown - method: Robinson Datum: unknown - Ellipsoid: unknown - Prime Meridian: Greenwich, extent: list = None, style=None, figsize: tuple = None, vmin: float = None, vmax: float = None, nlevels: int = 11, title: str = None, titles: list = None, cmap='RdBu_r', cbar_label: str = None, transform_first=False, cyclic_lon=True, return_fig=False, loglevel='WARNING', **kwargs)

Plot multiple maps. This is supposed to be used for maps to be compared together. A list of xarray.DataArray objects is expected and a map is plotted for each of them

Parameters:

  • maps (list) – list of xarray.DataArray objects

  • contour (bool,opt) – If True, plot a contour map, otherwise a pcolormesh. Defaults to True.

  • sym (bool,opt) – symetric colorbar, default is False

  • proj (cartopy.crs.Projection,opt) – projection, default is ccrs.Robinson()

  • extent (list,opt) – extent of the map, default is None

  • style (str,opt) – style for the plot, default is the AQUA style

  • figsize (tuple,opt) – figure size, default is (6,6) for each map. Here the full figure size is set.

  • vmin (float,opt) – minimum value for the colorbar, default is None

  • vmax (float,opt) – maximum value for the colorbar, default is None

  • nlevels (int,opt) – number of levels for the colorbar, default is 11

  • title (str,opt) – super title for the figure

  • titles (list,opt) – list of titles for the maps

  • cmap (str,opt) – colormap, default is ‘RdBu_r’

  • cbar_label (str,opt) – colorbar label

  • transform_first (bool, optional) – If True, transform the data before plotting. Defaults to False.

  • cyclic_lon (bool,opt) – add cyclic longitude, default is True

  • return_fig (bool,opt) – return the figure, default is False

  • loglevel (str,opt) – log level, default is ‘WARNING’

  • **kwargs – Keyword arguments for plot_single_map

Raises:

ValueError – if nothing to plot, i.e. maps is None or not a list of xarray.DataArray

Returns:

fig if more manipulations on the figure are needed, if return_fig=True

aqua.plot_single_map(data: ~xarray.core.dataarray.DataArray, contour=True, sym=False, proj: ~cartopy.crs.Projection = <Projected CRS: +proj=robin +a=6378137.0 +lon_0=0 +no_defs +type=c ...> Name: unknown Axis Info [cartesian]: - E[east]: Easting (metre) - N[north]: Northing (metre) Area of Use: - undefined Coordinate Operation: - name: unknown - method: Robinson Datum: unknown - Ellipsoid: unknown - Prime Meridian: Greenwich, extent=None, coastlines=True, style=None, figsize=(11, 8.5), nlevels=11, vmin=None, vmax=None, cmap='RdBu_r', cbar: bool = True, cbar_label=None, title=None, transform_first=False, cyclic_lon=True, fig: ~matplotlib.figure.Figure = None, ax: ~matplotlib.axes._axes.Axes = None, ax_pos: tuple = (1, 1, 1), return_fig=False, loglevel='WARNING', **kwargs)

Plot contour or pcolormesh map of a single variable. By default the contour map is plotted.

Parameters:

  • data (xr.DataArray) – Data to plot.

  • contour (bool, optional) – If True, plot a contour map, otherwise a pcolormesh. Defaults to True.

  • sym (bool, optional) – If True, set the colorbar to be symmetrical. Defaults to False.

  • extent (list, optional) – Extent of the map to limit the projection. Defaults to None.

  • coastlines (bool, optional) – If True, add coastlines. Defaults to True.

  • style (str, optional) – Style to use. Defaults to None (aqua style).

  • figsize (tuple, optional) – Figure size. Defaults to (11, 8.5).

  • nlevels (int, optional) – Number of levels for the contour map. Defaults to 11.

  • vmin (float, optional) – Minimum value for the colorbar. Defaults to None.

  • vmax (float, optional) – Maximum value for the colorbar. Defaults to None.

  • cmap (str, optional) – Colormap. Defaults to ‘RdBu_r’.

  • cbar (bool, optional) – If True, add a colorbar. Defaults to True.

  • cbar_label (str, optional) – Colorbar label. Defaults to None.

  • title (str, optional) – Title of the figure. Defaults to None.

  • transform_first (bool, optional) – If True, transform the data before plotting. Defaults to False.

  • cyclic_lon (bool, optional) – If True, add cyclic longitude. Defaults to True.

  • fig (plt.Figure, optional) – Figure to plot on. By default a new figure is created.

  • ax (plt.Axes, optional) – Axes to plot on. By default a new axes is created.

  • ax_pos (list, optional) – Axes position. Used if the axes has to be created. Defaults to (1, 1, 1).

  • return_fig (bool, optional) – If True, return the figure and axes. Defaults to False.

  • loglevel (str, optional) – Log level. Defaults to ‘WARNING’.

Keyword Arguments:

  • nxticks (int, optional) – Number of x ticks. Defaults to 7.

  • nyticks (int, optional) – Number of y ticks. Defaults to 7.

  • ticks_rounding (int, optional) – Number of digits to round the ticks. Defaults to 0 for full map, 1 if min-max < 10, 2 if min-max < 1.

  • cbar_ticks_rounding (int, optional) – Number of digits to round the colorbar ticks. Default is no rounding.

Returns:

Figure and axes.

Return type:

tuple

aqua.plot_single_map_diff(data: ~xarray.core.dataarray.DataArray, data_ref: ~xarray.core.dataarray.DataArray, proj: ~cartopy.crs.Projection = <Projected CRS: +proj=robin +a=6378137.0 +lon_0=0 +no_defs +type=c ...> Name: unknown Axis Info [cartesian]: - E[east]: Easting (metre) - N[north]: Northing (metre) Area of Use: - undefined Coordinate Operation: - name: unknown - method: Robinson Datum: unknown - Ellipsoid: unknown - Prime Meridian: Greenwich, extent: list = None, vmin_fill: float = None, vmax_fill: float = None, vmin_contour: float = None, vmax_contour: float = None, sym_contour: bool = False, sym: bool = True, cyclic_lon: bool = True, return_fig: bool = False, fig: ~matplotlib.figure.Figure = None, ax: ~matplotlib.axes._axes.Axes = None, title: str = None, loglevel: str = 'WARNING', **kwargs)

Plot the difference of data-data_ref as map and add the data as a contour plot.

Parameters:

  • data (xr.DataArray) – Data to plot.

  • data_ref (xr.DataArray) – Reference data to plot the difference.

  • proj (cartopy.crs.Projection, optional) – Projection to use. Defaults to PlateCarree.

  • extent (list, optional) – Extent of the map to limit the projection. Defaults to None.

  • vmin_fill (float, optional) – Minimum value for the colorbar of the fill.

  • vmax_fill (float, optional) – Maximum value for the colorbar of the fill.

  • vmin_contour (float, optional) – Minimum value for the colorbar of the contour.

  • vmax_contour (float, optional) – Maximum value for the colorbar of the contour.

  • sym_contour (bool, optional) – If True, set the contour levels to be symmetrical. Default to False

  • sym (bool, optional) – If True, set the colorbar for the diff to be symmetrical. Default to True

  • title (str, optional) – Title of the figure. Defaults to None.

  • cyclic_lon (bool, optional) – If True, add cyclic longitude. Defaults to True.

  • return_fig (bool, optional) – If True, return the figure and axes. Defaults to False.

  • fig (plt.Figure, optional) – Figure to plot on. By default a new figure is created.

  • ax (plt.Axes, optional) – Axes to plot on. By default a new axes is created.

  • loglevel (str, optional) – Log level. Defaults to ‘WARNING’.

  • **kwargs – Keyword arguments for plot_single_map. Check the docstring of plot_single_map.

Keyword Arguments:

  • contour (bool, optional) – Plot the difference as contour. False to plot a pcolormesh

  • coastlines (bool, optional) – If True, add coastlines. Defaults to True.

Raises:

ValueError – If data or data_ref is not a DataArray.

aqua.plot_timeseries(monthly_data: list[DataArray] | DataArray = None, annual_data: list[DataArray] | DataArray = None, ref_monthly_data: DataArray = None, ref_annual_data: DataArray = None, std_monthly_data: DataArray = None, std_annual_data: DataArray = None, ens_monthly_data: DataArray = None, ens_annual_data: DataArray = None, std_ens_monthly_data: DataArray = None, std_ens_annual_data: DataArray = None, data_labels: list = None, ref_label: str = None, ens_label: str = None, style: str = None, fig: Figure = None, ax: Axes = None, figsize: tuple = (10, 5), title: str = None, loglevel: str = 'WARNING', **kwargs)

monthly_data and annual_data are list of xr.DataArray that are plot as timeseries together with their reference data and standard deviation.

Parameters:

  • monthly_data (list of xr.DataArray) – monthly data to plot

  • annual_data (list of xr.DataArray) – annual data to plot

  • ref_monthly_data (xr.DataArray) – reference monthly data to plot

  • ref_annual_data (xr.DataArray) – reference annual data to plot

  • std_monthly_data (xr.DataArray) – standard deviation of the reference monthly data

  • std_annual_data (xr.DataArray) – standard deviation of the reference annual data

  • ens_monthly_data (xr.DataArray) – ensemble monthly data to plot

  • ens_annual_data (xr.DataArray) – ensemble annual data to plot

  • std_ens_monthly_data (xr.DataArray) – standard deviation of the ensemble monthly data

  • std_ens_annual_data (xr.DataArray) – standard deviation of the ensemble annual data

  • data_labels (list of str) – labels for the data

  • ref_label (str) – label for the reference data

  • style (str) – style to use for the plot. By default the schema specified in the configuration file is used.

  • fig (plt.Figure) – figure object to plot on

  • ax (plt.Axes) – axis object to plot on

  • figsize (tuple) – size of the figure

  • title (str) – title of the plot

  • loglevel (str) – logging level

Keyword Arguments:

  • figsize (tuple) – size of the figure

  • title (str) – title of the plot

Returns:

tuple containing the figure and axis objects

Return type:

fig, ax (tuple)