Getting Started

Getting Started#

This package can be installed from PyPI using pip:

pip install infomeasure

This will automatically install all the necessary dependencies as specified in the pyproject.toml file. It is recommended to use a virtual environment, e.g., using conda, mamba or micromamba (they can be used interchangeably). infomeasure can be installed from the conda-forge channel.

conda create -n im_env -c conda-forge python
conda activate im_env
conda install -c conda-forge infomeasure

Usage#

For a more complete introduction, find the Reference Guide with the theoretical introduction, and for a quick start on how to use the estimators, find the Estimator Usage section. The most common functions are exposed in the top-level namespace, e.g. entropy() or estimator(). For example:

import infomeasure as im

data = [0, 1, 0, 1, 0, 1, 0, 1]
entropy = im.entropy(data, approach="kernel", bandwidth=3, kernel="box")
# or
est = im.estimator(data, measure="entropy", approach="kernel", bandwidth=3, kernel="box")
print(f"Entropy with im.entropy   = {entropy}")
print(f"Entropy with im.estimator = {est.result()}")

Entropy with im.entropy   = 1.0986122886681098
Entropy with im.estimator = 1.0986122886681098

For mutual information, there is a similar function:

data_x = [0, 1, 0, 1, 0, 1, 0, 1]
data_y = [0, 1, 0, 1, 0, 0, 0, 0]
mi = im.mutual_information(data_x, data_y, approach="discrete")
# or
est = im.estimator(data_x, data_y, measure="mutual_information",
                   approach="discrete", prop_time=1)
print(f"Mutual Information with im.mutual_information = {mi}")
print(f"Mutual Information with im.estimator          = {est.result()}")
result = est.statistical_test(n_tests=10)
print(f"p-value = {result.p_value}, p-score = {result.t_score}")

Mutual Information with im.mutual_information = 0.21576155433883548
Mutual Information with im.estimator          = 0.21576155433883548
p-value = 0.0, p-score = 1.449137674618944

Transfer entropy can be calculated as follows:

source = [0.0, 0.3, 0.5, 1.2, 0.0, 0.4, 0.2, -0.6, -0.8, -0.4]
dest = [0.0, 0.8, -0.7, 0.2, 1.2, 1.0, 1.3, 0.7, 0.8, -0.1]
te = im.transfer_entropy(source, dest, approach="metric", noise_level=0.001)
# or
est = im.estimator(source, dest, measure="transfer_entropy", approach="metric", noise_level=0.001)
#te, (est.result(), est.statistical_test(10).p_value, est.statistical_test(10).t_score)
print(f"Transfer Entropy with im.transfer_entropy = {te}")
print(f"Transfer Entropy with im.estimator        = {est.result()} (differs due to noise)")
result = est.statistical_test(n_tests=10)
print(f"p-value = {result.p_value}, p-score = {result.t_score}")

Transfer Entropy with im.transfer_entropy = 0.007804232804232776
Transfer Entropy with im.estimator        = 0.04484126984126978 (differs due to noise)
p-value = 0.5, p-score = 0.18144310656438453

In Estimator Usage, you can find more information on how to use the estimators, specific functions, p-value estimation and which approaches are available.

For more insight into the package, read the Reference Guide or the API Reference.

Set up Jupyter kernel#

If you want to use infomeasure with its environment im_env in Jupyter, run:

pip install --user ipykernel
python -m ipykernel install --user --name=im_env

This allows you to run Jupyter with the kernel im_env (Kernel > Change Kernel > im_env)

Development Setup#

For development, we recommend using micromamba to create a virtual environment (conda or mamba also work) and installing the package in editable mode. After cloning the repository, navigate to the root folder and create the environment with the desired python version and the dependencies.

micromamba create -n im_env -c conda-forge python
micromamba activate im_env

To let micromamba handle the dependencies, use the requirements files

micromamba install -f requirements/build_requirements.txt \
  -f requirements/linter_requirements.txt \
  -f requirements/test_requirements.txt \
  -f requirements/doc_requirements.txt
pip install --no-build-isolation --no-deps -e .

Alternatively, if you prefer to use pip, installing the package in editable mode will also install the development dependencies.

pip install -e ".[all]"

Now, the package can be imported and used in the python environment, from anywhere on the system, if the environment is activated. For new changes, the repository only needs to be updated, but the package does not need to be reinstalled.

Contents