chore: Release v1.2.0

.gitignore

@@ -1,5 +1,7 @@
 # Personal
 .vscode/
+# Test related to CCA
+tests/models/test_cca_solution.py
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

docs/_autosummary/xeofs.models.ComplexEOF.rst

@@ -24,6 +24,7 @@
       ~ComplexEOF.explained_variance
       ~ComplexEOF.explained_variance_ratio
       ~ComplexEOF.fit
+      ~ComplexEOF.fit_transform
       ~ComplexEOF.get_params
       ~ComplexEOF.inverse_transform
       ~ComplexEOF.scores

docs/_autosummary/xeofs.models.ComplexEOFRotator.rst

@@ -24,6 +24,7 @@
       ~ComplexEOFRotator.explained_variance
       ~ComplexEOFRotator.explained_variance_ratio
       ~ComplexEOFRotator.fit
+      ~ComplexEOFRotator.fit_transform
       ~ComplexEOFRotator.get_params
       ~ComplexEOFRotator.inverse_transform
       ~ComplexEOFRotator.scores

docs/_autosummary/xeofs.models.ComplexMCA.rst

@@ -33,6 +33,7 @@
       ~ComplexMCA.singular_values
       ~ComplexMCA.squared_covariance
       ~ComplexMCA.squared_covariance_fraction
+      ~ComplexMCA.total_covariance
       ~ComplexMCA.transform
 
 

docs/_autosummary/xeofs.models.ComplexMCARotator.rst

@@ -33,6 +33,7 @@
       ~ComplexMCARotator.singular_values
       ~ComplexMCARotator.squared_covariance
       ~ComplexMCARotator.squared_covariance_fraction
+      ~ComplexMCARotator.total_covariance
       ~ComplexMCARotator.transform
 
 

docs/_autosummary/xeofs.models.EOF.rst

@@ -22,6 +22,7 @@
       ~EOF.explained_variance
       ~EOF.explained_variance_ratio
       ~EOF.fit
+      ~EOF.fit_transform
       ~EOF.get_params
       ~EOF.inverse_transform
       ~EOF.scores

docs/_autosummary/xeofs.models.EOFRotator.rst

@@ -22,6 +22,7 @@
       ~EOFRotator.explained_variance
       ~EOFRotator.explained_variance_ratio
       ~EOFRotator.fit
+      ~EOFRotator.fit_transform
       ~EOFRotator.get_params
       ~EOFRotator.inverse_transform
       ~EOFRotator.scores

docs/_autosummary/xeofs.models.MCA.rst

@@ -29,6 +29,7 @@
       ~MCA.singular_values
       ~MCA.squared_covariance
       ~MCA.squared_covariance_fraction
+      ~MCA.total_covariance
       ~MCA.transform
 
 

docs/_autosummary/xeofs.models.MCARotator.rst

@@ -29,6 +29,7 @@
       ~MCARotator.singular_values
       ~MCARotator.squared_covariance
       ~MCARotator.squared_covariance_fraction
+      ~MCARotator.total_covariance
       ~MCARotator.transform
 
 

docs/_autosummary/xeofs.models.OPA.rst

@@ -22,6 +22,7 @@
       ~OPA.decorrelation_time
       ~OPA.filter_patterns
       ~OPA.fit
+      ~OPA.fit_transform
       ~OPA.get_params
       ~OPA.inverse_transform
       ~OPA.scores

docs/_autosummary/xeofs.validation.EOFBootstrapper.rst

@@ -22,6 +22,7 @@
       ~EOFBootstrapper.explained_variance
       ~EOFBootstrapper.explained_variance_ratio
       ~EOFBootstrapper.fit
+      ~EOFBootstrapper.fit_transform
       ~EOFBootstrapper.get_params
       ~EOFBootstrapper.inverse_transform
       ~EOFBootstrapper.scores

docs/auto_examples/1eof/index.rst

@@ -12,6 +12,23 @@
     <div class="sphx-glr-thumbnails">
 
 
+.. raw:: html
+
+    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates Extended EOF (EEOF) analysis on xarray tutorial  data. EEOF analysis,...">
+
+.. only:: html
+
+  .. image:: /auto_examples/1eof/images/thumb/sphx_glr_plot_eeof_thumb.png
+    :alt:
+
+  :ref:`sphx_glr_auto_examples_1eof_plot_eeof.py`
+
+.. raw:: html
+
+      <div class="sphx-glr-thumbnail-title">Extented EOF analysis</div>
+    </div>
+
+
 .. raw:: html
 
     <div class="sphx-glr-thumbcontainer" tooltip="EOF analysis in T-mode maximises the spatial variance.">
@@ -114,6 +131,23 @@
     </div>
 
 
+.. raw:: html
+
+    <div class="sphx-glr-thumbcontainer" tooltip="TIn this demonstration, we&#x27;ll apply GWPCA to a dataset detailing the chemical compositions of s...">
+
+.. only:: html
+
+  .. image:: /auto_examples/1eof/images/thumb/sphx_glr_plot_gwpca_thumb.png
+    :alt:
+
+  :ref:`sphx_glr_auto_examples_1eof_plot_gwpca.py`
+
+.. raw:: html
+
+      <div class="sphx-glr-thumbnail-title">Geographically weighted PCA</div>
+    </div>
+
+
 .. raw:: html
 
     </div>
@@ -122,10 +156,12 @@
 .. toctree::
    :hidden:
 
+   /auto_examples/1eof/plot_eeof
    /auto_examples/1eof/plot_eof-tmode
    /auto_examples/1eof/plot_eof-smode
    /auto_examples/1eof/plot_multivariate-eof
    /auto_examples/1eof/plot_mreof
    /auto_examples/1eof/plot_rotated_eof
    /auto_examples/1eof/plot_weighted-eof
+   /auto_examples/1eof/plot_gwpca
 

docs/auto_examples/1eof/plot_eeof.ipynb

@@ -0,0 +1,151 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "\n# Extented EOF analysis\n\nThis example demonstrates Extended EOF (EEOF) analysis on ``xarray`` tutorial \ndata. EEOF analysis, also termed as Multivariate/Multichannel Singular \nSpectrum Analysis, advances traditional EOF analysis to capture propagating \nsignals or oscillations in multivariate datasets. At its core, this \ninvolves the formulation of a lagged covariance matrix that encapsulates \nboth spatial and temporal correlations. Subsequently, this matrix is \ndecomposed to yield its eigenvectors (components) and eigenvalues (explained variance).\n\nLet's begin by setting up the required packages and fetching the data:\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "import xarray as xr\nimport xeofs as xe\nimport matplotlib.pyplot as plt\n\nxr.set_options(display_expand_data=False)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Load the tutorial data.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "t2m = xr.tutorial.load_dataset(\"air_temperature\").air"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Prior to conducting the EEOF analysis, it's essential to determine the\nstructure of the lagged covariance matrix. This entails defining the time\ndelay ``tau`` and the ``embedding`` dimension. The former signifies the\ninterval between the original and lagged time series, while the latter\ndictates the number of time-lagged copies in the delay-coordinate space,\nrepresenting the system's dynamics.\nFor illustration, using ``tau=4`` and ``embedding=40``, we generate 40\ndelayed versions of the time series, each offset by 4 time steps, resulting\nin a maximum shift of ``tau x embedding = 160``. Given our dataset's\n6-hour intervals, tau = 4 translates to a 24-hour shift.\nIt's obvious that this way of constructing the lagged covariance matrix\nand subsequently decomposing it can be computationally expensive. For example,\ngiven our dataset's dimensions,\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "t2m.shape"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "the extended dataset would have 40 x 25 x 53 = 53000 features\nwhich is much larger than the original dataset's 1325 features.\nTo mitigate this, we can first preprocess the data using PCA / EOF analysis\nand then perform EEOF analysis on the resulting PCA / EOF scores. Here,\nwe'll use ``n_pca_modes=50`` to retain the first 50 PCA modes, so we end\nup with 40 x 50 = 200 (latent) features.\nWith these parameters set, we proceed to instantiate the ``ExtendedEOF``\nmodel and fit our data.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "model = xe.models.ExtendedEOF(\n    n_modes=10, tau=4, embedding=40, n_pca_modes=50, use_coslat=True\n)\nmodel.fit(t2m, dim=\"time\")\nscores = model.scores()\ncomponents = model.components()\ncomponents"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "A notable distinction from standard EOF analysis is the incorporation of an\nextra ``embedding`` dimension in the components. Nonetheless, the\noverarching methodology mirrors traditional EOF practices. The results,\nfor instance, can be assessed by examining the explained variance ratio.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "model.explained_variance_ratio().plot()\nplt.show()"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Additionally, we can look into the scores; let's spotlight mode 4.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "scores.sel(mode=4).plot()\nplt.show()"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "In wrapping up, we visualize the corresponding EEOF component of mode 4.\nFor visualization purposes, we'll focus on the component at a specific\nlatitude, in this instance, 60 degrees north.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "components.sel(mode=4, lat=60).plot()\nplt.show()"
+      ]
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "codemirror_mode": {
+        "name": "ipython",
+        "version": 3
+      },
+      "file_extension": ".py",
+      "mimetype": "text/x-python",
+      "name": "python",
+      "nbconvert_exporter": "python",
+      "pygments_lexer": "ipython3",
+      "version": "3.11.4"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 0
+}

docs/auto_examples/1eof/plot_eeof.py

@@ -0,0 +1,83 @@
+"""
+Extented EOF analysis
+=====================
+
+This example demonstrates Extended EOF (EEOF) analysis on ``xarray`` tutorial 
+data. EEOF analysis, also termed as Multivariate/Multichannel Singular 
+Spectrum Analysis, advances traditional EOF analysis to capture propagating 
+signals or oscillations in multivariate datasets. At its core, this 
+involves the formulation of a lagged covariance matrix that encapsulates 
+both spatial and temporal correlations. Subsequently, this matrix is 
+decomposed to yield its eigenvectors (components) and eigenvalues (explained variance).
+
+Let's begin by setting up the required packages and fetching the data:
+"""
+
+import xarray as xr
+import xeofs as xe
+import matplotlib.pyplot as plt
+
+xr.set_options(display_expand_data=False)
+
+# %%
+# Load the tutorial data.
+t2m = xr.tutorial.load_dataset("air_temperature").air
+
+
+# %%
+# Prior to conducting the EEOF analysis, it's essential to determine the
+# structure of the lagged covariance matrix. This entails defining the time
+# delay ``tau`` and the ``embedding`` dimension. The former signifies the
+# interval between the original and lagged time series, while the latter
+# dictates the number of time-lagged copies in the delay-coordinate space,
+# representing the system's dynamics.
+# For illustration, using ``tau=4`` and ``embedding=40``, we generate 40
+# delayed versions of the time series, each offset by 4 time steps, resulting
+# in a maximum shift of ``tau x embedding = 160``. Given our dataset's
+# 6-hour intervals, tau = 4 translates to a 24-hour shift.
+# It's obvious that this way of constructing the lagged covariance matrix
+# and subsequently decomposing it can be computationally expensive. For example,
+# given our dataset's dimensions,
+
+t2m.shape
+
+# %%
+# the extended dataset would have 40 x 25 x 53 = 53000 features
+# which is much larger than the original dataset's 1325 features.
+# To mitigate this, we can first preprocess the data using PCA / EOF analysis
+# and then perform EEOF analysis on the resulting PCA / EOF scores. Here,
+# we'll use ``n_pca_modes=50`` to retain the first 50 PCA modes, so we end
+# up with 40 x 50 = 200 (latent) features.
+# With these parameters set, we proceed to instantiate the ``ExtendedEOF``
+# model and fit our data.
+
+model = xe.models.ExtendedEOF(
+    n_modes=10, tau=4, embedding=40, n_pca_modes=50, use_coslat=True
+)
+model.fit(t2m, dim="time")
+scores = model.scores()
+components = model.components()
+components
+
+# %%
+# A notable distinction from standard EOF analysis is the incorporation of an
+# extra ``embedding`` dimension in the components. Nonetheless, the
+# overarching methodology mirrors traditional EOF practices. The results,
+# for instance, can be assessed by examining the explained variance ratio.
+
+model.explained_variance_ratio().plot()
+plt.show()
+
+# %%
+# Additionally, we can look into the scores; let's spotlight mode 4.
+
+scores.sel(mode=4).plot()
+plt.show()
+
+# %%
+# In wrapping up, we visualize the corresponding EEOF component of mode 4.
+# For visualization purposes, we'll focus on the component at a specific
+# latitude, in this instance, 60 degrees north.
+
+components.sel(mode=4, lat=60).plot()
+plt.show()

docs/auto_examples/1eof/plot_eeof.py.md5

@@ -0,0 +1 @@
+7f3b66c7aec555c78dde9031213be3ad