the Creative Commons Attribution 4.0 License.
the Creative Commons Attribution 4.0 License.
| 26 May 2026
MJO Diagnostic Tools v1.1: Reassessment and implementation of standard MJO diagnostic tools in Python
Abstract. The Madden–Julian Oscillation (MJO) remains difficult to simulate realistically in atmospheric and coupled models, with model performance being strongly dependent on physical parameterizations and model configurations. A standardized and reproducible diagnostic framework of the MJO is therefore essential for systematic evaluation and model development. A widely used set of MJO diagnostics was developed by the US CLIVAR MJO Working Group in 2009 (MJO-WG09), but its original implementation depends on software and workflows that are no longer readily accessible in modern computing environments.
In this study, we reimplement the MJO-WG09 diagnostics using Python-based analysis libraries. The diagnostics are reconstructed following the published methodology and, where necessary, by examining the original source code to resolve ambiguities. As a result of methodological reassessment, the new implementation differs from the original in aspects such as temporal filtering, statistical testing, and spectral analysis; these differences are documented and discussed. In addition, we introduce a new diagnostic to evaluate the Walker circulation associated with the MJO. The open-source package provides a reproducible foundation for consistent evaluation of MJO simulations across models.
- Preprint
(10894 KB) - Metadata XML
- BibTeX
- EndNote
Status: final response (author comments only)
- RC1: 'Comment on egusphere-2026-2626', Anonymous Referee #1, 12 Jul 2026
-
RC2: 'Review on „MJO Diagnostic Tools v1.1: Reassessment and implementation of standard MJO diagnostic tools in Python“', Christoph Hoffmann, 27 Jul 2026
The authors describe their reproduction of MJO diagnostics originally developed in 2009. They provide example code in the modern programming language Python for these diagnostics and the manuscript also aims to make the community aware on the availability of this code.
After reading, I wavered between recommending minor or major revisions.
It is kind of a special manuscript, since it does not present anything really new and instead reports on a modern reproduction and porting of analysis software. I definitely think that this a valuable contribution to the field, which should be made available and acknowledged through a proper publication in GMD.
Furthermore, the publication is in good shape, easy to follow, well-structured and -- since it reproduces an earlier publication -- it is rather easy to check that the results are overall valid. Hence, from a strict GMD perspective, I would recommend only minor corrections, which are listed below under “Minor issues regarding the manuscript”. More detailed scientific aspects have already been raised by the first anonymous reviewer.
However, there is another major aspect, which is probably somewhat beyond the scope of the GMD criteria for a publication. But it is, from my perspective, important for the quality of the underlying software package, which is the basis for the publication. My concern is that also this reworked package will no longer be usable, either technically or scientifically, within only a few years and the efforts of the authors might then be wasted if not a few aspects of software quality are fulfilled. This is detailed in “Major issues regarding the code base of the software package”.
Since I know myself that it is inconvenient to be thrown back to the level of software development, when the corresponding publication should be quickly finished, I decided to declare this as a major point, to make unmistakably clear (hopefully in a constructive way) that the sustained reusability of their package is, from my perspective, currently not achieved, so that the authors hopefully seriously consider to take the recommended extra effort.
Finally, the editor can still decide, that only the criteria directly applicable to the manuscript have to be considered, then it would be a minor revision from my perspective.
Major issues regarding the code base of the software package
From my perspective, the authors make similar mistakes in terms of long-term usability of the software package as the authors of the original analysis tools themselves – with the exception that the authors of the current manuscript provide the package with a persistent DOI on Zenodo instead of using an arbitrary transient website, which is of course an improvement for availability.
Still, I am afraid that the files loaded from Zenodo will be error-prone for other users and their reliability in terms of executability and correctness of the calculations is limited. In contrast to this, the awareness for criteria of high-quality research software, which is worth to be published, has risen since the original publication. I would recommend the following improvements of the software itself. They would be accompanied by only smaller explanatory changes is the manuscript
- Separation of calculation and evaluation. The complete code is stored in IPython Notebooks, which are intended to aid simple data exploration, but are not well suited for performing the calculations. So cleanly split the calculations from the visualisations and put the calculations into .py files. This has several advantages, which are implicitly covered in the following.
- Without this separation, many Notebooks will exist also for a single user, which analyse different data but contain redundant calculation code. It will become almost impossible to share updates of the method or bugfixes consistently.
- Unit testing: This clean separation of calculation and evaluation enables you to implement and provide unit tests for the calculation routines. These tests run individual computation steps with known input data and compare the results to provided reference data. Providing unit tests with the code has several advantages:
- The user can easily check if everything works as expected.
- In the future, the underlying Python packages will change. Even if your code remains stable, it is unclear, if the results remain stable given the change of the underlying packages. Well-designed unit tests will therefore be suitable to check any execution environment, even in the future.
- They enable you, as the maintainers, to make quick adaptations with respect to changes of the underlying packages (since incompatibilities will occur) without worrying about the quality of the calculation, since validation is intrinsically included.
- Reference input and output data is implicitly provided by you (because you need them for the unit tests to function) and belong directly to the package. This will also enable reproduction studies in the more distant future.
- The code of the unit tests and the reference data can also serve as examples for users.
- Compile a proper Python package and upload it to the Python Package Index (https://pypi.org/). It then becomes installable with “pip”. This is convenient for the users and makes support easier for you: In case of questions, you have a higher probability that the calculation code of the package has not been changed by the user.
- Still share all versions of your code in a public git environment (e.g., GitHub), so that the source code and also changes between the versions can be explored by the users. It also enables contributions and improvements by the community (which are of course still under your control).
- Include a compilation of all data needed for a complete reproduction of your results. Possibly, this has already been achieved while implementing the unit tests. But double-check this to achieve reproducibility in many years.
- Extend your documentation of the code. Particularly, be more precise on the internal format of the input data files and mark entry points and parameters, which are intended to be changed by the user.
This may appear to require a lot of work, but I think that it is not that much in comparison to the effort already taken.
There are many examples of such elaborated research software packages, but since I am most familiar with my own package, I mention it as a possible template (although it also needs a technical update soon): https://github.com/cghoffmann/mjoindices / https://pypi.org/project/mjoindices/ / https://zenodo.org/records/7261815 / https://zenodo.org/records/3746563 / https://openresearchsoftware.metajnl.com/articles/10.5334/jors.331
Minor issues regarding the manuscript:
Line 49: Have the authors tried to contact the owners of the website? Also in the following, it partly remains hard to understand which kind of code and data was still available and which was not. For the unavailable parts, it would be of interest, if the original providers have been contacted and if they were really unable to provide code and data. Maybe the authors can comment on this.
Section 2: This is a rather short description of the environment. When the package is improved, more information on unit testing, usage etc. could be placed here.
Line 85: “we use...”: Does this mean that the user also has to use it in this way or is it your personal example?
Line 92: As stated above: I would recommend to compile the reference dataset with exactly the used data and to store it persistently as well for future reproduction.
Line 93: “longitude spacing (0.125°E-0.125°W)” Does this mean that the data spans all longitudes? This could then be written more easily.
Line 96: “CMAP”: This and other acronyms appear to be unexplained. Please check everywhere.
Line 143: This is also a disadvantage of the current code structure. Although the IPython Notebooks are generally well-named, it is not always totally straightforward to find the piece of code associated with the description in the manuscript. I recommend naming entry points explicitly in the paper.
Line 147: A quick note on which differences are expected from theory could be helpful. So how different are the filters or the other way around: Have you taken the Python implementation, which is closest to the original?
Line 153: Did you contact the authors in order to confirm a mistake?
Line 160: Do I understand it correctly that the validation of your results is everywhere in the paper based on a visual inspection of the plots? Or was it somewhere possible to compare quantitatively to the original results. It would be good to comment on this somewhere.
Lines 200 and 205: The authors miss information in the original publication but are themselves from my impression not very detailed here. What is exactly meant with “spectral analysis”? Please give all the information, which would be needed for reproduction.
Lines 209 and 210: I am not sure if this sentence is well constructed, especially after “k ≈ 1–4”.
Figure A2 and following: The authors could consider to explicitly mention the numbers of the corresponding figures in the original publication.
Figure A3: Can we get the contour interval from the information given? If not, please check everywhere.
Citation: https://doi.org/10.5194/egusphere-2026-2626-RC2
Viewed
| HTML | XML | Total | BibTeX | EndNote | |
|---|---|---|---|---|---|
| 207 | 77 | 18 | 302 | 16 | 13 |
- HTML: 207
- PDF: 77
- XML: 18
- Total: 302
- BibTeX: 16
- EndNote: 13
Viewed (geographical distribution)
| Country | # | Views | % |
|---|
| Total: | 0 |
| HTML: | 0 |
| PDF: | 0 |
| XML: | 0 |
- 1
This manuscript presents a valuable Python-based reimplementation of the classic MJO-WG09 diagnostic framework. Given the declining accessibility of legacy tools like GrADS, this work represents an important contribution to the climate community for evaluation of MJO representation in traditional climate and emerging AI models. However, I have several major methodological concerns regarding the data processing (especially for the spectral and filtering analysis), structural organization, and technical inaccuracies that can be improved for this manuscript before publication.
Major Comments:
Methodology of Space-Time Spectral Analysis and Filtering (Sections 4.2.2, Lines 227-228, Lines 240-241): The authors state that they apply a linear detrend to each 256-day segment. Applying a linear detrend directly to segments that still contain the raw seasonal cycle is highly concerning, possibly introducing artificial signals into the coherence-squared spectrum. A more reasonable approach would be to 1) first remove the climatological annual cycle and linear trend for the original data (OLR, U850) during the past decades, 2) construct the analysis segments, and 3) finally conduct the coherence-squared spectra and phase lag calculations.
Walker circulation diagnostic (Section 4.2.5 & Lines 119–120): While the inclusion of the Walker circulation in this diagnostic suite is a great addition, it represents a mean state (climatology) rather than a higher-order MJO propagation or variability statistic. To maintain a logical flow, the presentation of the Mean Walker Circulation should be moved from Section 4.2 ("Level 2 diagnostics") to Section 4.1.
Data Availability (Section 3): To ensure full reproducibility, the authors are strongly encouraged to upload the specific processed dataset used for this analysis to the online archive (e.g., Zenodo), in addition to the source code.
Possible Additional Diagnostics: While this study largely replicates and modernizes the results from Waliser et al. (2009), the utility of this Python package would be significantly enhanced by adding some important, yet simple, MJO diagnostics. Specifically, I highly recommend including longitude-vertical cross-sections of specific humidity (q), temperature (T), and vertical velocity (omega) to capture the vertical structure associated with MJO convection over the Indian Ocean and Western Pacific.
Global Grammar Check: The manuscript contains several scattered grammatical, punctuation, and syntax oversights. It is highly recommended that the authors thoroughly proofread the entire text prior to resubmission.
Other minor comments:
Line 16: Please spell out the acronym CLIVAR at its first mention.
Lines 22–23: The text mentions "the Walker circulation associated with the MJO." However, this appears to represent only the background mean state rather than a composite for the MJO.
Line 30: "maritime continent" should be capitalized as "Maritime Continent".
Line 53: Insert a comma before "which" to read as "...GrADS), which were...".
Line 108: For simplicity, the authors may consider rephrasing this definition to "PRCP (representing the column-integrated latent heat release)".
Line 140: Suggest changing "Appendix A Figs. A1 and A2" to "Figs. A1 and A2".
Line 154: "...variance of the unfiltered, data." Remove the misplaced comma after "unfiltered".
Line 267: "Because neither study provides details of their normalization, we investigated the discrepancy." Change to "Since neither study provides explicit details regarding its normalization, we investigated the underlying
discrepancy."
Line 282: Change "the leading EOF modes" to "the first leading EOF mode".
Line 213: Why "small" divergent flows?
Section 4.2.3, Lines 257-258: Please clarify whether the climatological annual cycle was removed prior to applying the band-pass time filter.
Line 315: Please verify if "numpy.fft.fft" is the exact function utilized.
Figs. A1 and A2: The unit for the SST should be °C rather than K.
Fig. A4: Is it possible to add a 95% significance test overlay for the precipitation fields? Additionally, units for PRCP and U850 are missing from the figures or captions and should be added.
Figs. 6a and 6b: The units for vertical velocity omega (m/s) appear to be incorrect for pressure coordinates.
Lines 354-365: Possibly the weakening of the mean subsidence around 130E during the winter is simply due to active MJO passage over the Maritime Continent. It is difficult to disentangle the cause and effect here.