Merge pull request #16 from cghoffmann/pp_flexibility

Integration of Pp flexibility branch (no leap _years, EOF rotation, xarrax loading)

CITATION.cff

@@ -0,0 +1,33 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+authors:
+- family-names: "Hoffmann"
+  given-names: "Christoph G."
+  orcid: "https://orcid.org/0000-0003-2712-8648"
+title: "mjoindices"
+abstract: "A Python Package to Calculate the OLR-Based Index of the Madden-Julian-Oscillation (OMI)"
+license: GPL-3.0 license
+doi:  10.5281/zenodo.3957857
+repository-code: "https://github.com/cghoffmann/mjoindices"
+preferred-citation:
+  type: article
+  authors:
+  - family-names: "Hoffmann"
+    given-names: "Christoph G."
+    orcid: "https://orcid.org/0000-0003-2712-8648"
+  - family-names: "Kiladis"
+    given-names: "George N."
+    orcid: "https://orcid.org/0000-0001-6588-3762"
+  - family-names: "Gehne"
+    given-names: "Maria"
+    orcid: "https://orcid.org/0000-0002-7267-8676"
+  - family-names: "von Savigny"
+    given-names: "Christian"
+    orcid: "https://orcid.org/0000-0001-7926-3986"
+  doi: "10.5334/jors.331"
+  journal: "Journal of Open Research Software"
+  title: "A Python Package to Calculate the OLR-Based Index of the Madden-Julian-Oscillation (OMI) in Climate Science and Weather Forecasting"
+  volume: 9
+  issue: 1
+  year: 2021
+  month: 5

README.md

@@ -7,27 +7,37 @@ mjoindices - A python package for calculating the Madden-Julian-Oscillation OMI
 Overview
 --------
 
-mjoindices is a Python package relevant for users of the atmospheric sciences. It provides functionality to compute an 
+mjoindices is a Python package relevant for atmospheric scientists. It provides functionality to compute an 
 index of the Madden-Julian-Oscillation (MJO), particularly the OLR-based MJO index (OMI).
 
-Whereas the package name has been chosen to indicate that further MJO indices should be included in future, the 
+Whereas the package name has been chosen to indicate that further MJO indices should be included in the future, the 
 implementation is currently limited to the OMI algorithm.
 
-A scientific description of the packge is found in [Hoffmann et al. (2021)](https://doi.org/10.5334/jors.331).
+A scientific description of the package is found in [Hoffmann et al. (2021)](https://doi.org/10.5334/jors.331).
 
 Citation
 --------
-If you use mjoindices in published research, please cite the correspondig paper: Hoffmann, C.G., Kiladis, G.N., Gehne, M. and von Savigny, C., 2021.
+If you use mjoindices in published research, please cite the corresponding paper: Hoffmann, C.G., Kiladis, G.N., Gehne, M. and von Savigny, C., 2021.
 A Python Package to Calculate the OLR-Based Index of the Madden- Julian-Oscillation (OMI) in Climate Science and Weather Forecasting. 
 Journal of Open Research Software, 9(1), p.9. DOI: http://doi.org/10.5334/jors.331
 
-In addition, you can also cite the Zenodo DOI http://dx.doi.org/10.5281/zenodo.3613752.
+Please check our [list of further scientific publications](https://cghoffmann.github.io/mjoindices/references.html), on which the
+implementation of the package is based. It is likely that some of these publications should also be cited.
+
+Contributors
+------------
+Thanks for the contributions from the community!
+
+[![Contributors](https://contrib.rocks/image?repo=cghoffmann/mjoindices)](https://github.com/cghoffmann/mjoindices/graphs/contributors)
+
 
 Requirements
 ------------
-mjoindices is written for Python 3 (version > 3.6) and depends on the packages NumPy, Pandas, SciPy, and Matplotlib. It runs on Linux
+mjoindices is written for Python 3 (version >= 3.7) and depends on the packages NumPy, Pandas, SciPy, and Matplotlib. It runs on Linux
 and Windows. Other operating systems have not been tested. 
 
+There are optional requirements, which can be installed along with mjoindices (see below)
+
 Installation
 ------------
 mjoindices is available in the [Python Package Index (PyPI)](https://pypi.org/project/mjoindices/). It can be installed using, 
@@ -38,48 +48,90 @@ e.g., pip.
 It can also be installed from the source, which is available on [Zenodo](http://dx.doi.org/10.5281/zenodo.3613752) and [GitHub](https://github.com/cghoffmann/mjoindices). 
 Download the source, move into the directory containing the file setup.py and run
 
-    python3 setup.py install
-
-API documentation
------------------
-The API documentation is found on [GitHub Pages](https://cghoffmann.github.io/mjoindices/index.html) and also in the docs
-folder of the [source](https://github.com/cghoffmann/mjoindices/tree/master/docs).
-
+    pip3 install .
+
+The following optional dependency sets can additionaly be installed by adding ["set_name"] behind the above commands:
+  * *full_func*: Install these packages to be sure that all options are really available. This might 
+    require a higher Python version than for the core functionality alone. OMI may still be computed without these
+    additional packages, but the number of alternative approaches is limited.
+  * *dev*: packages that are needed for the further development, documentation and testing of mjoindices.
+
+Examples: 
+
+    pip3 install mjoindices[full_func]
+
+or
+
+    pip3 install -e .[dev]
+
 Getting started / examples
 --------------------------
+*Note for experienced users: We have slightly changed the API for the EOF calculation with version 1.4. to be more flexible 
+for changes in the future. Please read the API docs or compare your code with the current example. The old API is still
+working but will deprecate with one of the next releases. Adapting to the new interface will only take a few minutes.*
+
+There are three basic entry points, of which you should read the documentation:
+
+* Calculation of the EOFs: [calc_eofs_from_olr](https://cghoffmann.github.io/mjoindices/api/omi_calculator.html#mjoindices.omi.omi_calculator.calc_eofs_from_olr).
+* Calculation of the PCs: [calculate_pcs_from_olr](https://cghoffmann.github.io/mjoindices/api/omi_calculator.html#mjoindices.omi.omi_calculator.calculate_pcs_from_olr).
+* An OLR data container class, which has to be provided for the calculations: [OLRData](https://cghoffmann.github.io/mjoindices/api/olr_handling.html#mjoindices.olr_handling.OLRData)
+
 After you have installed mjoindices, you can download an
-[example](https://github.com/cghoffmann/mjoindices/tree/master/examples) from the source, which consists of two files: 
+[example](examples/) from the source, which consists of two files: 
 
 * recalculate_original_omi.py: After downloading some data files, which are mentioned and linked in the source
-documentation of the example, you can run this example to recalculate the original OMI values. The script will save
-the computed Empirical Orthogonal Functions (EOFs) and the Principal Components (PCs) in two individual files, which
-can also be configured in the source code. In addition, it will save a few plots into a directory, which can
-also be configured in the source. These plots show the agreement with the original OMI values (slight deviations are 
-expected due to numerical differences. This will be detailed in the corresponding software meta paper).
+  documentation of the example, you can run this example to recalculate the original OMI values. The script will save
+  the computed Empirical Orthogonal Functions (EOFs) and the Principal Components (PCs) in two individual files, which
+  can also be configured in the source code. In addition, it will save a few plots into a directory, which can
+  also be configured in the source. These plots show the agreement with the original OMI values (slight deviations are 
+  expected due to numerical differences. This is explained in detail in the corresponding software meta paper).
 
-    Note that you can use this example also as a template to calculate OMI values with your own OLR data. 
-In order to do that, you have to adapt only two parts of the code, which are also marked in the code documentation.
+  Note that you can use this example also as a template to calculate OMI values with your own OLR data. 
+  In order to do that, you only have to adapt two parts of the code, which are also marked in the code documentation.
 
-    Note also that this script may run for one or two hours on common personal computer systems.
+  Note also that this script may run for one or two hours on common personal computer systems.
 
 * evaluate_omi_reproduction.py: This script produces more detailed comparison plots and saves them into a directory.
-The script recalculate_original_omi.py has to be run before, as the evaluation script is based on the saved results.
-As for recalculate_original_omi.py, some file and directory names have to be adapted in the beginning of the code.
+  The script recalculate_original_omi.py has to be run first, since the evaluation script is based on the saved results.
+  As for recalculate_original_omi.py, some file and directory names have to be adapted in the beginning of the code.
 
 Both files are also available as Jupyter notebook files.
 
+Documentation
+-----------------
+The documentation is found on [GitHub Pages](https://cghoffmann.github.io/mjoindices/index.html) and also in the docs
+folder of the [source](docs/index.html).
+
 Automated testing
 -----------------
 After you have installed mjoindices, you can also download
-[unit and integration tests](https://github.com/cghoffmann/mjoindices/tree/master/tests) from the source to check
-your installation using pytest.
+[unit and integration tests](tests/) from the source to check
+your installation using pytest:
 
 * Download the complete test directory to you local file system.
 
-* Download some external input and reference data files from  [Zenodo](https://doi.org/10.5281/zenodo.3746562). Details are given in a separate [Readme file](https://github.com/cghoffmann/mjoindices/blob/master/tests/testdata/README). 
+* Download the external input and reference data files from [Zenodo](https://doi.org/10.5281/zenodo.3746562). Details are given in a separate [Readme file](tests/testdata/README). 
+  * Note that some necessary data files are already included in the test directory in the repository. Make sure to download
+    those files together with the tests. The data files on Zenodo are complementary and not 
+    included in the repository for reasons of file size and ownership.
+
+* Install the pytest package or simply install the mjoindices development dependencies with 
+
+      pip3 install mjoindices[dev]
 
 * Move into your local test directory and run
 
-        pytest
+      pytest
+
+* In the case that some tests are failing with FileNotFoundErrors, it is likely that the package code is actually working, but that the test 
+  environment is not set up properly. You should check the following before contacting us:
+   * Did you download the data files from the repository?
+   * Did you download the data files from Zenodo?
+   * Did you preserve the directory structure?
+   * Did you execute pytest in the tests/ subdirectory (where pytest.ini is located)? 
+
+* Note that the tests may run for a few hours on a common personal computer.
+  * To get a quicker impression, you can omit slow tests by executing the following command. However, this will
+    not check the core OMI computation, which is most important, of course.
 
-Note that the tests may run for a few hours on a common personal computer.
+        pytest -m 'not slow' 

Release_Checklist.md

@@ -1,3 +1,6 @@
+#To install optional development dependencies
+- pip install -e .[dev]
+
 #Jupyter Notebooks
 - clear cell outputs 
 
@@ -18,7 +21,7 @@
 
 # Setup Tools
 - activate venv
-- python3 setup.py sdist bdist_wheel
+- python -m build
 
 # GitHub
 - Create Release from new tag

docs/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 43c19e6dc6482ba3e17a2858545d2353
+config: f446bbd3bce08b8f7ba94e8fd09f77d6
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/_modules/index.html

@@ -1,38 +1,46 @@
 
 
 <!DOCTYPE html>
-<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
-<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
+<html class="writer-html5" lang="en" >
 <head>
-  <meta charset="utf-8">
+  <meta charset="utf-8" />
 
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
 
   <title>Overview: module code &mdash; mjoindices  documentation</title>
 
 
 
+  <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
+  <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+  <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+  <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
+
+
 
+
 
 
 
 
-  <script type="text/javascript" src="../_static/js/modernizr.min.js"></script>
+
+
+  <!--[if lt IE 9]>
+    <script src="../_static/js/html5shiv.min.js"></script>
+  <![endif]-->
 
 
       <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+        <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
         <script src="../_static/jquery.js"></script>
         <script src="../_static/underscore.js"></script>
+        <script src="../_static/_sphinx_javascript_frameworks_compat.js"></script>
         <script src="../_static/doctools.js"></script>
-        <script src="../_static/language_data.js"></script>
+        <script src="../_static/sphinx_highlight.js"></script>
 
     <script type="text/javascript" src="../_static/js/theme.js"></script>
 
 
-
-
-  <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
-  <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
     <link rel="index" title="Index" href="../genindex.html" />
     <link rel="search" title="Search" href="../search.html" /> 
 </head>
@@ -71,25 +79,28 @@
 
         </div>
 
+
         <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
 
 
 
 
 
 
-              <p class="caption"><span class="caption-text">Contents:</span></p>
+              <p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="../quickstart.html">Quickstart</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../api/apidoc.html">API documentation (for running calculations)</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../api/apidoc.html#api-documentation-for-working-with-results">API documentation (for working with results)</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../api/apidoc.html#api-documentation-minor-relevance-for-users">API documentation (minor relevance for users)</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../references.html">References and citation hints</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../indices.html">Indices and tables</a></li>
 </ul>
 
 
 
         </div>
+
       </div>
     </nav>
 
@@ -124,11 +135,13 @@
 
 
 
+
+
 <div role="navigation" aria-label="breadcrumbs navigation">
 
   <ul class="wy-breadcrumbs">
 
-      <li><a href="../index.html">Docs</a> &raquo;</li>
+      <li><a href="../index.html" class="icon icon-home"></a> &raquo;</li>
 
       <li>Overview: module code</li>
 
@@ -150,6 +163,8 @@ <h1>All modules for which code is available</h1>
 <li><a href="mjoindices/evaluation_tools.html">mjoindices.evaluation_tools</a></li>
 <li><a href="mjoindices/olr_handling.html">mjoindices.olr_handling</a></li>
 <li><a href="mjoindices/omi/omi_calculator.html">mjoindices.omi.omi_calculator</a></li>
+<li><a href="mjoindices/omi/postprocessing_original_kiladis2014.html">mjoindices.omi.postprocessing_original_kiladis2014</a></li>
+<li><a href="mjoindices/omi/postprocessing_rotation_approach.html">mjoindices.omi.postprocessing_rotation_approach</a></li>
 <li><a href="mjoindices/omi/quick_temporal_filter.html">mjoindices.omi.quick_temporal_filter</a></li>
 <li><a href="mjoindices/omi/wheeler_kiladis_mjo_filter.html">mjoindices.omi.wheeler_kiladis_mjo_filter</a></li>
 <li><a href="mjoindices/principal_components.html">mjoindices.principal_components</a></li>
@@ -160,20 +175,25 @@ <h1>All modules for which code is available</h1>
 
           </div>
           <footer>
-
 
   <hr/>
 
   <div role="contentinfo">
     <p>
-        &copy; Copyright 2020, Christoph G. Hoffmann
+        &#169; Copyright 2020, Christoph G. Hoffmann.
 
     </p>
   </div>
-  Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. 
+
+
+
+    Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
+
+    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
+
+    provided by <a href="https://readthedocs.org">Read the Docs</a>. 
 
 </footer>
-
         </div>
       </div>
 
@@ -182,7 +202,6 @@ <h1>All modules for which code is available</h1>
   </div>
 
 
-
   <script type="text/javascript">
       jQuery(function () {
           SphinxRtdTheme.Navigation.enable(true);
@@ -200,6 +219,7 @@ <h1>All modules for which code is available</h1>
     })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
 
     ga('create', 'UA-XXXXXXX-1', 'auto');
+
     ga('send', 'pageview');
     </script>