Home

Welcome to the Read the Docs page for pyhanami. This documentation contains detailed information on how to use the pyhanami Python package, a tool designed to evaluate the replicability and scientific skill of Earth System Models (ESMs).

Description

pyhanami is a Python package that provides tools for:

  1. Generating diagnostic visualizations (e.g., time series and spatial plots)

  2. Evaluating the replicability of ESMs (e.g., identify significant differences between experiments)

  3. Assessing the scientific skill of ESMs (e.g., scalar scores related to several climate phenomena)

Key features of the package include:

  • Easy input handling: load climate simulation ensembles from a NetCDF file or an xarray.Dataset object (in future releases, also from an intake catalogue) using the SimulationData class.

  • Diagnostics plotting: generate visualizations comparing two previously loaded simulation ensembles for selected variables using the DataDiagnostics class. These include time series and spatial plots. The latter involves plots displaying the absolute difference and the effect size (Cohen’s d) between two ensembles, and bias plots comparing the simulations to reference observations.

  • Replicability testing: perform a replicability test checking the statistical indistinguishability between two previously loaded simulation ensembles using the ReplicabilityTest class.

  • Scientific skill evaluation: compute scalar scores evaluating the following phenomena using the ScientificEvaluation class:

    • General skill: this includes the computation of general scalar scores (bias (BIAS), Root Mean Square Error (RMSE), and spatial Pearson correlation (\(r_{xy}\))) for any variable in the simulation dataset comparing to observations.

    • Tropical IntraSeasonal Oscillation (ISO): this includes the computation of the bimodal ISO indices (for MJO and BSISO), as well as the calculation of related scalar scores comparing the indices between simulations and observations (amplitude ratio (\(\alpha\)), temporal correlation (\(R\)), standard deviation ratio (\(\sigma\)), and Taylor Skill Score (TSS)).

    • Madden-Julian Oscillation (MJO): this includes the computation of the Real-Time Multivariate MJO (RMM) indices and the MJO power spectrum, as well as the calculation of related scalar scores (Pearson correlation (\(r_{\text{var,mode}}\)) and bias (\(b\))) comparing the MJO spatial patterns, activity and power between simulations and observations.

    • Tropical Cyclones (TCs): this includes the computation of various scalar scores (bias (\(\bar{b}\)), spatial Pearson correlation (\(r_{xy}\)), and temporal Spearman rank correlation (\(\rho_s\))) for several TC metrics (counts, TC days (TCD), accumulated cyclone energy (ACE), pressure ACE (PACE), and latitude of lifetime-maximum intensity (LMI)).

  • Flexible data management: add and compare datasets in the DataDiagnostics, ReplicabilityTest, and ScientificEvaluation classes even after initialization.

Future releases will include:

  • Additional scientific skill evaluation: compute additional scalar scores evaluating several climate phenomena, such as precipitation.

  • Automated report generation: produce reports including plots and scores summary.

For quick start instructions, see the README on the project’s GitHub repository. This documentation provides in-depth information and advanced usage details.

Contact people

Main developer:

This work was developed as part of the Hpc AlliaNce for Applications and supercoMputing Innovation (HANAMI) project, which received funding from the European High Performance Computing Joint Undertaking (EuroHPC JU) under the European Union’s Horizon Europe framework program for research and innovation and Grant Agreement No. 101136269.