xeofs 1.1.0

Collection of EOF analysis and related techniques for climate science

Versions
Build & Testing
Code Quality
Documentation
Citation & Licensing
User Engagement

Overview

xeofs is a Python toolbox designed for methods like Empirical Orthogonal Function (EOF) analysis, also known as Principal Component Analysis (PCA), and related variants. The package stands out due to its capacity to handle multi-dimensional Earth observation data.

Here are the key strengths of xeofs:

• Multi-dimensional Analysis: Execute labeled EOF analysis with the extensive features of xarray.

• Scalability: Handle large datasets effectively with dask.

• Speed: Enjoy quick EOF analysis using scipy’s randomized SVD.

• Variety of Methods: Perform diverse variants of EOF analysis, including complex and rotated EOF analysis, along with related techniques such as Maximum Covariance Analysis (MCA).

• Model Validation: Validate models through bootstrapping.

• Modular Code Structure: Incorporate new EOF variants with ease due to the package’s modular structure.

• Flexible Data Formats: Accepts a variety of xarray input types (DataArray, Dataset, list of DataArray).

Compared to similar packages like eofs, pyEOF, and xMCA, xeofs is more comprehensive and flexible, providing unique capabilities like handling fully multidimensional dimensions (both samples and features) and a simple interface for bootstrapping. This makes xeofs a powerful one-stop-shop for most of your EOF analysis needs.

Installation

To install the package, use either of the following commands:

conda install -c conda-forge xeofs

or

pip install xeofs

Quickstart

In order to get started with xeofs, follow these simple steps:

Import the package

import xeofs as xe

EOF analysis

model = xe.models.EOF(n_modes=10)
model.fit(data, dim="time")
comps = model.components()  # EOFs (spatial patterns)
scores = model.scores()  # PCs (temporal patterns)

Varimax-rotated EOF analysis

rotator = xe.models.EOFRotator(n_modes=10)
rotator.fit(model)
rot_comps = rotator.components()  # Rotated EOFs (spatial patterns)
rot_scores = rotator.scores()  # Rotated PCs (temporal patterns)

MCA

model = xe.models.MCA(n_modes=10)
model.fit(data1, data2, dim="time")
comps1, comps2 = model.components()  # Singular vectors (spatial patterns)
scores1, scores2 = model.scores()  # Expansion coefficients (temporal patterns)

Varimax-rotated MCA

rotator = xe.models.MCARotator(n_modes=10)
rotator.fit(model)
rot_comps = rotator.components()  # Rotated singular vectors (spatial patterns)
rot_scores = rotator.scores()  # Rotated expansion coefficients (temporal patterns)

To further explore the capabilities of xeofs, check the available documentation and examples. For a full list of currently available methods, see the methods section.

Documentation

For a more comprehensive overview and usage examples, visit the documentation.

Contributing

Contributions are highly welcomed and appreciated. If you’re interested in improving xeofs or fixing issues, please open a Github issue.

License

This project is licensed under the terms of the MIT license.

Contact

For questions or support, please open a Github issue.

Credits

I want to acknowledge

• Andrew Dawson, for his foundational Python package for EOF analysis.

• Yefee, whose work provided useful references for implementing MCA in xeofs.

• James Chapman, creator of a Python package for Canonical Correlation Analysis.

• Diego Bueso, for his open-source ROCK-PCA implementation in Matlab.

• The developers of NumPy, pandas, and xarray for their indispensable tools for scientific computations in Python.

How to cite?

When utilizing xeofs, kindly remember to cite the original creators of the methods employed in your work. Additionally, if xeofs is proving useful in your research, I’d appreciate if you could acknowledge its use with the following citation:

@software{rieger_xeofs_2023,
  title = {xeofs: Multi-dimensional {EOF} analysis and variants in xarray},
  url = {https://github.com/nicrie/xeofs}
  version = {1.x.y},
  author = {Rieger, Niclas},
  date = {2023},
  doi = {10.5281/zenodo.6323011}
}