1.4.0

ennemi: easy nearest neighbor estimation of mutual information. Mutual information (MI) can be used to find non-linear correlations between variables, and this Python 3 package is designed to fit into your data analysis workflow.

This minor release adds support for NumPy 2.0, pandas 2.0, and Python 3.12. There are no user-visible changes or differences in the algorithms compared to 1.3.0. (However, results may be slightly different due to changes in e.g. SciPy random number generation.)

The documentation for this release is available at https://polsys.github.io/ennemi. This release requires at least

• Python 3.10
• NumPy 1.23 (NumPy 2.0 is supported)
• SciPy 1.9
• (Optional: pandas 1.5+ or 2.x)

Changes since 1.3.0

• Support for NumPy 2.0 and pandas 2.0
• Minimum required versions of dependencies have been increased

This release fixes several warnings/crashes in ennemi caused by changes in NumPy and pandas. If you upgrade to NumPy 2.x and/or pandas 2.x, you need to update ennemi as well.

There are no new features or algorithm changes. If you cannot upgrade your Python version, ennemi 1.3 should produce (near-)identical results.

Installation

This package is available on PyPI. To install/update it, execute

pip install --upgrade ennemi

on your Python installation.

Contributing

Your feedback is very valuable! If you encounter any problems, please file an issue. Code contributions are welcomed as well.

1.3.0

ennemi: easy nearest neighbor estimation of mutual information. Mutual information (MI) can be used to find non-linear correlations between variables, and this Python 3 package is designed to fit into your data analysis workflow.

This minor release adds official support for NumPy 1.24 and Python 3.11. There are no user-visible changes or differences in the algorithms compared to 1.2.0. (However, results may be slightly different due to changes in e.g. SciPy random number generation.)

The documentation for this release is available at https://polsys.github.io/ennemi. This release requires at least

• Python 3.8
• NumPy 1.21
• SciPy 1.7
• (Optional: pandas 1.0)

Changes since 1.2.1

This release is tested with NumPy 1.24. Support for Python 3.7 and certain older NumPy and SciPy versions is dropped.

There are some internal cleanups enabled by the NumPy upgrade, but user-visible behavior should be identical.

The documentation pages received some improvements in this release.

Installation

This package is available on PyPI. To install/update it, execute

pip install --upgrade ennemi

on your Python installation.

Contributing

Your feedback is very valuable! If you encounter any problems, please file an issue. Code contributions are welcomed as well.

1.2.1

ennemi: easy nearest neighbor estimation of mutual information. Mutual information (MI) can be used to find non-linear correlations between variables, and this Python 3 package is designed to fit into your data analysis workflow.

This patch release adds official support for NumPy 1.23. There are no user-visible changes or differences in the algorithms compared to 1.2.0 or 1.1.1.

Note: This version was re-released because of a typo in the PyPI publish script. Apologies to those who get release notifications via GitHub.

The documentation for this release is available at https://polsys.github.io/ennemi. This release requires at least

• Python 3.7
• NumPy 1.19
• SciPy 1.5
• (Optional: pandas 1.0.0)

Changes since 1.2.0

This release is tested with NumPy 1.23. There are some related internal changes to type annotations, but user-visible behavior should be identical.

Python 3.7 is still supported in this version, contrary to 1.1.1 release notes.

Installation

This package is available on PyPI. To install/update it, execute

pip install --upgrade ennemi

on your Python installation.

Contributing

Your feedback is very valuable! If you encounter any problems, please file an issue. Code contributions are welcomed as well.

1.2.0

ennemi: easy nearest neighbor estimation of mutual information. Mutual information (MI) can be used to find non-linear correlations between variables, and this Python 3 package is designed to fit into your data analysis workflow.

This is a minor release that contains only small but significant "quality-of-life" changes. It also drops support for older NumPy and SciPy versions. There is no difference in the algorithms compared to 1.1.0.

The documentation for this release is available at https://polsys.github.io/ennemi. This release requires at least

• Python 3.7
• NumPy 1.19
• SciPy 1.5
• (Optional: pandas 1.0.0)

Changes since 1.1.1

Added estimate_corr and pairwise_corr methods. These methods are aliases to estimate_mi and pairwise_mi with parameter normalize=True.

Python 3.7 is still supported in this version, contrary to 1.1.1 release notes. However, the minimum NumPy and SciPy versions have increased.

Installation

This package is available on PyPI. To install/update it, execute

pip install --upgrade ennemi

on your Python installation.

Contributing

Your feedback is very valuable! If you encounter any problems, please file an issue. Code contributions are welcomed as well.

1.1.1

ennemi: easy nearest neighbor estimation of mutual information. Mutual information (MI) can be used to find non-linear correlations between variables, and this Python 3 package is designed to fit into your data analysis workflow.

This patch release contains only minor changes. There is no difference in the algorithms compared to 1.1.0.

The documentation for this release is available at https://polsys.github.io/ennemi. This release requires at least

• Python 3.7
• NumPy 1.17.5
• SciPy 1.4.0
• (Optional: pandas 1.0.0)

Changes since 1.1.0

The package is now tested with Python 3.10 and NumPy 1.22. Python 3.7 is still supported as this is a patch release. Support for Python 3.7 will be dropped in ennemi 1.2.0.

• Added warning when the normalization formula is used with discrete data.
• Fixed incorrect mention of Python 3.6 support in PyPI metadata.
• Internal changes to type-checking, no user-visible difference.

Installation

This package is available on PyPI. To install/update it, execute

pip install --upgrade ennemi

on your Python installation.

Contributing

Your feedback is very valuable! If you encounter any problems, please file an issue. Code contributions are welcomed as well.

1.1.0

This release contains minor quality-of-life improvements to ennemi: easy nearest neighbor estimation of mutual information. Mutual information (MI) can be used to find non-linear correlations between variables, and this Python 3 package is designed to fit into your data analysis workflow.

The documentation for this release is available at https://polsys.github.io/ennemi. This release requires at least

• Python 3.7
• NumPy 1.17.5
• SciPy 1.4.0
• (Optional: pandas 1.0.0)

Changes since 1.0.0

One small feature and minor fixes.

• Discrete MI:
  • Now you can compute exact MI between two discrete variables
  • Conditioning with discrete condition (any dimension) is supported
  • Pairwise MI between any kind of variables (conditioning limited for now)
  • Documentation: Working with discrete data
• Improved type annotations. Type annotations are only supported with NumPy 1.21 and newer.
• Removed support for Python 3.6.

Installation

This package is available on PyPI. To install/update it, execute

pip install --upgrade ennemi

on your Python installation.

Contributing

Your feedback is very valuable! If you encounter any problems, please file an issue. Code contributions are welcomed as well.

1.0.0

This is the first stable release of ennemi: easy nearest neighbor estimation of mutual information. Mutual information (MI) can be used to find non-linear correlations between variables, and this Python 3 package is designed to fit into your data analysis workflow.

The documentation for this release is available at https://polsys.github.io/ennemi. This release requires at least

• Python 3.6
• NumPy 1.17.5
• SciPy 1.4.0
• (Optional: pandas 1.0.0)

Features of ennemi

• Estimation of MI and the related correlation coefficient from continuous data
  • Also supported: MI between discrete and continuous variables
• Removal of known factors by conditioning on one or more variables
• Time delays, masks, and NaN removal
• Interface designed for practical data analysis
• Support for plain Python, NumPy and Pandas data types
• Optimized and parallelized algorithm

Changes since beta1

• We have documented the future support policy.
• The package supports Python 3.9 and NumPy 1.20.
• Minor internal improvements.

Installation

This package is available on PyPI. To install it, execute

pip install ennemi

on your Python installation.

Contributing

Your feedback is very valuable! If you encounter any problems, please file an issue. Code contributions are welcomed as well.

1.0.0 beta 1

This is the first beta release of ennemi: easy nearest neighbor estimation of mutual information. Mutual information (MI) can be used to find non-linear correlations between variables, and this Python 3 package is designed to fit into your data analysis workflow.

The documentation for this release is available at https://polsys.github.io/ennemi. This release requires at least

• Python 3.6
• NumPy 1.17.5
• SciPy 1.4.0
• (Optional: pandas 1.0.0)

Highlights of this release

• The algorithm is now much faster: more than 10x speedups across all estimation methods are common.
• Added support for MI between discrete y and continuous x. Pass the discrete_y parameter to estimate_mi() to enable. All features, including conditioning, are supported.
• MI methods preprocess the data by rescaling to unit variance and adding noise. You can opt out of this behavior by setting preprocess=False. More complicated transformations (e.g. logarithming) are still up to you.
• Improvements to the documentation.

Other changes

• Type annotations are included in the package. You can use mypy to verify type-correctness of your code.
• Parallelism is now implemented in threads instead of processes. As a breaking change, the parallel parameter is replaced by a max_threads parameter.
• The parallelized methods accept a callback parameter. You can implement e.g. progress bars for long-running tasks with it.
• You can now pass drop_nan=True to ignore missing values. This complements the mask parameter by not being fixed to the y variable.
• You can now set a separate lag for each conditioning variable by passing a 2D array to cond_lag.
• Bug fix: entropy estimation with both mask and cond now works.
• Internal testing improvements.

Installation

This package is available on PyPI. To install it, execute

pip install ennemi

on your Python installation.

Contributing

Your feedback is very valuable! If you encounter any problems, please file an issue. Code contributions are welcomed as well.

This release was contributed to by: @morrme.

1.0.0 alpha 2

This is the second alpha release of ennemi: easy-to-use nearest neighbor estimation of mutual information. Mutual information (MI) can be used to find non-linear correlations between variables, and this Python 3 package is designed to fit into your data analysis workflow.

This release requires Python 3.6 and NumPy 1.17.5, or newer. The documentation for this release is available at https://polsys.github.io/ennemi.

Highlights

• The pairwise_mi method makes it easy to create pairwise MI/correlation matrices. All the nice features of estimate_mi are there: it supports pandas and uses all the CPU cores for faster estimation.
• The documentation has been improved. A new case study with real-world data is included.
• The new estimate_entropy method implements nearest-neighbor estimation of differential entropy. This method is mostly included for completeness, but we have still more love planned for it.

Other changes

• The normalize parameter to estimate_mi removes the need for normalize_mi(estimate_mi(...)). The normalize_mi method won't be going anywhere, if you still need to use it.
• Improved some error messages and input checks. It should now be harder to get an ugly backtrace deep within the algorithm.
• You can now install the development dependencies by pip install ennemi[dev].
• Extended the test suite with several realistic test cases. You can be more confident that ennemi does what it promises.

Installation

This package is available on PyPI. To install it, execute

pip install ennemi

on your Python installation.

1.0.0 alpha 1

This is the first alpha release of ennemi: easy-to-use nearest neighbor estimation of mutual information. Mutual information (MI) can be used to find non-linear correlations between variables, and this Python 3 package is designed to fit into your data analysis workflow.

Features

• Mutual information between one or more variable pairs
• Conditional mutual information, with as many conditioning variables as you like
• Time lags between variables
• Masking of observations, integrated with time lags
• Normalization of results to a correlation coefficient scale
• Integration with pandas data frames and series (optional, no runtime dependency)
• Optimized and parallelized algorithm, written in pure Python with NumPy

Installation

This package is available on PyPI. To install it, execute

pip install ennemi

on your Python installation. Python 3.6 and later on Linux, macOS and Windows are supported.

Work in progress

This package is still in development. While the algorithm itself is reliable, the interface may still change between alpha versions. If you encounter problems or have suggestions, please file an issue!