https://github.com/moldyn/normi
Generalized Kraskov Estimator for Normalized Mutual Information
https://github.com/moldyn/normi
Last synced: 11 months ago
JSON representation
Generalized Kraskov Estimator for Normalized Mutual Information
- Host: GitHub
- URL: https://github.com/moldyn/normi
- Owner: moldyn
- License: mit
- Created: 2023-06-21T10:01:27.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2024-11-21T17:00:49.000Z (over 1 year ago)
- Last Synced: 2024-11-21T17:40:27.489Z (over 1 year ago)
- Language: Python
- Homepage: https://moldyn.github.io/NorMI
- Size: 2.61 MB
- Stars: 10
- Watchers: 0
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: docs/contributing.md
- License: LICENSE
Awesome Lists containing this project
README
# 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](https://doi.org/10.1063/5.0217960)
If you use this software package, please cite the above mentioned paper.
## Features
- Intuitive usage via [module](#module---inside-a-python-script) and via [CI](#ci---usage-directly-from-the-command-line)
- 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](https://moldyn.github.io/NorMI) and detailed discussion in publication
## Installation
The package is called `normi` and is available via [PyPI](https://pypi.org/project/normi) or [conda](https://anaconda.org/conda-forge/normi). To install it, simply call:
```bash
python3 -m pip install --upgrade normi
```
or
```
conda install -c conda-forge normi
```
or for the latest dev version
```bash
# 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](https://click.palletsprojects.com/en/8.0.x/shell-completion).
In the case of bash you need to add following line to your `~/.bashrc`
```bash
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](https://click.palletsprojects.com).
For a complete list of all options please see the
[docs](https://moldyn.github.io/NorMI/reference/cli/).
```bash
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
```python
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
