External climatology class

class marine_qc.Climatology(data, time_axis=None, lat_axis=None, lon_axis=None, source_units=None, target_units=None, valid_ntime=None)[source]

Class for dealing with climatologies, reading, extracting values etc.

Automatically detects if this is a single field, pentad or daily climatology.

Parameters:

  • data (xr.DataArray) – Climatology data.

  • time_axis (str, optional) – Name of time axis. Set if time axis in data is not CF compatible.

  • lat_axis (str, optional) – Name of latitude axis. Set if latitude axis in data is not CF compatible.

  • lon_axis (str, optional) – Name of longitude axis. Set if longitude axis in data is not CF compatible.

  • source_units (str, optional) – Name of units in data. Set if units are not defined in data.

  • target_units (str, optional) – Name of target units to which units must conform.

  • valid_ntime (int or list, default: [1, 73, 365]) – Number of valid time steps: - 1: single field climatology - 73: pentad climatology - 365: daily climatology

convert_units_to(target_units, source_units=None)[source]

Convert units to user-specific units.

Parameters:

  • target_units (str) – Target units to which units must conform.

  • source_units (str, optional) – Source units if not specified in Climatology.

Return type:

None

Notes

For more information see: xclim.core.units.convert_units_to()

static get_t_index(month, day, ntime)[source]

Convert arrays of months and days to an array of indices for the grid.

Parameters:

  • month (ndarray) – Array of months.

  • day (ndarray) – Array of days.

  • ntime (int) – Number of time points in the grid, valid values are 1, 73 (pentad resolution) and 365 (daily resolution).

Return type:

ndarray

Returns:

ndarray – Array of indices.

get_tindex(month, day)[source]

Get the time index of the input month and day.

Parameters:

  • month (int) – Month for which the time index is required.

  • day (int) – Day for which the time index is required.

Return type:

int

Returns:

int – Time index for specified month and day.

get_value(lat, lon, date=None, month=None, day=None)[source]

Get the value from a climatology at the give position and time.

Parameters:
Return type:

ndarray | Series

Returns:

ndarray or pd.Series – Climatology value at specified location and time.

Notes

Use only exact matches for selecting time and nearest valid index value for selecting location.

get_value_fast(lat, lon, date=None, month=None, day=None)[source]

Get the value from a climatology at the give position and time.

Parameters:
Return type:

ndarray | Series

Returns:

ndarray or pd.Series – Climatology value at specified location and time.

Notes

Assumes that the grid is a regular latitude longitude grid. The alternative method get_value works with non-regular grids.

static get_x_index(lon_arr, lon_axis)[source]

Convert an array of longitudes to an array of indices for the grid.

Parameters:

  • lon_arr (ndarray) – Array of longitudes.

  • lon_axis (ndarray) – Array containing the longitude axis.

Return type:

ndarray

Returns:

ndarray – Array of indices.

static get_y_index(lat_arr, lat_axis)[source]

Convert an array of latitudes to an array of indices for the grid.

Parameters:

  • lat_arr (np.ndarray) – Array of latitudes.

  • lat_axis (np.ndarray) – Array containing the latitude axis.

Return type:

ndarray

Returns:

np.ndarray – Array of indices.

classmethod open_netcdf_file(file_name, clim_name, **kwargs)[source]

Open a NetCDF climatology file and construct a Climatology instance.

Parameters:

  • file_name (str or path-like) – Path to the NetCDF file to open.

  • clim_name (str) – Name of the climatology variable within the NetCDF file.

  • **kwargs (dict) – Additional keyword arguments passed to the Climatology constructor.

Return type:

Climatology

Returns:

Climatology – A Climatology instance constructed from the specified variable in the NetCDF file. If the file cannot be opened, an empty climatology object is returned.

External climatology functions

marine_qc.external_clim.get_climatological_value(climatology, **kwargs)[source]

Get the value from a climatology.

Parameters:

  • climatology (Climatology) – Climatology class.

  • **kwargs (dict) – Pass keyword-arguments to :py:func:~Climatology.get_value`.

Return type:

ndarray

Returns:

ndarray – Climatology value at specified location and time.

marine_qc.external_clim.open_xrdataset(files, use_cftime=True, decode_cf=False, decode_times=False, parallel=False, data_vars='minimal', chunks='default', coords='minimal', compat='override', combine='by_coords', **kwargs)[source]

Optimized function for opening large CF-compliant datasets with xarray.

This implementation follows guidance from: https://github.com/pydata/xarray/issues/1385#issuecomment-561920115

decode_timedelta=False is added to leave variables and coordinates with time units in {“days”, “hours”, “minutes”, “seconds”, “milliseconds”, “microseconds”} encoded as numbers.

Parameters:
Return type:

Dataset

Returns:

xarray.Dataset – Opened xarray Dataset, optimized for large CF datasets.