xeofs

A dedicated Python package for dimensionality reduction in the realm of climate science, offering methods like PCA, known as EOF analysis within the field, and related variants.
https://github.com/xarray-contrib/xeofs

Category: Climate Change
Sub Category: Climate Data Processing and Analysis

Keywords

climate-science dask dimensionality-reduction eof-analysis pattern-recognition pca xarray

Keywords from Contributors

virtualization geocode good-first-issue feature-engine annotations routing actions parallel batteries profiles

Last synced: about 11 hours ago
JSON representation

Repository metadata

Comprehensive EOF analysis in Python with xarray: A versatile, multidimensional, and scalable tool for advanced climate data analysis

Host: GitHub
URL: https://github.com/xarray-contrib/xeofs
Owner: xarray-contrib
License: mit
Created: 2022-02-12T00:22:58.000Z (about 3 years ago)
Default Branch: main
Last Pushed: 2025-01-28T08:38:48.000Z (3 months ago)
Last Synced: 2025-04-21T19:08:54.440Z (6 days ago)
Topics: climate-science, dask, dimensionality-reduction, eof-analysis, pattern-recognition, pca, xarray
Language: Python
Homepage: https://xeofs.readthedocs.io/
Size: 44.8 MB
Stars: 115
Watchers: 6
Forks: 23
Open Issues: 17
Releases: 45
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Citation: CITATION.cff

README.md

xeofs logo

Versions
Build & Testing
Code Quality
Documentation
Citation
Licensing
User Engagement

Overview

xeofs is a specialized Python package designed for dimensionality reduction in climate science, aimed at extracting meaningful patterns from large datasets. It provides eigenmethods such as Principal Component Analysis (EOF analysis) and several related variants. Seamlessly integrated with xarray and Dask, xeofs enables efficient handling and scalable computation of large, multi-dimensional datasets.

Multi-Dimensional: Designed for xarray objects, it applies dimensionality reduction to multi-dimensional data while maintaining data labels.
Dask-Integrated: Supports large datasets via Dask xarray objects
Extensive Methods: Offers various dimensionality reduction techniques
Adaptable Output: Provides output corresponding to the type of input, whether single or list of xr.DataArray or xr.Dataset
Missing Values: Handles NaN values within the data
Bootstrapping: Comes with a user-friendly interface for model evaluation using bootstrapping
Efficient: Ensures computational efficiency, particularly with large datasets through randomized SVD
Modular: Allows users to implement and incorporate new dimensionality reduction methods

Installation

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

conda install -c conda-forge xeofs

pip install xeofs

Quickstart

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

Import the package

>>> import xarray as xr  # for example data only
>>> import xeofs as xe

Load example data

>>> t2m = xr.tutorial.open_dataset("air_temperature")
>>> t2m_west = t2m.isel(lon=slice(None, 20))
>>> t2m_east = t2m.isel(lon=slice(21, None))

EOF analysis
Initiate and fit the EOF/PCA model to the data

>>> eof = xe.single.EOF(n_modes=10)
>>> eof.fit(t2m, dim="time")  # doctest: +ELLIPSIS
<xeofs.single.eof.EOF object at ...>

Now, you can access the model's EOF components and PC scores:

>>> comps = eof.components()  # EOFs (spatial patterns)
>>> scores = eof.scores()  # PCs (temporal patterns)

Varimax-rotated EOF analysis
Initiate and fit an EOFRotator class to the model to obtain a varimax-rotated EOF analysis

>>> rotator = xe.single.EOFRotator(n_modes=3)
>>> rotator.fit(eof) # doctest: +ELLIPSIS
<xeofs.single.eof_rotator.EOFRotator object at ...>

>>> rot_comps = rotator.components()  # Rotated EOFs (spatial patterns)
>>> rot_scores = rotator.scores()  # Rotated PCs (temporal patterns)

Maximum Covariance Analysis (MCA)

>>> mca = xe.cross.MCA(n_modes=10)
>>> mca.fit(t2m_west, t2m_east, dim="time")  # doctest: +ELLIPSIS
<xeofs.cross.mca.MCA object at ...>

>>> comps1, comps2 = mca.components()  # Singular vectors (spatial patterns)
>>> scores1, scores2 = mca.scores()  # Expansion coefficients (temporal patterns)

Varimax-rotated MCA

>>> rotator = xe.cross.MCARotator(n_modes=10)
>>> rotator.fit(mca)  # doctest: +ELLIPSIS
<xeofs.cross.mca_rotator.MCARotator object at ...>

>>> 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 out the available documentation and examples.
For a full list of currently available methods, see the Reference API.

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 read our Contributing Guide.

License

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

Contact

For questions or support, please open a Github issue.

Credits

Randomized PCA: scikit-learn
EOF analysis: Python package eofs by Andrew Dawson
MCA: Python package xMCA by Yefee
CCA: Python package CCA-Zoo by James Chapman
ROCK-PCA: Matlab implementation by Diego Bueso
Sparse PCA: Based on Ristretto library by Benjamin Erichson

How to cite?

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

@article{rieger_xeofs_2024,
author = {Rieger, Niclas and Levang, Samuel J.},
doi = {10.21105/joss.06060},
journal = {Journal of Open Source Software},
month = jan,
number = {93},
pages = {6060},
title = {{xeofs: Comprehensive EOF analysis in Python with xarray}},
url = {https://joss.theoj.org/papers/10.21105/joss.06060},
volume = {9},
year = {2024}
}

Contributors

Citation (CITATION.cff)

cff-version: 1.2.0
message: "If you use this software, please cite it as below."
authors:
- family-names: "Rieger"
  given-names: "Niclas"
  orcid: "https://orcid.org/0000-0003-3357-1742"
- family-names: "Levang"
  given-names: "Samuel J."
title: "xeofs"
abstract: "Comprehensive EOF analysis in Python with xarray."
license: MIT
doi: 10.5281/zenodo.6323011
url: "https://xeofs.readthedocs.io/en/latest/"
repository-code: "https://github.com/xarray-contrib/xeofs"
preferred-citation:
  authors:
  - family-names: "Rieger"
    given-names: "Niclas"
    orcid: "https://orcid.org/0000-0003-3357-1742"
  - family-names: "Levang"
    given-names: "Samuel J."
  date-published: "2024-01-02"
  doi: 10.21105/joss.06060
  issn: 2475-9066
  issue: 93
  journal: "Journal of Open Source Software"
  publisher: 
    name: "Open Journals"
  start: 6060
  title: "xeofs: Comprehensive EOF analysis in Python with xarray"
  type: article
  url: "https://joss.theoj.org/papers/10.21105/joss.06060"
  volume: 9

Owner metadata

Name: xarray-contrib
Login: xarray-contrib
Email:
Kind: organization
Description: xarray compatible projects
Website: https://xarray.dev
Location:
Twitter: xarray_dev
Company:
Icon url: https://avatars.githubusercontent.com/u/35757293?v=4
Repositories: 23
Last ynced at: 2023-03-04T02:29:00.282Z
Profile URL: https://github.com/xarray-contrib

GitHub Events

Total

Issues event: 14
Watch event: 14
Delete event: 2
Issue comment event: 19
Push event: 5
Pull request event: 3
Pull request review event: 1
Pull request review comment event: 1
Fork event: 2
Create event: 2

Last Year

Issues event: 14
Watch event: 14
Delete event: 2
Issue comment event: 19
Push event: 5
Pull request event: 3
Pull request review event: 1
Pull request review comment event: 1
Fork event: 2
Create event: 2

Committers metadata

Last synced: 6 days ago

Total Commits: 560
Total Committers: 10
Avg Commits per committer: 56.0
Development Distribution Score (DDS): 0.152

Commits in past year: 70
Committers in past year: 5
Avg Commits per committer in past year: 14.0
Development Distribution Score (DDS) in past year: 0.343

Name	Email	Commits
Niclas Rieger	n**r@g**m	475
github-actions	g**s@g**m	30
Sam Levang	3****g	24
github-actions[bot]	g****]	11
github-actions	a**n@g**m	8
semantic-release	s****e	8
arfriedman	a**d@g**m	1
Mattia Almansi	m**i@b**u	1
Damien Irving	i**n@g**m	1
Aaron Spring	a****g	1

Committer domains:

github.com: 2
bopen.eu: 1

Issue and Pull Request metadata

Last synced: 1 day ago

Total issues: 118
Total pull requests: 150
Average time to close issues: 24 days
Average time to close pull requests: 1 day
Total issue authors: 31
Total pull request authors: 5
Average comments per issue: 2.33
Average comments per pull request: 0.91
Merged pull request: 146
Bot issues: 0
Bot pull requests: 0

Past year issues: 39
Past year pull requests: 57
Past year average time to close issues: 12 days
Past year average time to close pull requests: about 10 hours
Past year issue authors: 14
Past year pull request authors: 3
Past year average comments per issue: 1.95
Past year average comments per pull request: 0.4
Past year merged pull request: 57
Past year bot issues: 0
Past year bot pull requests: 0

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/xarray-contrib/xeofs

Top Issue Authors

nicrie (59)
gkb999 (5)
slevang (5)
arfriedman (4)
mschulzie (4)
SHEN-Cheng (3)
liuchao95 (3)
semvijverberg (2)
shenyulu (2)
agirnow (2)
donehii (2)
juntyr (2)
navidcy (2)
malmans2 (2)
NILICK (2)

Top Pull Request Authors

nicrie (124)
slevang (23)
malmans2 (1)
arfriedman (1)
DamienIrving (1)

Top Issue Labels

bug (31)
documentation (16)
new feature (14)
design (12)
enhancement (3)
usage (2)

Top Pull Request Labels

Package metadata

Total packages: 1
Total downloads:
- pypi: 2,026 last-month
Total dependent packages: 2
Total dependent repositories: 2
Total versions: 38
Total maintainers: 1

pypi.org: xeofs

Comprehensive EOF analysis in Python with xarray: A versatile, multidimensional, and scalable tool for advanced climate data analysis

Homepage:
Documentation: https://xeofs.readthedocs.io/
Licenses: MIT
Latest release: 3.0.4 (published 6 months ago)
Last Synced: 2025-01-13T17:48:28.523Z (3 months ago)
Versions: 38
Dependent Packages: 2
Dependent Repositories: 2
Downloads: 2,026 Last month
Rankings:
- Dependent packages count: 7.31%
- Downloads: 8.24%
- Stargazers count: 8.867%
- Average: 9.536%
- Forks count: 11.463%
- Dependent repos count: 11.798%
Maintainers (1)
- nrieger

Dependencies

poetry.lock pypi

atomicwrites 1.4.0 develop
attrs 21.4.0 develop
cftime 1.5.2 develop
coverage 6.3.1 develop
flake8 4.0.1 develop
iniconfig 1.1.1 develop
mccabe 0.6.1 develop
netcdf4 1.5.8 develop
pluggy 1.0.0 develop
py 1.11.0 develop
pycodestyle 2.8.0 develop
pyflakes 2.4.0 develop
pytest 7.0.1 develop
tomli 2.0.1 develop
appdirs 1.4.4
certifi 2021.10.8
charset-normalizer 2.0.12
colorama 0.4.4
idna 3.3
joblib 1.1.0
numpy 1.22.2
packaging 21.3
pandas 1.4.1
pooch 1.6.0
pyparsing 3.0.7
python-dateutil 2.8.2
pytz 2021.3
requests 2.27.1
scikit-learn 1.0.2
scipy 1.6.1
six 1.16.0
threadpoolctl 3.1.0
tqdm 4.64.0
urllib3 1.26.8
xarray 0.21.1

pyproject.toml pypi

coverage ^6.3.1 develop
flake8 ^4.0.1 develop
netCDF4 ^1.5.7 develop
pytest ^7.0.1 develop
numpy ^1.19.2
pandas ^1.4.1
pooch ^1.6.0
python ^3.8
scikit-learn ^1.0.2
tqdm ^4.64.0
xarray ^0.21.1

.github/workflows/black_formatting.yml actions

actions/checkout v3 composite
psf/black stable composite

.github/workflows/changelog.yml actions

BobAnkh/auto-generate-changelog v1.2.5 composite
actions/checkout v2 composite

.github/workflows/ci.yml actions

abatilo/actions-poetry v2.1.0 composite
actions/checkout v3 composite
actions/setup-python v3 composite
codecov/codecov-action v3 composite

.github/workflows/pull-request-linting.yml actions

amannn/action-semantic-pull-request v5 composite

.github/workflows/release_package.yml actions

actions/checkout v3 composite
pypa/gh-action-pypi-publish release/v1 composite
python-semantic-release/python-semantic-release master composite
python-semantic-release/upload-to-gh-release main composite

docs/environment.yml pypi

xeofs *

Score: 14.801670577160802

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Open Sustainable Technology