Merge pull request #25 from nicrie/develop

Develop

README.rst

@@ -3,7 +3,7 @@
   :width: 800
   :alt: Comparison of standard, Varimax-rotated and Proxmax-rotated EOF analysis for temperature field over North America.
 
-Example_ showing North American surface temperature decomposed via EOF analysis, Varimax rotation and Promax rotation.
+Example_ showing sea surface temperature decomposed via EOF analysis, Varimax rotation and Promax rotation.
 
 .. _Example: https://xeofs.readthedocs.io/en/stable/auto_examples/1eof/plot_rotated_eof.html#sphx-glr-auto-examples-1eof-plot-rotated-eof-py
 
@@ -60,13 +60,16 @@ Package                 **xeofs**   eofs_       pyEOF_      xeof_       xMCA_
 EOF analysis           ✅           ✅           ✅           ✅           ✅            ✅
 Rotated EOF analysis   ✅           ❌           ✅           ❌           ❌            ✅
 Complex EOF analysis   ❌           ❌           ❌           ❌           ❌            ✅
+`ROCK-PCA`_            ✅           ❌           ❌           ❌           ❌            ❌
 Multivariate EOF       ✅           ✅           ❌           ❌           ❌            ❌
 MCA                    ✅           ❌           ❌           ❌           ✅            ✅
-Rotated MCA            ❌           ❌           ❌           ❌           ❌            ✅
+Rotated MCA            ✅           ❌           ❌           ❌           ❌            ✅
 Complex MCA            ❌           ❌           ❌           ❌           ❌            ✅
 Multivariate MCA       ✅           ❌           ❌           ❌           ❌            ❌
 =====================  ==========  ==========  ==========  ==========  ==========  ==========
 
+.. _ROCK-PCA: https://ieeexplore.ieee.org/stamp/stamp.jsp?arnumber=8989964&casa_token=3zKG0dtp-ewAAAAA:FM1CrVISSSqhWEAwPGpQqCgDYccfLG4N-67xNNDzUBQmMvtIOHuC7T6X-TVQgbDg3aDOpKBksg&tag=1
+
 
 Additional features
 ----------------------
@@ -148,13 +151,34 @@ Documentation_ is work in progress. Meanwhile check out some examples_ to get st
 Credits
 ----------------------
 
-- Project folder structure: yngvem_
-- Testing data: xarray_ \& pooch_
-- All developers of the EOF packages mentioned above
+- to Andrew Dawson_ for the first and fundamental Python package for EOF analysis
+- to Yefee_ from which I took some inspiration to implement MCA
+- to James Chapman_ who created a great Python package for Canonical Correlation Analysis
+- to Diego Bueso_ for his open-source ROCK-PCA implementation in Matlab
+- to yngvem_ for how to organize the project folder structure
+- to all the developers of NumPy_, pandas_ \& xarray_ for their invaluable contributions to science
 
 
 .. _NumPy: https://www.numpy.org
 .. _pandas: https://pandas.pydata.org
 .. _xarray: https://xarray.pydata.org
 .. _yngvem: https://github.com/yngvem/python-project-structure
 .. _pooch: https://github.com/fatiando/pooch
+.. _Chapman: https://github.com/jameschapman19/cca_zoo
+.. _Bueso: https://github.com/DiegoBueso/ROCK-PCA
+.. _Dawson: https://github.com/ajdawson/eofs
+.. _Yefee: https://github.com/Yefee/xMCA
+
+
+How to cite?
+----------------------
+Please make sure that when using ``xeofs`` you always cite the **original source** of the method used. Additionally, if you find ``xeofs`` useful for your research, you may cite it as follows::
+
+   @software{rieger_xeofs_2022,
+     title = {xeofs: Multi-dimensional {EOF} analysis and variants in xarray},
+     url = {https://github.com/nicrie/xeofs}
+     version = {0.6.0},
+     author = {Rieger, Niclas},
+     date = {2022},
+     doi = {10.5281/zenodo.6323011}
+   }

docs/_autosummary/xeofs.models.MCA_Rotator.rst

@@ -0,0 +1,36 @@
+xeofs.models.MCA\_Rotator
+=========================
+
+.. currentmodule:: xeofs.models
+
+.. autoclass:: MCA_Rotator
+   :members:
+   :show-inheritance: 
+   :inherited-members:
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~MCA_Rotator.__init__
+      ~MCA_Rotator.explained_covariance
+      ~MCA_Rotator.heterogeneous_patterns
+      ~MCA_Rotator.homogeneous_patterns
+      ~MCA_Rotator.pcs
+      ~MCA_Rotator.project_onto_left_singular_vectors
+      ~MCA_Rotator.project_onto_right_singular_vectors
+      ~MCA_Rotator.reconstruct_XY
+      ~MCA_Rotator.rotate
+      ~MCA_Rotator.singular_values
+      ~MCA_Rotator.singular_vectors
+      ~MCA_Rotator.squared_covariance_fraction
+
+
+
+
+
+

docs/_autosummary/xeofs.models.ROCK_PCA.rst

@@ -0,0 +1,34 @@
+xeofs.models.ROCK\_PCA
+======================
+
+.. currentmodule:: xeofs.models
+
+.. autoclass:: ROCK_PCA
+   :members:
+   :show-inheritance: 
+   :inherited-members:
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~ROCK_PCA.__init__
+      ~ROCK_PCA.eofs
+      ~ROCK_PCA.eofs_amplitude
+      ~ROCK_PCA.eofs_phase
+      ~ROCK_PCA.explained_variance
+      ~ROCK_PCA.explained_variance_ratio
+      ~ROCK_PCA.pcs
+      ~ROCK_PCA.pcs_amplitude
+      ~ROCK_PCA.pcs_phase
+      ~ROCK_PCA.solve
+
+
+
+
+
+

docs/_autosummary/xeofs.pandas.MCA_Rotator.rst

@@ -0,0 +1,36 @@
+xeofs.pandas.MCA\_Rotator
+=========================
+
+.. currentmodule:: xeofs.pandas
+
+.. autoclass:: MCA_Rotator
+   :members:
+   :show-inheritance: 
+   :inherited-members:
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~MCA_Rotator.__init__
+      ~MCA_Rotator.explained_covariance
+      ~MCA_Rotator.heterogeneous_patterns
+      ~MCA_Rotator.homogeneous_patterns
+      ~MCA_Rotator.pcs
+      ~MCA_Rotator.project_onto_left_singular_vectors
+      ~MCA_Rotator.project_onto_right_singular_vectors
+      ~MCA_Rotator.reconstruct_XY
+      ~MCA_Rotator.rotate
+      ~MCA_Rotator.singular_values
+      ~MCA_Rotator.singular_vectors
+      ~MCA_Rotator.squared_covariance_fraction
+
+
+
+
+
+

docs/_autosummary/xeofs.pandas.ROCK_PCA.rst

@@ -0,0 +1,34 @@
+xeofs.pandas.ROCK\_PCA
+======================
+
+.. currentmodule:: xeofs.pandas
+
+.. autoclass:: ROCK_PCA
+   :members:
+   :show-inheritance: 
+   :inherited-members:
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~ROCK_PCA.__init__
+      ~ROCK_PCA.eofs
+      ~ROCK_PCA.eofs_amplitude
+      ~ROCK_PCA.eofs_phase
+      ~ROCK_PCA.explained_variance
+      ~ROCK_PCA.explained_variance_ratio
+      ~ROCK_PCA.pcs
+      ~ROCK_PCA.pcs_amplitude
+      ~ROCK_PCA.pcs_phase
+      ~ROCK_PCA.solve
+
+
+
+
+
+

docs/_autosummary/xeofs.xarray.MCA_Rotator.rst

@@ -0,0 +1,36 @@
+xeofs.xarray.MCA\_Rotator
+=========================
+
+.. currentmodule:: xeofs.xarray
+
+.. autoclass:: MCA_Rotator
+   :members:
+   :show-inheritance: 
+   :inherited-members:
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~MCA_Rotator.__init__
+      ~MCA_Rotator.explained_covariance
+      ~MCA_Rotator.heterogeneous_patterns
+      ~MCA_Rotator.homogeneous_patterns
+      ~MCA_Rotator.pcs
+      ~MCA_Rotator.project_onto_left_singular_vectors
+      ~MCA_Rotator.project_onto_right_singular_vectors
+      ~MCA_Rotator.reconstruct_XY
+      ~MCA_Rotator.rotate
+      ~MCA_Rotator.singular_values
+      ~MCA_Rotator.singular_vectors
+      ~MCA_Rotator.squared_covariance_fraction
+
+
+
+
+
+

docs/_autosummary/xeofs.xarray.ROCK_PCA.rst

@@ -0,0 +1,34 @@
+xeofs.xarray.ROCK\_PCA
+======================
+
+.. currentmodule:: xeofs.xarray
+
+.. autoclass:: ROCK_PCA
+   :members:
+   :show-inheritance: 
+   :inherited-members:
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~ROCK_PCA.__init__
+      ~ROCK_PCA.eofs
+      ~ROCK_PCA.eofs_amplitude
+      ~ROCK_PCA.eofs_phase
+      ~ROCK_PCA.explained_variance
+      ~ROCK_PCA.explained_variance_ratio
+      ~ROCK_PCA.pcs
+      ~ROCK_PCA.pcs_amplitude
+      ~ROCK_PCA.pcs_phase
+      ~ROCK_PCA.solve
+
+
+
+
+
+

docs/api.rst

@@ -14,9 +14,11 @@ Numpy | ``np.ndarray``
    :recursive:
 
    xeofs.models.EOF
+   xeofs.models.ROCK_PCA
+   xeofs.models.MCA
    xeofs.models.Rotator
+   xeofs.models.MCA_Rotator
    xeofs.models.Bootstrapper
-   xeofs.models.MCA
 
 
 
@@ -32,7 +34,8 @@ pandas | ``pd.DataFrame``
    xeofs.pandas.Rotator
    xeofs.pandas.Bootstrapper
    xeofs.pandas.MCA
-
+   xeofs.pandas.MCA_Rotator
+   xeofs.pandas.ROCK_PCA
 
 *************************
 xarray | ``xr.DataArray``
@@ -43,6 +46,8 @@ xarray | ``xr.DataArray``
    :recursive:
 
    xeofs.xarray.EOF
+   xeofs.xarray.ROCK_PCA
+   xeofs.xarray.MCA
    xeofs.xarray.Rotator
+   xeofs.xarray.MCA_Rotator
    xeofs.xarray.Bootstrapper
-   xeofs.xarray.MCA

docs/auto_examples/1eof/plot_eof-smode.ipynb

@@ -26,7 +26,7 @@
       },
       "outputs": [],
       "source": [
-        "# Load packages and data:\nimport xarray as xr\nimport matplotlib.pyplot as plt\nfrom matplotlib.gridspec import GridSpec\nfrom cartopy.crs import Orthographic, PlateCarree\n\nfrom xeofs.xarray import EOF"
+        "# Load packages and data:\nimport xarray as xr\nimport matplotlib.pyplot as plt\nfrom matplotlib.gridspec import GridSpec\nfrom cartopy.crs import EqualEarth, PlateCarree\n\nfrom xeofs.xarray import EOF"
       ]
     },
     {
@@ -37,7 +37,7 @@
       },
       "outputs": [],
       "source": [
-        "t2m = xr.tutorial.load_dataset('air_temperature')['air']"
+        "sst = xr.tutorial.open_dataset('ersstv5')['sst']"
       ]
     },
     {
@@ -55,7 +55,25 @@
       },
       "outputs": [],
       "source": [
-        "model = EOF(t2m, n_modes=5, norm=False, dim='time')\nmodel.solve()\nexpvar = model.explained_variance_ratio()\neofs = model.eofs()\npcs = model.pcs()"
+        "model = EOF(sst, n_modes=5, norm=False, dim='time')\nmodel.solve()\nexpvar = model.explained_variance_ratio()\neofs = model.eofs()\npcs = model.pcs()"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Explained variance fraction\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "expvar * 100"
       ]
     },
     {
@@ -73,7 +91,7 @@
       },
       "outputs": [],
       "source": [
-        "proj = Orthographic(central_latitude=30, central_longitude=-80)\nkwargs = {\n    'cmap' : 'RdBu', 'vmin' : -.05, 'vmax': .05, 'transform': PlateCarree()\n}\n\nfig = plt.figure(figsize=(10, 10))\ngs = GridSpec(3, 4)\nax1 = fig.add_subplot(gs[0, :])\nax2 = fig.add_subplot(gs[1, 2:], projection=proj)\nax3 = fig.add_subplot(gs[1, :2])\nax4 = fig.add_subplot(gs[2, 2:], projection=proj)\nax5 = fig.add_subplot(gs[2, :2])\n\nax2.coastlines(color='.5')\nax4.coastlines(color='.5')\n\nexpvar.plot(ax=ax1, marker='.')\neofs.sel(mode=1).plot(ax=ax2, **kwargs)\npcs.sel(mode=1).plot(ax=ax3)\neofs.sel(mode=2).plot(ax=ax4, **kwargs)\npcs.sel(mode=2).plot(ax=ax5)\nplt.tight_layout()\nplt.savefig('eof-smode.jpg')"
+        "proj = EqualEarth(central_longitude=180)\nkwargs = {\n    'cmap' : 'RdBu', 'vmin' : -.05, 'vmax': .05, 'transform': PlateCarree()\n}\n\nfig = plt.figure(figsize=(10, 8))\ngs = GridSpec(3, 2, width_ratios=[1, 2])\nax0 = [fig.add_subplot(gs[i, 0]) for i in range(3)]\nax1 = [fig.add_subplot(gs[i, 1], projection=proj) for i in range(3)]\n\nfor i, (a0, a1) in enumerate(zip(ax0, ax1)):\n    pcs.sel(mode=i+1).plot(ax=a0)\n    a1.coastlines(color='.5')\n    eofs.sel(mode=i+1).plot(ax=a1, **kwargs)\n\n    a0.set_xlabel('')\n\nplt.tight_layout()\nplt.savefig('eof-smode.jpg')"
       ]
     }
   ],