Module mjoindices.olr_handling

This module provides basic functionality to handle OLR data, which is the basic input for the OMI calculation.

class mjoindices.olr_handling.OLRData(olr: ndarray, time: ndarray, lat: ndarray, long: ndarray)[source]

This class serves as a container for spatially distributed and temporally resolved OLR data.

A filled object of this class has to be provided by the user in order to start the OMI calculation.

Parameters:

  • olr – The OLR data as a 3-dim array. The three dimensions correspond to time, latitude, and longitude, in this order.

  • time – The temporal grid as 1-dim array of numpy.datetime64 dates.

  • lat – The latitude grid as 1-dim array.

  • long – The longitude grid as 1-dim array.

close(other: OLRData) → bool[source]

Checks equality of two OLRData objects, but allows for numerical tolerances.

Parameters:

other – The object to compare with.

Returns:

Equality of all members considering the default tolerances of numpy.allclose()

extract_olr_matrix_for_doy_range(center_doy: int, window_length: int = 0, leap_year_treatment: str = 'original') → ndarray[source]

Extracts a range of OLR data from the DOYs around one center DOY (center_doy +/- windowlength).

Keep in mind that the OLR time series might span several years. In this case the center DOY is found more than once and the respective window in considered for each year. Example: 3 full years of data, centerdoy = 20, and window_length = 4 results in 3*(2*4+1) = 27 entries in the time axis

Parameters:

  • center_doy – The center DOY of the window.

  • window_length – The window length of DOYs on both sides of the center DOY. Hence, if the window is fully covered by the data, one gets :math:2*window_length + 1 entries per year in the result.

  • leap_year_treatment – see :py:func:mjoindices.omi.omi_calculator.calc_eofs_from_olr.

Returns:

The excerpt of the OLR data as a 3-dim array. The three dimensions correspond to time, latitude, and longitude, in this order.

get_olr_for_date(date: datetime64) → ndarray[source]

Returns the spatially distributed OLR map for a particular date.

Parameters:

date – The date, which has to be exactly matched by one of the dates in the OLR time grid.

Returns:

The excerpt of the OLR data as a 2-dim array. The two dimensions correspond to latitude and longitude, in this order. Returns None if the date is not contained in the OLR time series.

property lat

The latitude grid as 1-dim array.

property long

The longitude grid as 1-dim array.

property olr

The OLR data as a 3-dim array. The three dimensions correspond to time, latitude, and longitude, in this order.

save_to_npzfile(filename: Path) → None[source]

Saves the data arrays contained in the OLRData object to a numpy file.

Parameters:

filename – The full filename.

property time

The temporal grid as 1-dim array of numpy.datetime64 dates.

mjoindices.olr_handling.interpolate_spatial_grid(olr: OLRData, target_lat: ndarray, target_long: ndarray) → OLRData[source]

Interpolates the OLR data linearly onto the given grids.

No extrapolation will be done. Instead, a ValueError is raised if the data does not cover the target grid.

Note that no sophisticated resampling is provided here. If some kind of averaging, etc., is needed, it should be performed by the user before injecting the data into the OMI calculation.

Parameters:

  • olr – The OLR data to resample.

  • target_lat – The new latitude grid.

  • target_long – The new longitude grid.

Returns:

A new OLRData object containing the resampled OLR data.

mjoindices.olr_handling.interpolate_spatial_grid_to_original(olr: OLRData) → OLRData[source]

Convenience function that interpolates the OLR data in an OLRData object spatially onto the spatial grid, which was used for the original OMI calculation by Kiladis et al. (2014).

This original grid has the following properties:

  • Latitude: 2.5 deg-sampling in the tropics from -20 to 20 deg (20 S to 20 N).

  • Longitude: Whole globe with 2.5 deg-sampling.

Parameters:

olr – The OLR data

Returns:

A new OLRData object with the interpolated data.

mjoindices.olr_handling.load_noaa_interpolated_olr(filename: Path, use_xarray: bool = False) → OLRData[source]

Loads the standard OLR data product provided by NOAA in NetCDF3 format. This is mainly used to load the OLR files originally used for the OMI calculation some years ago.

ATTENTION: Note that the file format was changed by NOAA from NetCDF3 to NetCDF4 sometime between the years 2019 and 2021. If you are using a recent download of the data and experience problems with this loader method, you should use load_noaa_interpolated_olr_netcdf4() instead.

The original OLR data file is contained in the reference data package found at: https://doi.org/10.5281/zenodo.3746562

The current dataset can be obtained from https://www.psl.noaa.gov/thredds/catalog/Datasets/interp_OLR/catalog.html?dataset=Datasets/interp_OLR/olr.day.mean.nc

A description is found at https://psl.noaa.gov/data/gridded/data.olrcdr.interp.html

Parameters:

  • filename – Full filename of a local copy of OLR data file.

  • use_xarray – Option to use xarray instead of SciPy netcdf for faster loading of data and timestamps. Note that OMI values based on this parameter have not been validated. The respective unit tests currently fail when this option is activated, however, this is probably only caused by very small numerical differences, which are irrelevant for the actual use. Still make sure that you trust the values when activating the option. A further advantage of this option is that is works for NetCDF3 and NetCDF4 files, hence for the older and the newer NOAA OLR datafiles.

Returns:

The OLR data.

mjoindices.olr_handling.load_noaa_interpolated_olr_netcdf4(filename: Path, use_xarray: bool = False) → OLRData[source]

Loads the standard OLR data product provided by NOAA in NetCDF4 format.

ATTENTION: Whereas NetCDF4 seems to be the format of the recent NOAA OLR data files, the files originally used some years ago were saved as NetCDF3. So, if you are going to load the original files for reference purposes, you should use the loader function load_noaa_interpolated_olr() instead.

The dataset can be obtained from https://www.psl.noaa.gov/thredds/catalog/Datasets/interp_OLR/catalog.html?dataset=Datasets/interp_OLR/olr.day.mean.nc

A description is found at https://psl.noaa.gov/data/gridded/data.olrcdr.interp.html

Parameters:

  • filename – Full filename of a local copy of OLR data file.

  • use_xarray – Option to use xarray instead of NetCDF4 for faster loading of data and timestamps. If you consider activating this parameter, you should call instead load_noaa_interpolated_olr(), since it works for NetCDF 3 and 4. Later on, when the xarray option is established, the present function particularly for NetCDF4 will be removed. Please also take into account the warnings in the docs of load_noaa_interpolated_olr().

Returns:

The OLR data.

mjoindices.olr_handling.plot_olr_map_for_date(olr: OLRData, date: datetime64) → Figure[source]

Plots a map pf the OLR data for a specific date.

Parameters:

  • olr – The complete OLR data.

  • date – The date for which the OLR data should be plotted (has to be exactly matched by a date of the OLR time grid).

Returns:

The handle to the figure.

mjoindices.olr_handling.remove_leap_years(olr: OLRData) → OLRData[source]

Removes any leap days (any instances of February 29) and returns an OLRData object with the remaining OLR data

Parameters:

olr – The OLR data to restrict.

Returns:

A new OLRData object with no leap days

mjoindices.olr_handling.restore_from_npzfile(filename: Path) → OLRData[source]

Loads an OLRData object from a numpy file, which has been saved with the function mjoindices.olr_handling.OLRData.save_to_npzfile()

Parameters:

filename – The filename to the .npz file.

Returns:

The OLR data.

mjoindices.olr_handling.restrict_time_coverage(olr: OLRData, start: datetime64, stop: datetime64) → OLRData[source]

Cuts the OLR time series at the given dates (given dates are included).

This is useful when the OLR data should be restricted for the EOF calculation, which is based on a subset. Of course, it can also be used to limit the PC calculation to a specific period.

Note that a temporal resampling method is not provided here, since the possible resampling methods, which the users might want to apply, are too diverse. Hence, it is assumed that the temporal spacing is already correct (daily averages recommended) and only a restriction of the period is needed before calculation.

Parameters:

  • olr – The OLR data to restrict.

  • start – The beginning of the wanted period of OLR data (included).

  • stop – The ending of the wanted period (included).

Returns:

A new OLRData object with restricted temporal coverage.

Raises:

ValueError if no OLR Data is found for the specified period