Package: mjoindices
mjoindices - A python package for calculating the Madden-Julian-Oscillation OMI indexOverviewmjoindices 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 the future, the
implementation is currently limited to the OMI algorithm.A scientific description of the package is found inHoffmann et al. (2021).CitationIf 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.331Please check ourlist of further scientific publications, on which the
implementation of the package is based. It is likely that some of these publications should also be cited.ContributorsThanks for the contributions from the community!Requirementsmjoindices 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)Installationmjoindices is available in thePython Package Index (PyPI). It can be installed using,
e.g., pip.pip3 install mjoindicesIt can also be installed from the source, which is available onZenodoandGitHub.
Download the source, move into the directory containing the file setup.py and runpip3 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]orpip3 install -e .[dev]Getting started / examplesNote 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.Calculation of the PCs:calculate_pcs_from_olr.An OLR data container class, which has to be provided for the calculations:OLRDataAfter you have installed mjoindices, you can download anexamplefrom 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 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 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.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 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.DocumentationThe documentation is found onGitHub Pagesand also in the docs
folder of thesource.Automated testingAfter you have installed mjoindices, you can also downloadunit and integration testsfrom the source to check
your installation using pytest:Download the complete test directory to you local file system.Download the external input and reference data files fromZenodo. Details are given in a separateReadme file.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 withpip3 install mjoindices[dev]Move into your local test directory and runpytestIn 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.pytest -m 'not slow'