Module mjoindices.empirical_orthogonal_functions

This module provides basic functionality to handle EOF data, which is a basic output of the OMI calculation.

class mjoindices.empirical_orthogonal_functions.EOFData(lat: ndarray, long: ndarray, eof1: ndarray, eof2: ndarray, explained_variances: Optional[ndarray] = None, eigenvalues: Optional[ndarray] = None, no_observations: Optional[int] = None)

This class serves as a container for the EOF data of one pair of EOFs.

Parameters:

• lat – The latitude grid of the EOF data.

• long – The longitude grid of the EOF data.

• eof1 – Values of the first EOF. Can either be a 1-dim vector with lat.size * long.size elements (Start with all values of the first latitude, then all values of the second latitude, etc.) or a 2-dim map with the first index representing the latitude axis and the second index representing longitude axis.

• eof2 – Values of the second EOF. Structure similar to eof1

• explained_variances – Fraction of data variance that is explained by each EOF (for all EOFs and not only the first two EOFs). Can be set to None.

• eigenvalues – Eigenvalue corresponding to each EOF. Can be set to None.

• no_observations – The number of observations that went into the EOF calculation. Can be set to None.

Note that the explained variances are not independent of the eigenvalues. However, this class is meant only to store the data. Hence, we store redundant data here intentionally to be able to have all computation performed together in another location.

close(other: EOFData) → bool

Checks equality of two EOFData 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()

property eigenvalue_eof1: float

The eigenvalue of EOF1.

Returns:

The eigenvalue. Might be None.

property eigenvalue_eof2: float

The eigenvalue of EOF2.

Returns:

The eigenvalue. Might be None.

property eigenvalues: ndarray

The eigenvalues of all EOFs (not only the first two ones).

Returns:

The eigenvalues. Might be None.

property eof1map: ndarray

EOF1 as a 2-dimensional map.

property eof1vector: ndarray

EOF1 as a vector (and not a matrix).

property eof2map: ndarray

EOF2 as a 2-dimensional map.

property eof2vector: ndarray

EOF2 as a vector (and not a matrix).

property explained_variance_eof1: float

The explained variance of EOF1 as fraction between 0 and 1.

Returns:

The variance. Might be None.

property explained_variance_eof2: float

The explained variance of EOF2 as fraction between 0 and 1.

Returns:

The variance. Might be None.

property explained_variances: ndarray

The explained variances of all EOFs (not only the first two ones).

Returns:

Explained Variances. Might be None.

property lat: ndarray

The latitude grid of the EOFs.

property long: ndarray

The longitude grid of the EOFs.

property no_observations: int

The number of observations that went into the calculation of the EOFs.

reshape_to_map(vector: ndarray) → ndarray

Reshapes data in a vector to fit into a matrix, which corresponds to the present latitude/longitude grid.

Parameters:

vector – The vector with the data. Must have the length lat.size * long.size.

Returns:

The map. The first index corresponds to the latitude grid, the second to longitude grid.

reshape_to_vector(map: ndarray) → ndarray

Reshapes the horizontally distributed data to fit into a vector.

The vector elements will contain the values of all longitudes for the first latitude, and then the values of all longitudes for the second latitude, etc.

Parameters:

map – The 2-dim data. The first dimension must correspond to the latitude grid, the second to the longitude grid.

Returns:

The data as a vector.

save_eofs_to_txt_file(filename: Path) → None

Saves both EOFs to a .txt file.

Note that the file format is not exactly that of the original data files. Particularly, both EOFs are written into the same file instead of 2 separate files. Furthermore, the lat/long-grids are also explicitly saved.

A suitable reader is provided by the function load_single_eofs_from_txt_file(), whereas a reader for the original files is provided by load_original_eofs_for_doy()

Parameters:

filename – The full path- and filename.

property sum_of_explained_variances: float

Returns the total variance explained by all EOFs.

This should be close to 1 if the calculation was successful.

Returns:

The total explained variance. Might be None.

class mjoindices.empirical_orthogonal_functions.EOFDataForAllDOYs(eof_list: List[EOFData], no_leap_years: bool)

This class serves as a container for a series of EOF pairs, which covers all DOYs and provides some overall statistical quantities.

The basic EOF computation function mjoindices.omi.omi_calculator.calc_eofs_from_olr() will return an object of this class as a major result of this package.

The individual EOF pairs are represented by EOFData objects.

Note that the user can choose to consider or to ignore leap years in the data. This is probably of interest for the work with modeled data, since models might ignore leap years in idealized setups. Here, this means that the number of considered DOYs (and therefore the number of EOF pairs and further variables) can be either 365 or 366. The code in this package is designed to treat both cases consistently, however, the users should have their own choice in mind when working with the results.

Parameters:

• eof_list – A list with one EOFData object for each DOY.

• no_leap_years – True if every year has 365 days, False if dataset contains leap years.

eigenvalue1_for_all_doys()

Returns a vector containing the eigenvalues of EOF1 for each DOY.

Returns:

The eigenvalue vector.

eigenvalue2_for_all_doys()

Returns a vector containing the eigenvalues of EOF2 for each DOY.

Returns:

The eigenvalue vector.

eof1vector_for_doy(doy: int) → ndarray

Shortcut to the EOF1 vector of a particular DOY.

Parameters:

doy – The DOY.

Returns:

The vector.

eof2vector_for_doy(doy: int) → ndarray

Shortcut to the EOF2 vector of a particular DOY.

Parameters:

doy – The DOY.

Returns:

The vector.

property eof_list: List[EOFData]

EOF data for all DOYs as a list.

Remember that DOY 1 corresponds to list entry 0.

eofdata_for_doy(doy: int) → EOFData

Returns the EOFData object for a particular DOY.

Parameters:

doy – The DOY

Returns:

The EOFData object

explained_variance1_for_all_doys()

Returns a vector containing the explained variance of EOF1 for each DOY.

Returns:

The variance vector.

explained_variance2_for_all_doys()

Returns a vector containing the explained variance of EOF2 for each DOY.

Returns:

The variance vector.

property lat: ndarray

The latitude grid common to the EOFs of all DOYs.

property len_eof_list: int

Length of the eof_list, based on no_leap_years, i.e. the number of considered DOYs.

property long: ndarray

The longitude grid common to the EOFs of all DOYs.

property no_leap_years: bool

True if every year has 365 days, False if dataset contains leap years.

no_observations_for_all_doys()

Returns a vector containing -for each DOY- the number of observations that went into the computation of the EOFs.

Returns:

The number of observations vector.

save_all_eofs_to_dir(dirname: Path, create_dir=True) → None

Saves the EOF1 and EOF2 data for each of the DOYs in the given directory.

For each DOY, one text file will be created, which contains both EOFs. Note that the text files do not contain the eigenvalues and explained variance values. To save also those values, use the function save_all_eofs_to_npzfile().

Parameters:

• dirname – The directory, where the files will be saved into.

• create_dir – If True, the directory (and parent directories) will be created, if not existing.

save_all_eofs_to_npzfile(filename: Path) → None

Saves the complete EOF data to a numpy file.

Parameters:

filename – The filename.

total_explained_variance_for_all_doys()

Returns a vector containing -for each DOY- the sum of the explained variance over all EOFs.

Returns:

The variance vector. Should by close to 1 for each DOY if computation was successful.

mjoindices.empirical_orthogonal_functions.load_all_eofs_from_directory(dirname: Path) → EOFDataForAllDOYs

Loads the EOF functions (created with the function EOFDataForAllDOYs.save_all_eofs_to_dir()) for all DOYs from the given directory

Parameters:

dirname – The directory in which the files are stored.

Returns:

The EOFs for all DOYs.

mjoindices.empirical_orthogonal_functions.load_all_original_eofs_from_directory(dirname: Path) → EOFDataForAllDOYs

Loads the EOF functions for all DOYs from the original file format.

The original EOFs are found here: ftp://ftp.cdc.noaa.gov/Datasets.other/MJO/eof1/ and ftp://ftp.cdc.noaa.gov/Datasets.other/MJO/eof2/

Note that the EOFs are represented as pure vectors in the original treatment, so that a connection to the individual locations on a world map is not obvious without any further knowledge. The corresponding grid is hardcoded in here.

Parameters:

dirname – Path to the directory, in which the EOFs for all DOYs are stored. This path should contain the sub directories “eof1” and “eof2”, in which the 366 files each are located: One file per day of the year.

Returns:

The original EOFs for all DOYs.

mjoindices.empirical_orthogonal_functions.load_original_eofs_for_doy(dirname: Path, doy: int) → EOFData

Loads the EOF values for the first 2 EOFs from the original file format.

Note that the EOFs are represented as pure vectors in the original treatment, so that a connection to the individual locations on a world map is not obvious without any further knowledge. The corresponding grid is hardcoded in here.

The original EOFs are found here: ftp://ftp.cdc.noaa.gov/Datasets.other/MJO/eof1/ and ftp://ftp.cdc.noaa.gov/Datasets.other/MJO/eof2/

Parameters:

• dirname – Path to the directory, in which the EOFs for all DOYs are stored. This path should contain the sub directories “eof1” and “eof2”, in which the 365 or 366 files each are located: One file per DOY.

• doy – DOY for which the 2 EOFs are loaded (number between 1 and 366).

Returns:

The pair of EOFs.

mjoindices.empirical_orthogonal_functions.load_single_eofs_from_txt_file(filename: Path) → EOFData

Loads a pair of EOFs, which was previously saved with this package (function EOFData.save_eofs_to_txt_file()).

Parameters:

filename – Path to the EOF file.

Returns:

The pair of EOFs.

mjoindices.empirical_orthogonal_functions.plot_eigenvalues_for_all_doys(eofs: EOFDataForAllDOYs) → Figure

Plots the Eigenvalues for EOF1 and EOF2 for all DOYs.

Parameters:

eofs – The EOF data to plot.

Returns:

Handle to the figure.

mjoindices.empirical_orthogonal_functions.plot_explained_variance_for_all_doys(eofs: EOFDataForAllDOYs, include_total_variance: bool = False, include_no_observations: bool = False) → Figure

Plots the explained variance values for EOF1 and EOF2 for all DOYs.

Comparable to Kiladis et al. (2014), Fig. 1 (although the values there are too high by a factor of 2). See Kiladis et al. (2020) for the correct original values.

Parameters:

eofs – The EOF data to plot.

Returns:

Handle to the figure.

mjoindices.empirical_orthogonal_functions.plot_individual_eof_map(eofdata: EOFData, doy: Optional[int] = None) → Figure

Plots a pair of EOFs for a particular DOY in two maps.

Parameters:

• eofdata – The EOF data to plot.

• doy – The corresponding DOY. Only used to display it in the title.

Returns:

Handle to the figure.

mjoindices.empirical_orthogonal_functions.plot_individual_eof_map_from_file(filename, doy: int) → Figure

Plots a pair of EOFs, which are loaded from a file, in two maps.

Parameters:

• filename – The file with the EOF data.

• doy – The corresponding DOY. Only used to display it in the title.

Returns:

Handle to the figure.

mjoindices.empirical_orthogonal_functions.plot_individual_explained_variance_all_eofs(eof: EOFData, doy: Optional[int] = None, max_eof_number: Optional[int] = None) → Figure

Plots the explained variances for each EOF function, but only for EOF data of one DOY.

This is useful to confirm that the first 2 EOFs cover actually most of the variance.

Parameters:

• eof – The EOF data.

• doy – The corresponding DOY. Only used to display it in the title.

• max_eof_number – The limit of the x-axis.

Returns:

Handle to the figure.

mjoindices.empirical_orthogonal_functions.plot_original_individual_eof_map(path, doy: int) → Figure

Plots a pair of original EOFs, which are loaded from a directory, in two maps.

Parameters:

• path – The directory with the EOF data (see load_original_eofs_for_doy() for details).

• doy – The corresponding DOY. Only used to display it in the title.

Returns:

Handle to the figure.

mjoindices.empirical_orthogonal_functions.restore_all_eofs_from_npzfile(filename: Path) → EOFDataForAllDOYs

Loads all EOF data from a numpy file, which was written with EOFDataForAllDOYs.save_all_eofs_to_npzfile().

Parameters:

filename – The filename.

Returns:

The EOFs for all DOYs.