Skip to content

NorMI: Nonparametric Normalized Mutual Information Estimator Based on k-NN Statistics

This software provides an extension to the Kraskov-Estimator to allow normalizing the mutual information.

The method was published in:

Accurate estimation of the normalized mutual information of multidimensional data
D. Nagel, G. Diez, and G. Stock,
J. Chem. Phys. 2024 161, 054108
doi: 10.1063/5.0217960

If you use this software package, please cite the above mentioned paper.

Features

  • Intuitive usage via module and via CI
  • Sklearn-style API for fast integration into your Python workflow
  • No magic, only a single parameter which can be optimized via cross-validation
  • Extensive documentation and detailed discussion in publication

Installation

The package is called normi and is available via PyPI or conda. To install it, simply call: 

python3 -m pip install --upgrade normi
or 
conda install -c conda-forge normi
or for the latest dev version 
# via ssh key
python3 -m pip install git+ssh://git@github.com/moldyn/NorMI.git

# or via password-based login
python3 -m pip install git+https://github.com/moldyn/NorMI.git

Shell Completion

Using the bash, zsh or fish shell click provides an easy way to provide shell completion, checkout the docs. In the case of bash you need to add following line to your ~/.bashrc 

eval "$(_NORMI_COMPLETE=bash_source normi)"

Usage

In general one can call the module directly by its entry point $ normi or by calling the module $ python -m normi. The latter method is preferred to ensure using the desired python environment. For enabling the shell completion, the entry point needs to be used.

CI - Usage Directly from the Command Line

The module brings a rich CI using click. For a complete list of all options please see the docs. 

python -m normi /
  --input input_file  / # ascii file of shape (n_samples, n_features)
  --output output_file  / # creates ascii file of shape (n_features, n_features)
  --n-dims / # this allows to treat every n_dims columns as a high dimensional feature
  --verbose

Module - Inside a Python Script

from normi import NormalizedMI

# Load file
# X is np.ndarray of shape (n_samples, n_features)

nmi = NormalizedMI()
nmi_matrix = nmi.fit_transform(X)
...

Credits

  • Logo generated with DALL·E 3 by @gegabo