Contents

momlevel.util module

util.py - generic utilities for momlevel

momlevel.util.annual_average(xobj, tcoord='time')

Function to calculate annual averages

This function calculates the annual average of the supplied xarray object. The average is weighted by the number of days in the month, as inferred from the calendar attributes of the time coordinate objects. Non-numeric variables are skipped.

Parameters:

  • xobj (xarray.core.dataset.Dataset or xarray.core.dataarray.DataArray) – Input xarray object

  • tcoord (str, optional) – Name of time coordinate, by default “time”

Return type:

xarray.core.dataset.Dataset

momlevel.util.annual_cycle(xobj, tcoord='time', func='mean', time_axis_year=None)

Function to calculate annual cycle climatology

This function calculates the annual cycle climatology from an xarray dataset containing monthly timeseries variables.

Parameters:

  • xobj (xarray.core.dataset.Dataset or xarray.core.dataarray.DataArray) – Input xarray object

  • tcoord (str, optional) – Name of time coordinate, by default “time”

  • func (str, optional) – “mean”, “std”, “min”, or “max” across for the climatology, by default “mean”

  • time_axis_year (int, optional) – Specify year used in resulting time axis, otherwise use the mean year for the entire dataset, by default None

Returns:

Annual cycle climatology with 12 time points, 1 per month

Return type:

xarray.core.dataset.Dataset

momlevel.util.default_coords(coord_names=None)

Function to set the default coordinate names

This function reads the coordinate names dictionary and returns either the specified values or the default values if missing from coord_names.

Parameters:

coord_names (dict, optional) – Dictionary of coordinate name mappings. This should use x, y, z, and t as keys, e.g. {“x”:”xh”, “y”:”yh”, “z”:”z_l”, “t”:”time”}. Coordinate bounds are noted by appending “bounds” to each key, i.e. “zbounds”

Returns:

Default coordinate names

Return type:

Tuple

momlevel.util.geolocate_points(df_model, df_locs, threshold=None, model_coords=('geolat', 'geolon'), rad_earth=6378.0, loc_coords=('lat', 'lon'), apply_mask=True, disable_warning=True)

Function to map a set of real-world locations to model grid points

This function compares two Pandas DataFrame objects to map a set of real-world locations to their nearest model grid points. The function generates a ball tree for computational efficiency and uses a haversine, or great-circle, distance metric. An optional distance threshold may be specified to filter out locations that are too far away from a model grid point.

Parameters:

  • df_model (pandas.core.frame.DataFrame) – DataFrame containing all model grid points

  • df_locs (pandas.core.frame.DataFrame) – DataFrame containing real-world locations to map to model grid

  • threshold (float, optional) – Filter out points that exceed this distance threshold in km, by default None

  • model_coords (Tuple[str, str], optional) – Names of DataFrame columns corresponding to the columns that identify the model’s latitude and longitude values, by default (“geolat”,”geolon”)

  • rad_earth (float, optional) – Radius of the earth, by default 6.378e03 km

  • loc_coords (Tuple[str, str]) – Names of DataFrame columns corresponding to the columns that identify the real-world latitude and longitude values, by default (“lat”,”lon”)

  • apply_mask (bool, optional) – Only consider valid model points based on the values of the mask column in df_model. If mask == 1, it is considered a valid point. By default, True

  • disable_warning (bool, optional) – Disable warnings when a requested point cannot be mapped. This option is set to True by default as requesting locations for regional model configurations can yield numerous message. Enabling the warnings may be useful in some cases, however. By default, True

Returns:

The df_locs DataFrame is returned with additional columns that map the points to the model grid

mod_indexint

Index value of selected point in df_model

distancefloat

Physical distance in km between the location and the selected grid cell location

model_coordstuple(float,float)

Coordinates of selected model grid cell

dim_valstuple(float or int, float or int)

Dimension values of selected model grid cell

Return type:

pandas.core.frame.DataFrame

momlevel.util.get_pv_colormap()

This function returns a colormap for potential vorticity

momlevel.util.get_xgcm_grid(dset, coord_dict=None, symmetric=False)

Function to generate xgcm grid

This function generates an xgcm grid based on an input dataset. Default MOM6 coordinate names are assumed but can be overridden using the coord_dict kwarg. Symmetric grids should be identified by setting symmetric=True.

Parameters:

  • dset (xarray.core.dataset.Dataset) – Input dataset

  • coord_dict (dict, optional) – Dictionary of xgcm coordinate name mappings, if different from the MOM6 default values, by default None

  • symmetric (bool) – Flag denoting symmetric grid, by default False

Returns:

Grid object from xgcm

Return type:

xgcm.Grid

momlevel.util.linear_detrend(*args, **kwargs)
momlevel.util.monthly_average(xobj, tcoord='time')

Function to calculate monthly averages from daily data

This function calculates monthly averages of the supplied xarray object. Non-numeric variables are skipped.

Parameters:

  • xobj (xarray.core.dataset.Dataset or xarray.core.dataarray.DataArray) – Input xarray object

  • tcoord (str, optional) – Name of time coordinate, by default “time”

Return type:

xarray.core.dataset.Dataset

momlevel.util.tile_nominal_coords(xcoord, ycoord, warn=True)

Function to convert 1-D dimensions to 2-D coordinate variables

This function converts 1-dimensional arrays of x and y coordinates to 2-dimensional lon and lat variables. This function is appropriate for regular lat-lon grids but should not be used with ocean model nominal coordinates associated with irregular grids.

Parameters:

  • xcoord (xarray.core.dataarray.DataArray) – x or longitude 1D coordinate

  • ycoord (xarray.core.dataarray.DataArray) – y or latitude 1D coordinate

  • warn (bool, optional) – Issue warning message, by default True

Returns:

2-dimensional longitude and latitude variables

Return type:

Tuple[xarray.core.dataarray.DataArray, xarray.core.dataarray.DataArray]

momlevel.util.validate_areacello(areacello, reference=361110920000000.0, tolerance=0.02)

Function to test validity of ocean cell area field

This function tests if the sum of the ocean cell area is within a specified tolerance of a real-world value.

The intent of this function is to identify gross deviations, such as the inadvertent use of the global surface area.

Parameters:

  • areacello (xarray.core.dataarray.DataArray) – Field containing ocean cell area

  • reference (float, optional) – Sum of ocean surface area in meters, by default 3.6111092e14

  • tolerance (float, optional) – Acceptable +/- tolerance range percentage, by default 0.02

Returns:

True if areacello is within tolerance

Return type:

bool

momlevel.util.validate_dataset(dset, reference=False, strict=True, additional_vars=None)

Function to validate requirements of the datasets

This function determines if a supplied dataset is either a valid input dataset or reference dataset. It checks for the presence of required fields and that they have the correct dimensionality.

Errors are collected and reported back as a group.

Parameters:

  • dset (xarray.core.dataset.Dataset) – Dataset supplied for validation

  • reference (bool, optional) – Flag denoting if dset is a reference dataset, by default False

  • strict (bool, optional) – If true, errors are handled as fatal Exceptions. If false, warnings are issued, by default True

  • additional_vars (list, optional) – List of additional variables to check for in the dataset

Return type:

None

momlevel.util.validate_tidegauge_data(arr, xcoord, ycoord, mask)

Function to validate inputs to tidegauge.extract_tidegauge

This function validates the input arguments before the tide gauge point extraction function continues

Parameters:

  • arr (xarray.core.dataarray.DataArray) – Input DataArray object

  • xcoord (xarray.core.dataarray.DataArray or str) – x-coordinate name or object

  • ycoord (xarray.core.dataarray.DataArray or str) – y-coordinate name or object

  • mask (xarray.core.dataarray.DataArray or None) – wet mask array

momlevel.trend module