Documentation

In brief

ennemi is a Python 3 package for estimating mutual information and other information-theoretic measures of continuous variables. These measures can be used for non-linear correlation analysis. The package is designed for practical data analysis with no theoretical background required.

Features:

• Non-linear correlation detection:
  • Mutual information between two variables, continous or discrete
  • Conditional MI with arbitrary-dimensional conditioning variables
  • Quick overview of many-variable datasets with pairwise MI estimation
• Practical data analysis:
  • Interfaces for evaluating multiple variable pairs and time lags with one call
  • Integrated with pandas data frames (optional)
  • Optimized and automatically parallelized estimation
  • Algorithms verified to work, so that you can focus on your data

ennemi is maintained by Petri Laarne (@polsys) and was initially developed at Institute for Atmospheric and Earth System Research (INAR), University of Helsinki. The package is published under the MIT License.

Documentation topics

• What is entropy? A quick overview of the theory and terminology.
• Tutorials:
  • Getting started. This tutorial covers the basic use cases through examples.
  • Case study. An example workflow with real data.
  • Working with discrete data. Estimation and interpretation when some variables are discrete.
• Potential issues. Common issues and how to solve them.
• API reference. All methods and their parameters.
• Code snippets. Example utilities that may be useful.
• Future support. What to expect from the maintenance.

Installation

This package is available on PyPI:

pip install ennemi

Citing

If you use this software in scientific work, please consider mentioning the exact version number for reproducibility. Versions are citable and archived on Zenodo (doi:10.5281/zenodo.3834018).

This package is described in the following articles:

• Code: Laarne, Zaidan, Nieminen: ennemi: Non-linear correlation detection with mutual information, SoftwareX, 2021. doi:10.1016/j.softx.2021.100686.
• Case study (with downloadable source code for all examples): Laarne, Amnell, Zaidan, Mikkonen, Nieminen: Exploring Non-Linear Dependencies in Atmospheric Data with Mutual Information, Atmosphere, 2022. doi:10.3390/atmos13071046.

Several research groups have already published papers that cite ennemi. We hope that you find the package useful for your work!