Module mjoindices.omi.omi_calculator¶

This major module provides the execution of the algorithm of the OMI calculation.

First, the algorithm can be used to compute the empirical orthogonal functions (EOFs), which serve as a new basis for the OLR data. According to the OMI algorithm, the EOFs have to be computed for each day of the year (DOY). Second, the time-dependent coefficients of the OLR maps w.r.t the EOFs are computed. These coefficients are called the principal components (PCs).

The complete algorithm is described in Kiladis et al. (2014).

Basically, only OLR data on a suitable spatial grid is needed. With that, the OMI EOFs and afterwards the PCs are computed using the functions calc_eofs_from_olr() and calculate_pcs_from_olr(), respectively.

In terms of the post-processing of the EOFs (before the PCs are calculated), the following options are available. They are selected with the parameter eofs_postprocessing_type of the function calc_eofs_from_olr()

The original approach is described in Kiladis et al. (2014). Details are found in post_process_eofs_original_kiladis_approach()
An alternative post-processing procedure may be used to reduce noise and potential degeneracy issues. This algorithm is described in Weidman et al. (2022). The alternative post-processing procedure is explained in post_process_eofs_rotation().

mjoindices.omi.omi_calculator.calc_eofs_for_doy(olrdata: OLRData, doy: int, leap_year_treatment: str = 'original') → EOFData[source]¶

Calculates a pair of EOFs for a particular DOY.

An explicit internal implementation of the EOF approach is used.

Note that it is recommended for the end user to call the function py:func:calc_eofs_from_olr to cover the complete algorithm.

Parameters:

olrdata – The filtered OLR data to calculate the EOFs from.
doy – The DOY for which the EOFs are calculated.
leap_year_treatment – see calc_eofs_from_olr().

Returns:

An object containing the pair of EOFs together with diagnostic values.

See also

calc_eofs_for_doy()

mjoindices.omi.omi_calculator.calc_eofs_from_olr(olrdata: OLRData, implementation: str = 'internal', leap_year_treatment: str = 'original', eofs_postprocessing_type: str = 'kiladis2014', eofs_postprocessing_params: Optional[dict] = None, sign_doy1reference: Optional[bool] = None, interpolate_eofs: Optional[bool] = None, interpolation_start_doy: Optional[int] = None, interpolation_end_doy: Optional[int] = None, strict_leap_year_treatment: Optional[bool] = None) → EOFDataForAllDOYs[source]¶

One of the major functions of this module. It performs the complete OMI EOF computation.

This function executes consistently the preprocessing (filtering), the actual EOF analysis, and the postprocessing.

Parameters:

olrdata – The OLR dataset, from which OMI should be calculated. Note that OLR values are assumed to be given in positive values. The spatial grid of the OLR datasets defines also the spatial grid of the complete OMI calculation.
implementation –
Choose one of the following values:
- "internal": uses the internal implementation of the EOF approach.
- "eofs_package": Uses the implementation of the external package eofs.
leap_year_treatment –
Choose one of the following values:
- "original" will be as close to the original version of Kiladis et al. (2014) as possible.
- "strict" (not recommended) will treat leap years somewhat more strictly, which might, however, cause the results to deviate from the original. See also description in find_doy_ranges_in_dates().
- "no_leap_years" will act as if there are no leap years in the dataset (365 days consistently), which might be useful for modeled data.
eofs_postprocessing_type –
Different approaches of the post-processing of the EOFs are available:
- "kiladis2014" for the original post-processing described in Kiladis et al. (2014).
- "eof_rotation" for the post-processing rotation algorithm described in Weidman et al. (2022);
- None for no post-processing.
eofs_postprocessing_params – dict of specific parameters, which will be passed as keyword parameters to the respective post-processing function. See the descriptions of the respective functions for details (post_process_eofs_original_kiladis_approach() or post_process_eofs_rotation()).
sign_doy1reference –

Deprecated since version 1.4.
interpolate_eofs –

Deprecated since version 1.4.
interpolation_start_doy –

Deprecated since version 1.4.
interpolation_end_doy –

Deprecated since version 1.4.
strict_leap_year_treatment –

Deprecated since version 1.4.

Returns:

The computed EOFs.

mjoindices.omi.omi_calculator.calc_eofs_from_preprocessed_olr(olrdata: OLRData, implementation: str = 'internal', leap_year_treatment: str = 'original') → EOFDataForAllDOYs[source]¶

Calculates a series of EOF pairs: one pair for each DOY.

This is based on already preprocessed OLR. Note that it is recommended to use the function calc_eofs_from_olr() to cover the complete algorithm.

Parameters:

olrdata – the preprocessed OLR data, from which the EOFs are calculated.
implementation – see calc_eofs_from_olr().
leap_year_treatment – see calc_eofs_from_olr().

Returns:

A pair of EOFs for each DOY. This series of EOFs has probably still to be postprocessed.

mjoindices.omi.omi_calculator.calculate_pcs_from_olr(olrdata: OLRData, eofdata: EOFDataForAllDOYs, period_start: datetime64, period_end: datetime64, use_quick_temporal_filter=False) → PCData[source]¶

This major function computes PCs according to the OMI algorithm based on given OLR data and previously calculated EOFs.

Parameters:

olrdata – The OLR dataset. The spatial grid must fit to that of the EOFs.
eofdata – The previously calculated DOY-dependent EOFs.
period_start – the beginning of the period, for which the PCs should be calculated.
period_end – the ending of the period, for which the PCs should be calculated.
use_quick_temporal_filter –
There are two implementations of the temporal filtering available (the results of both methods are quite similar):
- False: the original Wheeler-Kiladis-Filter, which is closer to the original implementation while being slower (because it is based on a 2-dim FFT).
- True: 1-dim FFT Filter, which results in a quicker computation.

Returns:

The PC time series. Normalized by the full PC time series

mjoindices.omi.omi_calculator.calculate_pcs_from_olr_original_conditions(olrdata: OLRData, original_eof_dirname: Path, use_quick_temporal_filter=False) → PCData[source]¶

Convenience function that calculates the OMI PCs for the original period using the original dataset (which has, however, to be provided by the user).

Parameters:

olrdata – The original OLR data, which can be downloaded from https://www.psl.noaa.gov/thredds/catalog/Datasets/interp_OLR/catalog.html?dataset=Datasets/interp_OLR/olr.day.mean.nc. It can be read with the function mjoindices.olr_handling.load_noaa_interpolated_olr_netcdf4().
original_eof_dirname – Path to the original EOFs, which can be downloaded from ftp://ftp.cdc.noaa.gov/Datasets.other/MJO/eof1/ and ftp://ftp.cdc.noaa.gov/Datasets.other/MJO/eof2/ . The contents of both remote directories should again be placed into sub directories eof1 and eof2
use_quick_temporal_filter – See calculate_pcs_from_olr()

Returns:

The PCs, which should be similar to the original ones.

mjoindices.omi.omi_calculator.initiate_eof_post_processing(raw_eofs: EOFDataForAllDOYs, eofs_postprocessing_type: str = 'kiladis2014', eofs_postprocessing_params: Optional[dict] = None) → EOFDataForAllDOYs[source]¶

Helper function that starts the selected post-processing routine and applies default post-processing parameters if none are given.

Parameters:

raw_eofs – The EOFs, which have not been post-processed.
eofs_postprocessing_type – see calc_eofs_from_olr().
eofs_postprocessing_params – see calc_eofs_from_olr().

Returns:

The post-processed EOFs.

mjoindices.omi.omi_calculator.preprocess_olr(olrdata: OLRData) → OLRData[source]¶

Performs the preprocessing of an OLR dataset to make it suitable for the EOF analysis.

This is a major step of the OMI algorithm and includes the Wheeler-Kiladis-Filtering.

Note that it is recommended to use the function calc_eofs_from_olr() to cover the complete algorithm.

Parameters:: olrdata – The original OLR dataset to be preprocessed. Note that OLR values are assumed to be given in positive values.
Returns:: The filtered OLR dataset.

mjoindices.omi.omi_calculator.regress_3dim_data_onto_eofs(data: object, eofdata: EOFDataForAllDOYs) → PCData[source]¶

Finds time-dependent coefficients w.r.t the DOY-dependent EOF basis for time-dependent spatially resolved data.

I.e. it finds the PCs for temporally resolved OLR data. But the function can also be used for other datasets, as long as those datasets have the same structure as the the class mjoindices.olr_handling.OLRData.

Parameters:

data – The data used to compute the coefficients. Should be an object of class mjoindices.olr_handling.OLRData or of similar structure.
eofdata – The DOY-dependent pairs of EOFs, as computed by, e.g., calc_eofs_from_olr()

Returns:

The time-dependent PCs as mjoindices.principal_components.PCData

mjoindices.omi.omi_calculator.regress_vector_onto_eofs(vector: ndarray, eof1: ndarray, eof2: ndarray) → Tuple[float, float][source]¶

Helper method that finds the coefficients of the given vector with respect to the given basis of 2 EOFs.

The computed coefficients are the PCs in the terminology of the EOF analysis.

Parameters:

vector – The vector for which the coefficients in the EOF basis should be found.
eof1 – EOF basis vector 1.
eof2 – EOF basis vector 2.

Returns:

The two PCs.