API Reference

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

ecmean module

class ecmean.Diagnostic(exp, year1, year2, config, funcname, line=False, trend=False, resolution='r360x180', ensemble='r1i1p1f1', addnan=False, interface=None, modelname=None, outputdir=None, xdataset=None, silent=None, numproc=1, climatology=None, reference=None)

Bases: object

General container class for common variables

Initialize the Diagnostic instance.

Parameters:: args – Arguments from command line/function.

cfg_global_mean(cfg)

Set up configuration details for global mean.

Parameters:: cfg – Configuration details.
Returns:: None

cfg_performance_indices(cfg)

Set up configuration for performance indices.

Parameters:: cfg – Configuration details.
Returns:: None

configure_amip_omip_cpld(support_dictionary)

Configure the experiment for AMIP, OMIP, or coupled simulations. Updates the variables/fields on which to run as a function of the experiment type, which is deduced from the availabe grids

Parameters:: util_dictionary – Dictionary containing output from Supporter()

filenames(kind): Return the filename for the output.

class ecmean.GlobalMean(exp, year1, year2, config='config.yml', loglevel='WARNING', numproc=1, interface=None, model=None, ensemble='r1i1p1f1', addnan=False, silent=None, trend=None, line=None, outputdir=None, xdataset=None, reference='EC23', title=None)

Bases: object

Class for computing global mean statistics from climate model output.

exp

Experiment name.

Type:: str

year1

Start year of the experiment.

Type:: int

year2

End year of the experiment.

Type:: int

config

Path to the configuration file. Default is ‘config.yml’.

Type:: str

loglevel

Logging level. Default is ‘WARNING’.

Type:: str

numproc

Number of processes to use. Default is 1.

Type:: int

interface

Path to the interface file. Default is None.

Type:: str

model

Model name. Default is None.

Type:: str

ensemble

Ensemble identifier. Default is ‘r1i1p1f1’.

Type:: str

addnan

Whether to add NaNs. Default is False.

Type:: bool

silent

Whether to suppress output. Default is None.

Type:: bool

trend

Whether to compute trends. Default is None.

Type:: bool

line

Line identifier. Default is None.

Type:: str

outputdir

Output directory. Default is None.

Type:: str

xdataset

Path to the xdataset. Default is None.

Type:: str

loggy

Logger instance.

Type:: logging.Logger

diag

Diagnostic instance.

Type:: Diagnostic

face

Interface dictionary.

Type:: dict

ref

Reference dictionary.

Type:: dict

util_dictionary

Supporter instance.

Type:: Supporter

varmean

Dictionary to store variable means.

Type:: dict

vartrend

Dictionary to store variable trends.

Type:: dict

funcname

Name of the class.

Type:: str

start_time

Start time for the timer.

Type:: float

title

Title of the plot, overrides default title.

Type:: str

final_toc(): Log the total elapsed time since the start.

static gm_worker(util, ref, face, diag, varmean, vartrend, varlist, loglevel)

” Workhorse for the global mean computation.

Parameters:

util (Supporter) – Utility dictionary for remapping and masks.
ref (dict) – Reference climatology dictionary.
face (dict) – Interface dictionary.
diag (Diagnostic) – Diagnostic instance.
varmean (dict) – Shared dictionary to store variable means.
vartrend (dict) – Shared dictionary to store variable trends.
varlist (list) – List of variables to process.
varlist – List of variables to process.

plot(diagname='global_mean', mapfile=None, figformat='pdf', storefig=True, returnfig=False, addnan=True)

Generate the heatmap for global mean.

Parameters:

diagname (str) – Name of the diagnostic. Default is ‘global_mean’.
mapfile (str) – Path to the output file. If None, it will be defined automatically following ECmean syntax.
figformat (str) – Format of the output file. Default is ‘pdf’.
storefig (bool) – If True, store the figure in the specified file. Default is True.
returnfig (bool) – If True, return the figure object. Default is False.
addnan (bool) – If True, add NaN values to the plot. Default is True.

prepare(): Prepare the necessary components for the global mean computation.

run(): Run the global mean computaacross all variables on using multiprocessing.

store(yamlfile=None, tablefile=None): Rearrange the data and save the yaml file and the table. :param yamlfile: Path to the output YAML file. If None, it will be defined automatically. :param tablefile: Path to the output TXT file. If None, it will be defined automatically.

toc(message): Update the timer and log the elapsed time.

class ecmean.PerformanceIndices(exp, year1, year2, config='config.yml', loglevel='WARNING', numproc=1, climatology=None, interface=None, model=None, ensemble='r1i1p1f1', silent=None, xdataset=None, outputdir=None, extrafigure=False, title=None)

Bases: object

Class to compute the performance indices for a given experiment and years.

exp

Experiment name.

Type:: str

year1

Start year of the experiment.

Type:: int

year2

End year of the experiment.

Type:: int

config

Path to the configuration file. Default is ‘config.yml’.

Type:: str

loglevel

Logging level. Default is ‘WARNING’.

Type:: str

numproc

Number of processes to use. Default is 1.

Type:: int

climatology

Climatology to use. Default is ‘EC24’.

Type:: str

interface

Path to the interface file.

Type:: str

model

Model name.

Type:: str

ensemble

Ensemble identifier. Default is ‘r1i1p1f1’.

Type:: str

silent

If True, suppress output. Default is None.

Type:: bool

xdataset

Dataset to use.

Type:: xarray.Dataset

outputdir

Directory to store output files.

Type:: str

loggy

Logger instance.

Type:: logging.Logger

diag

Diagnostic instance.

Type:: Diagnostic

face

Interface dictionary.

Type:: dict

piclim

Climatology dictionary.

Type:: dict

util_dictionary

Utility dictionary for remapping and masks.

Type:: Supporter

varstat

Dictionary to store variable statistics.

Type:: dict

funcname

Name of the class.

Type:: str

start_time

Start time for performance measurement.

Type:: float

title

Title of the plot, overrides default title.

Type:: str

Initialize the PerformanceIndices class with the given parameters.

final_toc(): Log the total elapsed time since the start.

static pi_worker(util, piclim, face, diag, field_3d, varstat, dictarray, varlist, loglevel)

Main parallel diagnostic worker for performance indices.

Parameters:

util (Supporter) – Utility dictionary for remapping and masks.
piclim (dict) – Climatology dictionary.
face (dict) – Interface dictionary.
diag (Diagnostic) – Diagnostic instance.
field_3d (list) – List of 3D fields.
varstat (dict) – Dictionary to store variable statistics.
dictarray (dict) – Dictionary to store the output array.
varlist (list) – List of variables to process.

plot(diagname='performance_indices', mapfile=None, figformat='pdf', storefig=True, returnfig=False)

Generate the heatmap for performance indices.

Parameters:

diagname (str) – Name of the diagnostic. Default is ‘performance_indices’.
mapfile (str) – Path to the output file. If None, it will be defined automatically following ECmean syntax.
storefig (bool) – If True, store the figure in the specified file. Default is True.
returnfig (bool) – If True, return the figure object. Default is False.

prepare(): Prepare the necessary components for performance indices calculation.

run(): Run the performance indices calculation.

store(yamlfile=None): Store the performance indices in a yaml file.

toc(message): Update the timer and log the elapsed time.

class ecmean.Supporter(component, atmdict, ocedict, areas=True, remap=False, targetgrid=None)

Bases: object

Support class for ecmean, including areas and masks to be used in global mean and performance indices

Class for masks, areas and interpolation (xESMF-based) for both atmospheric and oceanic component

load_area_field(areafile, comp): Loading files for area and interpolation

make_areas(gridtype, xfield): Create weights for area operations. Minimal structure.

make_atm_interp_weights(xfield): Create atmospheric interpolator weights

make_atm_masks(): Create land-sea masks for atmosphere model

make_oce_interp_weights(xfield)

Create oceanic interpolator weights.

Parameters:: xfield (xarray.DataArray) – The field to interpolate.
Returns:: The fix and remap objects.
Return type:: tuple

make_oce_masks(): Create land-sea masks for oceanic model. This is used only for CMIP

class ecmean.UnitsHandler(var=None, org_units=None, tgt_units=None, org_direction='down', tgt_direction='down', operation='mean', cumulation_time=None, clim=None, face=None, convert=True)

Bases: object

Class for dealing with units format and conversion within ecmean

Class for handling units and their conversion

Parameters:

var (string) – variable name, necessary for ecmean calls
org_units (string) – original units
tgt_units (string) – target units
org_direction (string) – down or up, direction for fluxes
tgt_direction (string) – down or up, direction for fluxes
operation (string) – mean or integral operation for target units
cumulation_time (integer) – expressed in seconds, cumulation time for fluxes
clim (dict) – climatology dictionary for ecmean calls
face (dict) – interface dictionary for ecmean calss
convert (bool) – if you want to perform conversion immediately

Returns:

units offset of conversion factor (float): units factor of conversion

Return type:

offset (float)

init_ecmean(clim, face): Specific initialization used within ECmean

units_converter()

Units conversion using metpy and pint. Converts org_units to tgt_units, providing offset and factor.

Assumes:

No simultaneous offset + factor conversions
Water fluxes and cumulated fluxes are handled with heuristics

Returns:: (offset, factor)
Return type:: tuple

ecmean.global_mean(exp, year1, year2, config='config.yml', loglevel='WARNING', numproc=1, interface=None, model=None, ensemble='r1i1p1f1', addnan=False, silent=None, trend=None, line=None, outputdir=None, xdataset=None, reference=None, title=None): Wrapecmeanction to compute the global mean.

ecmean.performance_indices(exp, year1, year2, config='config.yml', loglevel='WARNING', numproc=1, climatology=None, interface=None, model=None, ensemble='r1i1p1f1', silent=None, xdataset=None, outputdir=None, title=None, plot=True): Wrapper function to compute the performance indices for a given experiment and years.