xIndices

This section provides an overview of the modules included in the xIndices package and their functionalities.

Overview

xIndices is organized into the following modules:

1. xIndices.indices: This module contains functions for calculating indices such as SST trend and warming pattern, ENSO pattern & Index, PDO pattern & Index, and NAO pattern & Index.

   • global_sst_trend_and_enso: Calculate global SST trend, warming patterns, ENSO patterns, and indices.

   • compute_nao: Compute the NAO index and pattern using EOF analysis using varimax rotation.

   • compute_pdo: Calculate PDO indices and pattern usin EOF analysis.

   • compute_amo: Calculate PDO indices and pattern using area-averaged detrended anomaly

   • compute_regional_eof_modes: Calculate regional EOF modes (Rotated and unrotated) from gridded data.

2. xIndices.preprocess_data: This module handles data preprocessing tasks, such as calculating climatological anomalies and preparing data for EOF analysis.

   • load_data: Load NetCDF data into xarray DataArrays.

   • write_netcdf: Save processed data back to NetCDF format.

   • regridding: It helps regrid the Datasets and dataArrays (Curvilinear to Rectilinear; Rectilinear to Rectilinear)

   • adjust_longitude: Helper function and user function to adjust the longitude range of the dataset.

   • rename_dims_to_standard: Helper function and user function to rename dimensions to standard names for easier processing.

3. xIndices.utils: Contains utility functions that assist with common tasks required in data processing and analysis.

   • calculate_anomaly: Helper function to calculate anomalies based on a specified climatological period.

   • compute_weights: Helper function to compute latitudinal area weights.

   • compute_rotated_eofs: Compute EOFs with optional rotation using Varimax or Promax methods.

   • line_plot: Help visulize 1D data such as indices or PCs

   • contour_plot: Help visulize 2D data such as patterns or EOFs

Detailed Documentation

xIndices package

Submodules

xIndices.indices module

xIndices.indices.calculate_global_mean_sst(data, lat_name='lat', lon_name='lon')

Calculate the global mean sea surface temperature (SST) anomaly.

Parameters: data (xarray.DataArray): Input data array containing SST values. lat_name (str, optional): Name of the latitude coordinate in the data array. Default is ‘lat’. lon_name (str, optional): Name of the longitude coordinate in the data array. Default is ‘lon’.

Returns: xarray.DataArray: The global mean SST anomaly.

xIndices.indices.global_sst_trend_and_enso(data=None, path=None, var=None, clim_start=None, clim_end=None, desired=None, start_time=None, end_time=None, to_range='0_360', standardize=False, normalize_pattern=True, normalize_index=False)

Calculate global SST warming trend and ENSO patterns using EOF analysis.

This function computes the global SST warming trend, ENSO index, and their corresponding variance fractions using the first two EOF modes of SST anomalies. It first removes the annual cycle climatology and then applies EOF analysis.

Parameters:

dataxarray.DataArray or xarray.Dataset, optional

Gridded SST data with dimensions (time, lat, lon). If not provided, ‘path’ and ‘var’ must be used to load the data.

pathstr, optional

Directory path to the data. Required if ‘data’ is not provided.

varstr, optional

Name of the variable to load from the dataset.

clim_startint, optional

Climatology start year.

clim_endint, optional

Climatology end year (if both None, the entire period is used for climatology).

desiredlist of str, optional

Desired outputs, which can include: [‘sst_trend_pattern’, ‘sst_trend_timeseries’, ‘variance_fraction_trend’, ‘enso_pattern’, ‘enso_index’, ‘variance_fraction_enso’]. Default is to return all.

start_timeint, optional

Start year for loading data.

end_timeint, optional

End year for loading data.

to_rangestr, optional, default ‘0_360’

Longitude range for data adjustment. Options are ‘0_360’ or ‘-180_180’.

standardizebool, optional, default False

Whether to normalize the data with its standard deviation before EOF calculation.

normalize_patternbool, optional, default True

Whether to normalize spatial components (patterns) with singular values.

normalize_indexbool, optional, default False

Whether to normalize time series (scores) with singular values.

Returns:

List containing the desired outputs: SST trend pattern, trend timeseries, variance fraction of the trend, ENSO pattern, ENSO index, and variance fraction of ENSO.

xIndices.indices.compute_regional_eof_modes(data=None, path=None, var=None, clim_start=None, clim_end=None, desired=None, start_time=None, end_time=None, lat_s=90, lat_e=-90, lon_s=0, lon_e=360, to_range='0_360', n_modes=1, remove_trend=False, rotated=None, use_coslat=True, standardize=False, normalize_pattern=True, normalize_index=False)

Calculate regional EOF (Empirical Orthogonal Functions) modes from gridded SST data.

This generalized function computes EOFs for a specified regional domain, allowing for trend removal, rotation, and different normalization options.

Parameters:

dataxarray.DataArray or xarray.Dataset, optional

Gridded SST data with dimensions (time, lat, lon). Use ‘path’ and ‘var’ instead if you want to load the data from a file.

pathstr, optional

Directory path to the data. Required if ‘data’ is not provided.

varstr, optional

Name of the variable to load from the dataset.

clim_startint, optional

Climatology start year.

clim_endint, optional

Climatology end year (if both None, the entire period is used for climatology).

desiredlist, optional

Desired outputs, which can be [‘regional_patterns’, ‘regional_timeseries’, ‘variance_fractions_regional’]. Default is all three.

start_timeint, optional

Start year for loading data.

end_timeint, optional

End year for loading data.

lat_sfloat, optional

Start latitude for the regional selection. Default is 90.

lat_efloat, optional

End latitude for the regional selection. Default is -90.

lon_sfloat, optional

Start longitude for the regional selection. Default is 0.

lon_efloat, optional

End longitude for the regional selection. Default is 360.

to_rangestr, optional

Target longitude range. Default is ‘0_360’. Use ‘-180_180’ if needed.

n_modesint, optional

Number of EOF modes to compute. Default is 1.

remove_trendbool, optional

Whether to remove the global trend before calculating EOFs. Default is False.

rotatedstr, optional

Whether to apply Varimax or Promax rotation to the EOFs. Default is False.

use_coslatbool, optional

Whether to use cosine latitude weighting. Default is True.

standardizebool, optional

Whether to normalize the data with its standard deviation before EOF calculation. Default is False.

normalize_patternbool, optional

Whether to normalize spatial components (patterns) with singular values. Default is True.

normalize_indexbool, optional

Whether to normalize the time series (scores) with singular values. Default is False.

Returns:

List containing the desired outputs: regional patterns, timeseries, and/or variance fractions.

xIndices.indices.compute_pdo(data=None, path=None, var=None, clim_start=None, clim_end=None, desired=None, start_time=None, end_time=None, to_range='0_360', standardize=False, normalize_pattern=True, normalize_index=False, lat_s=70, lat_e=20, lon_s=110, lon_e=260, remove_trend=False)

Calculate the PDO (Pacific Decadal Oscillation) index and pattern.

This function calculates the conventional PDO index, pattern, and variance fraction as the first EOF modes of SST anomaly in the North Pacific (above 20°N) after removing the annual cycle climatology and global mean SST (to account for the warming trend).

Parameters:

dataxarray.DataArray or xarray.Dataset, optional

Gridded SST data with dimensions (time, lat, lon). Use ‘path’ and ‘var’ instead if you want to load the data from a file.

pathstr, optional

Directory path to the data. Required if ‘data’ is not provided.

varstr, optional

Name of the variable to load from the dataset.

clim_startint, optional

Climatology start year.

clim_endint, optional

Climatology end year (if both None, whole period will be chosen for climatology).

desiredlist, optional

Desired outputs, which can be [‘pdo_pattern’, ‘pdo_index’, ‘variance_fraction_pdo’]. Default is all three.

start_timeint, optional

Start year for loading data.

end_timeint, optional

End year for loading data.

to_rangestr, optional

Target longitude range. Default is ‘0_360’. Use ‘-180_180’ if needed.

standardizebool, optional

Whether to normalize the data with its standard deviation.

normalize_patternbool, optional

Whether to normalize spatial components with singular values. Default is True.

normalize_indexbool, optional

Whether to normalize the time series (scores) with singular values. Default is False.

remove_trendbool, optional

Whether to remove the global trend. Default is False, in which case mode 2 is used. If True, mode 1 is used.

Returns:

List containing the desired outputs: PDO pattern, PDO index, and/or variance fraction.

xIndices.indices.compute_amo(data=None, path=None, var=None, clim_start=None, clim_end=None, desired=None, start_time=None, end_time=None, lat_s=70, lat_e=0, lon_s=280, lon_e=360, to_range='0_360')

Calculate the AMO (Atlantic Multidecadal Oscillation) index and pattern.

This function calculates the conventional AMO index and AMO pattern as the area-averaged SST anomalies and time-averaged SST anomalies in the North Atlantic (0°N-70°N) after removing the annual cycle climatology and global mean SST (to account for the warming trend).

Parameters:

dataxarray.DataArray or xarray.Dataset, optional

Gridded SST data with dimensions (time, lat, lon). Use ‘path’ and ‘var’ instead if you want to load the data from a file.

pathstr, optional

Directory path to the data. Required if ‘data’ is not provided.

varstr, optional

Name of the variable to load from the dataset.

start_timeint, optional

Start year for loading data.

end_timeint, optional

End year for loading data.

clim_startint, optional

Climatology start year.

clim_endint, optional

Climatology end year (if both None, whole period will be chosen for climatology).

desiredlist, optional

Desired outputs, which can be [‘amo_pattern’, ‘amo_index’]. Default is both.

lat_sfloat, optional

Start latitude for the region. Default is 70 (North).

lat_efloat, optional

End latitude for the region. Default is 0 (Equator).

lon_sfloat, optional

Start longitude for the region. Default is 280 (Western Atlantic).

lon_efloat, optional

End longitude for the region. Default is 360.

to_rangestr, optional

Target longitude range. Default is ‘0_360’. Use ‘-180_180’ if needed.

Returns:

List containing the desired outputs: AMO pattern and/or AMO index.

xIndices.indices.compute_nao(data=None, path=None, var=None, clim_start=None, clim_end=None, desired=None, lat_s=None, lat_e=None, use_coslat=None, standardize=None, to_range=None, n_modes=10, nao_mode=None, start_time=None, end_time=None, rotated='Varimax')

This function calculates the NAO index, NAO pattern, and variance fraction. It is calculated as the second EOF mode of 500mb geopotential height anomaly above 20N after removing the annual cycle climatology.

Parameters: - data : xarray.DataArray or xarray.Dataset

Processed gridded data in the shape of (time, lat, lon).

• pathstr, optional

  Path to the data file (if data is to be loaded directly).

• varstr, optional

  Variable name in the dataset (used if loading from a file).

• clim_startint, optional

  Climatology start year.

• clim_endint, optional

  Climatology end year. If None, the whole period will be used.

• desiredlist, optional

  List of desired outputs, e.g., [‘nao_pattern’, ‘nao_index’, ‘variance_fraction_nao’].

• lat_sfloat, optional

  Start latitude for selecting the northern region.

• lat_efloat, optional

  End latitude for selecting the northern region.

• use_coslatbool, optional

  Whether to apply cosine latitude weighting. Default is True.

• standardizebool, optional

  If True, standardizes the data. Default is False.

• to_rangestr, optional

  Longitude range, either ‘0_360’ or ‘-180_180’. Default is ‘0_360’.

• nao_modeint, optional

  The EOF mode number to be considered as NAO. Default is 1.

• start_time, end_timestr, optional

  Time range for selecting data.

• rotatedstr, optional

  Rotation method for EOFs. Options: None, ‘Varimax’, ‘Promax’. Default is ‘Varimax’.

xIndices.preprocess_data module

xIndices.preprocess_data.load_data(path, var=None, start_time=None, end_time=None, lat_s=None, lat_e=None, lon_s=None, lon_e=None)

Load variables from NetCDF files as xarray.DataArray or Dataset.

Parameters:

pathstr

Path to the NetCDF file.

varstr, optional

Variable name to extract from the file. If None, the entire dataset is returned.

start_timestr, optional

Start year in ‘YYYY’ format for the time range selection.

end_timestr, optional

End year in ‘YYYY’ format for the time range selection.

lat_sfloat, optional

Start latitude for spatial selection. If None, the full latitude range is selected.

lat_efloat, optional

End latitude for spatial selection. If None, the full latitude range is selected.

lon_sfloat, optional

Start longitude for spatial selection. If None, the full longitude range is selected.

lon_efloat, optional

End longitude for spatial selection. If None, the full longitude range is selected.

Returns:

xarray.DataArray or xarray.Dataset

The selected subset of data based on the provided parameters.

xIndices.preprocess_data.regridding(ds, ds_out=None, var=None, method=None, to_range=None, x_s=None, x_e=None, x_i=None, y_s=None, y_e=None, y_i=None)

This function is useful for regridding rectilinear and curvilinear grids.

dsxarray.Dataset or xarray.DataArray

The dataset or dataarray containing the variable grid to be regridded.

ds_outxarray.Dataset or xarray.DataArray

The target dataset or dataarray containing the target grid. if ds_out is None, regridding will be done using a generic grid made using xe, xs, ye, ys, xi, and yi.

var :

The name of the variable to be regridded. If None, it is assumed that ds and ds_out are DataArrays.

to_range :

The target longitude range, either ‘0_360’ or ‘-180_180’. Default is ‘0_360’.

methodstr, optional

The method for regridding. Default is ‘bilinear’. Other values can be: [‘bilinear’, ‘conservative’, ‘patch’, ‘conservative_normed’, ‘nearest_s2d’, ‘nearest_d2s’]. For more details, see: - https://xesmf.readthedocs.io/en/stable/notebooks/Compare_algorithms.html - https://earthsystemmodeling.org/esmpy_doc/release/latest/ESMPy.pdf

x_s: start longitude x_e: end longitude’ x_i: lon increment

y_s: start latitude y_e: end latitude’ y_i: lat increment

To perform regridding from Curvilinear data to rectilinear data we suggest providing Curvilinear as ds and rectilinear as ds_out.

xIndices.preprocess_data.write_netcdf(data, file_path)

Save the given data to a NetCDF file.

Parameters: data (xarray.Dataset or xarray.DataArray): The data to be saved. file_path (str): The path where the NetCDF file will be saved.

Returns: None

xIndices.preprocess_data.adjust_longitude(ds, lon_name='lon', to_range='0_360')

Adjusts the longitude values in the given dataset to the specified range. Parameters: ds (xarray.Dataset): The input dataset containing longitude values. lon_name (str, optional): The name of the longitude variable in the dataset. Default is ‘lon’. to_range (str, optional): The target range for longitude values.

Can be ‘0_360’ for [0, 360) or ‘-180_180’ for [-180, 180). Default is ‘0_360’.

Returns: xarray.Dataset: The dataset with adjusted longitude values. Raises: ValueError: If the specified target range is not ‘0_360’ or ‘-180_180’.

xIndices.preprocess_data.adjust_latitude(ds, lat_name='lat')

Adjusts the latitude coordinates of an xarray Dataset to be in descending order.

Parameters: ds (xarray.Dataset): The input dataset containing latitude coordinates. lat_name (str, optional): The name of the latitude coordinate in the dataset. Default is ‘lat’.

Returns: xarray.Dataset: The dataset with latitude coordinates sorted in descending order.

xIndices.preprocess_data.rename_dims_to_standard(ds)

Rename the dimensions of an xarray Dataset to standard names (‘lon’, ‘lat’, ‘time’) based on their units. Parameters: ds (xarray.Dataset): The input dataset with dimensions to be renamed. Returns: xarray.Dataset: The dataset with renamed dimensions if applicable. The function performs the following steps: 1. Detects the longitude dimension by checking for the unit ‘degrees_east’. 2. Detects the latitude dimension by checking for the unit ‘degrees_north’. 3. Detects the time dimension by checking for units like ‘days since’, ‘seconds since’, or ‘months since’. 4. Renames the detected dimensions to ‘lon’, ‘lat’, and ‘time’ respectively.

xIndices.utils module

xIndices.utils.calculate_anomaly(data, clim_start=None, climatology_dim='time', clim_end=None, freq='month')

Calculate anomalies by subtracting the climatology from the data.

Parameters: data (xarray.DataArray or xarray.Dataset): The input data from which to calculate anomalies. clim_start (str, optional): The start year for the climatology period in ‘YYYY’ format. If None, the entire period is used. climatology_dim (str, optional): The dimension over which to calculate the climatology. Default is ‘time’. clim_end (str, optional): The end year for the climatology period in ‘YYYY’ format. If None, the entire period is used. freq (str, optional): The frequency for grouping the data. Must be either ‘month’ or ‘dayofyear’. Default is ‘month’.

Returns: xarray.DataArray or xarray.Dataset: The anomalies calculated by subtracting the climatology from the data.

Raises: ValueError: If the frequency is not ‘month’ or ‘dayofyear’.

xIndices.utils.compute_weights(data, lat_dim=None)

Compute weights based on the cosine of latitude values.

Parameters: data (xarray.DataArray or xarray.Dataset): The input data containing latitude values. lat_dim (str, optional): The name of the latitude dimension in the data. Defaults to ‘lat’.

Returns: xarray.DataArray: Weights computed as the cosine of the latitude values in radians.

xIndices.utils.line_plot(data, figsize=None, dpi=None, variance_fraction=None, color=None, label=None)

Plots a line graph for the given data.

Parameters: data (xarray.DataArray): The data to be plotted. Must be 1-dimensional and contain a ‘time’ dimension. figsize (tuple, optional): The size of the figure in inches (width, height). Defaults to None. dpi (int, optional): The resolution of the figure in dots per inch. Defaults to None. variance_fraction (float, optional): A variance fraction value to be displayed on the plot. Defaults to None. color (str, optional): The color of the line plot. Defaults to None. label (str, optional): The label for the plot. Defaults to None.

Returns: None

Raises: Exception: If an error occurs during plotting, it prints an error message.

xIndices.utils.contour_plot(data, projection=None, figsize=None, dpi=None, cmap=None, extend=None, levels=None, central_lon=None, central_lat=None, ax_global=False)

Generate a contour plot for the given data. Parameters: data (xarray.DataArray): The data to be plotted. Must be a 2D array with ‘lat’ and ‘lon’ dimensions. projection (cartopy.crs.Projection, optional): The map projection to use. Defaults to PlateCarree with central_longitude. figsize (tuple, optional): The size of the figure in inches (width, height). Defaults to None. dpi (int, optional): The resolution of the figure in dots per inch. Defaults to None. cmap (str or matplotlib.colors.Colormap, optional): The colormap to use for the plot. Defaults to None. extend (str, optional): Whether to extend the colorbar at the ends. Options are ‘neither’, ‘both’, ‘min’, ‘max’. Defaults to None. levels (list, optional): The contour levels to use. Defaults to 10 levels between the min and max of the data. central_lon (float, optional): The central longitude for the projection. Defaults to 0. central_lat (float, optional): The central latitude for the projection. Defaults to 0. ax_global (bool, optional): Whether to set the axis to global. Defaults to False. Returns: None

xIndices.utils.compute_rotated_eofs(data, rotated=None, n_modes=None, standardize=None, use_coslat=None)

Compute EOFs using the xeofs module, with optional Varimax or Promax rotation.

Parameters:

dataxarray.DataArray

Input data with a time dimension.

rotatedstr, optional

Specify ‘Varimax’ for orthogonal rotation or ‘Promax’ for oblique rotation. Leave as None for unrotated EOFs.

n_modesint, default=10

Number of modes to compute.

standardizebool, optional

Whether to standardize the data. Default is False.

use_coslatbool, optional

If True (default), weights EOFs by the cosine of latitude for area-averaging.

Returns:

modelxeofs.single.EOF or xeofs.single.EOFRotator

The fitted EOF model, either rotated or unrotated.

Notes:

• Varimax corresponds to orthogonal rotations (power=1).

• Promax corresponds to oblique rotations (power=4).

• Returns None if an invalid rotation option is provided.

xIndices.utils.lanczos_filter_xarray(data, dT=1, Cf=None, Cf2=None, M=100, filter_type='low', time_dim=None)

Apply a Lanczos filter to an xarray DataArray using FFT-based filtering.

Parameters: - data (xarray.DataArray): Input data to filter - dT (float): Sampling interval (default: 1) - Cf (float): Lower cut-off frequency in 1/dT units (default: Nyquist/2 for low/high-pass) - Cf2 (float): Upper cut-off frequency (only used for bandpass) - M (int): Number of coefficients (default: 100) - filter_type (str): Type of filter - ‘low’, ‘high’, or ‘band’ - time_dim (str): The name of the time dimension (default: auto-detect)

Returns: - xarray.DataArray: Filtered data