Migrating to v3#

This short guide outlines the key changes in version 3 of xeofs and provides instructions for updating your code from version 2.

Updated Namespaces for Models#

To improve organization and future scalability, new namespaces have been introduced for the models. This is a breaking change, but updating your code is straightforward. You’ll need to adjust the import statements and method access in your v2 code. The new namespaces are as follows:

  • xeofs.single: Contains all single-field models (e.g. EOF analysis)

  • xeofs.cross: Contains all cross-field models (e.g. MCA)

  • xeofs.multi: Contains all multi-field models

Previously, methods were accessed like this:

eof = xe.models.EOF()

In v3, they are now accessed as follows:

eof = xe.single.EOF()
mca = xe.cross.MCA()

Complex/Hilbert Classes Reanming#

In v2, Hilbert methods were mistakenly named as Complex methods. This has been corrected in v3. If you were using Complex methods in v2, you should now use Hilbert methods in v3.

# v2
ceof = xe.models.ComplexEOF()

# v3
ceof = xe.single.HilbertEOF()

Complex methods still exist but now follow the standard convention of analyzing pre-existing complex fields (e.g., wind field components u and v). Hilbert methods, on the other hand, are used for analyzing real physical fields, where the Hilbert transform is applied to convert the real field into a complex field.

Normalization of score() Methods#

To align with the scikit-learn API, the default value for the normalize parameter in the score() methods has been changed from True to False. In EOF analysis, this means that the raw principal components (PCs) will now be returned, with each PC weighted by its respective mode’s importance (singular value). If you prefer the previous behavior, you can explicitly set normalize=True.

The components() method remains unchanged, with normalization still set to True by default.

Dropped Parameters#

Several parameters have been removed in v3:

  • verbose: This parameter has been removed from all methods, as it was deemed unnecessary

  • squared_loadings (specific to MCARotator classes): This parameter has been removed because, although it preserved the squared covariance fraction after rotation, it invalidated the inverse_transform method for reconstructing the original fields. Its removal helps avoid confusion and misuse.

Standardize Variable Names#

In v3, variable names have been standardized to X and Y for input data. In v2, input data was often referred to as data, data1, or data2. This change improves code readability and aligns with the scikit-learn API for consistency.