infomeasure package

infomeasure package#

Subpackages#

Module contents#

infomeasure package.

class infomeasure.Config[source]#

Bases: object

Configuration settings for the package.

This class provides configuration settings for the package. The settings are stored as class attributes and can be accessed and modified using the class methods.

Default settings:

  • base: “e” (nats)

  • p_value_method: “permutation_test”

Attributes:
_settingsdict

A dictionary containing the configuration settings.

Methods

get(key)

Get the value of a configuration setting.

get_logarithmic_unit()

Get the logarithmic unit for entropy calculations.

get_logarithmic_unit_description()

Get the description of the logarithmic unit for entropy calculations.

reset()

Reset the configuration settings to the default values.

set(key, value)

Set the value of a configuration setting.

set_log_level(level)

Set the logging level for the package.

set_logarithmic_unit(unit)

Set the base for the logarithmic unit.
classmethod get(key: str)[source]#

Get the value of a configuration setting.

Parameters:
keystr

The key of the configuration setting.

Returns:
Any

The value of the configuration setting.

classmethod get_logarithmic_unit() → str[source]#

Get the logarithmic unit for entropy calculations.

Returns:
str

The logarithmic unit.

classmethod get_logarithmic_unit_description() → str[source]#

Get the description of the logarithmic unit for entropy calculations.

Returns:
str

The description of the logarithmic unit.

Raises:
ValueError

If there is no description for the logarithmic unit.

classmethod reset()[source]#

Reset the configuration settings to the default values.

classmethod set(key: str, value)[source]#

Set the value of a configuration setting.

Parameters:
keystr

The key of the configuration setting.

valueAny

The value to set the configuration setting to.

Raises:
KeyError

If the key is not recognized.

TypeError

If the value is not of the correct type.

static set_log_level(level: int | str) → None[source]#

Set the logging level for the package.

Parameters:
levelint | str

The logging level. See the logging module for more information.

Raises:
ValueError

If the level is not a valid logging level.

classmethod set_logarithmic_unit(unit: str)[source]#

Set the base for the logarithmic unit.

The base determines the logarithmic unit used for entropy calculations:

  • ‘bits’ or ‘shannons’ (base 2)

  • ‘nats’ (base e)

  • ‘hartleys’, ‘bans’, or ‘dits’ (base 10)

Alternatively, you can set the base directly using the ‘base’ key, via set().

Parameters:
unitstr

The logarithmic unit to set. Use ‘bit(s)’ or ‘shannon(s)’ for base 2, ‘nat(s)’ for base e, and ‘hartley(s)’, ‘ban(s)’, or ‘dit(s)’ for base 10.

Raises:
ValueError

If the unit is not recognized.

infomeasure.cmi(*data, **kwargs: any)#

Conditional mutual information between two variables given a third variable.

See mutual_information for more information.

infomeasure.conditional_mutual_information(*data, **kwargs: any)[source]#

Conditional mutual information between two variables given a third variable.

See mutual_information for more information.

infomeasure.conditional_transfer_entropy(*data, **kwargs: any)[source]#

Conditional transfer entropy between two variables given a third variable.

See transfer_entropy for more information.

infomeasure.cte(*data, **kwargs: any)#

Conditional transfer entropy between two variables given a third variable.

See transfer_entropy for more information.

infomeasure.entropy(data, approach: str, *args, **kwargs: any)[source]#

Calculate the entropy using a functional interface of different estimators.

Supports the following approaches:

  1. discrete: Discrete entropy estimator.

  2. kernel: Kernel entropy estimator.

  3. [metric, kl]: Kozachenko-Leonenko entropy estimator.

  4. renyi: Renyi entropy estimator.

  5. [ordinal, symbolic, permutation]: Ordinal / Permutation entropy estimator.

  6. tsallis: Tsallis entropy estimator.

Parameters:
dataarray_like

The data used to estimate the entropy.

approachstr

The name of the estimator to use.

*args: tuple

Additional arguments to pass to the estimator.

**kwargs: dict

Additional keyword arguments to pass to the estimator.

Returns:
float

The calculated entropy.

Raises:
ValueError

If the estimator is not recognized.

infomeasure.estimator(*data, cond=None, measure: str = None, approach: str = None, step_size: int = 1, prop_time: int = 0, src_hist_len: int = 1, dest_hist_len: int = 1, cond_hist_len: int = 1, **kwargs: any) → EstimatorType[source]#

Get an estimator for a specific measure.

This function provides a simple interface to get an Estimator for a specific measure.

If you are only interested in the global result, use the functional interfaces:

Estimators available:

  1. Entropy:
  2. Mutual Information:
  3. Transfer Entropy:
Parameters:
*data

The data used to estimate the measure. For entropy: a single array-like data. A tuple of data for joint entropy. For mutual information: arbitrary number of array-like data. For transfer entropy: two array-like data. Source and destination.

condarray_like, optional

Only if the measure is conditional transfer entropy.

measurestr

The measure to estimate. Options: entropy, mutual_information, transfer_entropy, conditional_mutual_information conditional_transfer_entropy; aliases: h, mi, te, cmi, cte.

approachstr

The name of the estimator to use. Find the available estimators in the docstring of this function.

*args: tuple

Additional arguments to pass to the estimator.

**kwargs: dict

Additional keyword arguments to pass to the estimator.

Returns:
Estimator

The estimator instance.

Raises:
ValueError

If the measure is not recognized.

infomeasure.get_estimator_class(measure=None, approach=None) → EstimatorType[source]#

Get estimator class based on the estimator name and approach.

This function returns the estimator class based on the measure and approach provided. If you want an instance of an estimator, initialized with data and parameters, use the functional interface estimator().

Parameters:
measurestr

The measure to estimate. Options: entropy, mutual_information, transfer_entropy, conditional_mutual_information, conditional_transfer_entropy. Aliases: h, mi, te, cmi, cte.

approachstr

The name of the estimator to use.

Returns:
class

The estimator class.

Raises:
ValueError

If the measure is not recognized.

ValueError

If the approach is not recognized.

infomeasure.h(data, approach: str, *args, **kwargs: any)#

Calculate the entropy using a functional interface of different estimators.

Supports the following approaches:

  1. discrete: Discrete entropy estimator.

  2. kernel: Kernel entropy estimator.

  3. [metric, kl]: Kozachenko-Leonenko entropy estimator.

  4. renyi: Renyi entropy estimator.

  5. [ordinal, symbolic, permutation]: Ordinal / Permutation entropy estimator.

  6. tsallis: Tsallis entropy estimator.

Parameters:
dataarray_like

The data used to estimate the entropy.

approachstr

The name of the estimator to use.

*args: tuple

Additional arguments to pass to the estimator.

**kwargs: dict

Additional keyword arguments to pass to the estimator.

Returns:
float

The calculated entropy.

Raises:
ValueError

If the estimator is not recognized.

infomeasure.jensen_shannon_divergence(*data, approach: str | None = None, **kwargs)[source]#

Calculate the Jensen-Shannon Divergence between two or more distributions.

The Jensen-Shannon Divergence is a symmetrized and smoothed version of the Kullback-Leibler Divergence. It is calculated as the average of the Kullback-Leibler Divergence between each distribution and the average distribution.

\[JSD(P \| Q) = \frac{1}{2} KL(P \| M) + \frac{1}{2} KL(Q \| M)\]

where \(M = \frac{1}{2} (P + Q)\).

Parameters:
parray_like

The first data.

qarray_like

The second data.

…array_like

Further data to compare.

approachstr

The name of the entropy estimator to use.

**kwargsdict

Additional keyword arguments to pass to the entropy estimator.

Returns:
float

The Jensen-Shannon Divergence.

Raises:
ValueError

If the approach is not supported or the entropy estimator is not compatible with the Jensen-Shannon Divergence.

ValueError

If any of the given data is not an array-like object.

infomeasure.jsd(*data, approach: str | None = None, **kwargs)#

Calculate the Jensen-Shannon Divergence between two or more distributions.

The Jensen-Shannon Divergence is a symmetrized and smoothed version of the Kullback-Leibler Divergence. It is calculated as the average of the Kullback-Leibler Divergence between each distribution and the average distribution.

\[JSD(P \| Q) = \frac{1}{2} KL(P \| M) + \frac{1}{2} KL(Q \| M)\]

where \(M = \frac{1}{2} (P + Q)\).

Parameters:
parray_like

The first data.

qarray_like

The second data.

…array_like

Further data to compare.

approachstr

The name of the entropy estimator to use.

**kwargsdict

Additional keyword arguments to pass to the entropy estimator.

Returns:
float

The Jensen-Shannon Divergence.

Raises:
ValueError

If the approach is not supported or the entropy estimator is not compatible with the Jensen-Shannon Divergence.

ValueError

If any of the given data is not an array-like object.

infomeasure.kld(data_p, data_q, approach: str = '', **kwargs)#

Calculate the Kullback-Leibler Divergence between two distributions.

The Kullback-Leibler Divergence is a measure of the difference between two probability distributions. It is calculated as the expectation of the logarithm of the ratio of the probability of two events. To calculate, we use the identity of combining the joint and marginal entropies:

\[KL(P \| Q) = \sum_{x \in X} P(x) \log \left( \frac{P(x)}{Q(x)} \right) = H(P, Q) - H(P)\]
Parameters:
data_parray_like

The first data.

data_qarray_like

The second data.

approachstr

The name of the entropy estimator to use.

**kwargsdict

Additional keyword arguments to pass to the entropy estimator.

Returns:
float

The Kullback-Leibler Divergence.

Raises:
ValueError

If the approach is not supported or the entropy estimator is not compatible with the Kullback-Leibler Divergence.

infomeasure.kullback_leiber_divergence(data_p, data_q, approach: str = '', **kwargs)[source]#

Calculate the Kullback-Leibler Divergence between two distributions.

The Kullback-Leibler Divergence is a measure of the difference between two probability distributions. It is calculated as the expectation of the logarithm of the ratio of the probability of two events. To calculate, we use the identity of combining the joint and marginal entropies:

\[KL(P \| Q) = \sum_{x \in X} P(x) \log \left( \frac{P(x)}{Q(x)} \right) = H(P, Q) - H(P)\]
Parameters:
data_parray_like

The first data.

data_qarray_like

The second data.

approachstr

The name of the entropy estimator to use.

**kwargsdict

Additional keyword arguments to pass to the entropy estimator.

Returns:
float

The Kullback-Leibler Divergence.

Raises:
ValueError

If the approach is not supported or the entropy estimator is not compatible with the Kullback-Leibler Divergence.

infomeasure.mi(*data, approach: str, **kwargs: any)#

Calculate the mutual information using a functional interface of different estimators.

Supports the following approaches:

  1. discrete: Discrete mutual information estimator.

  2. kernel: Kernel mutual information estimator.

  3. [metric, ksg]: Kraskov-Stoegbauer-Grassberger mutual information estimator.

  4. renyi: Renyi mutual information estimator.

  5. [ordinal, symbolic, permutation]: Ordinal mutual information estimator.

  6. tsallis: Tsallis mutual information estimator.

Parameters:
*dataarray_like

The data used to estimate the (conditional) mutual information.

condarray_like, optional

The conditional data used to estimate the conditional mutual information.

approachstr

The name of the estimator to use.

normalizebool, optional

If True, normalize the data before analysis. Default is False. Not available for the discrete estimator.

**kwargs: dict

Additional keyword arguments to pass to the estimator.

Returns:
float

The calculated mutual information.

Raises:
ValueError

If the estimator is not recognized.

infomeasure.mutual_information(*data, approach: str, **kwargs: any)[source]#

Calculate the mutual information using a functional interface of different estimators.

Supports the following approaches:

  1. discrete: Discrete mutual information estimator.

  2. kernel: Kernel mutual information estimator.

  3. [metric, ksg]: Kraskov-Stoegbauer-Grassberger mutual information estimator.

  4. renyi: Renyi mutual information estimator.

  5. [ordinal, symbolic, permutation]: Ordinal mutual information estimator.

  6. tsallis: Tsallis mutual information estimator.

Parameters:
*dataarray_like

The data used to estimate the (conditional) mutual information.

condarray_like, optional

The conditional data used to estimate the conditional mutual information.

approachstr

The name of the estimator to use.

normalizebool, optional

If True, normalize the data before analysis. Default is False. Not available for the discrete estimator.

**kwargs: dict

Additional keyword arguments to pass to the estimator.

Returns:
float

The calculated mutual information.

Raises:
ValueError

If the estimator is not recognized.

infomeasure.te(*data, approach: str, **kwargs: any)#

Calculate the transfer entropy using a functional interface of different estimators.

Supports the following approaches:

  1. discrete: Discrete transfer entropy estimator.

  2. kernel: Kernel transfer entropy estimator.

  3. [metric, ksg]: Kraskov-Stoegbauer-Grassberger transfer entropy estimator.

  4. renyi: Renyi transfer entropy estimator.

  5. [ordinal, symbolic, permutation]: Ordinal transfer entropy estimator.

  6. tsallis: Tsallis transfer entropy estimator.

Parameters:
source, destarray_like

The source (X) and destination (Y) data used to estimate the transfer entropy.

condarray_like, optional

The conditional data used to estimate the conditional transfer entropy.

approachstr

The name of the estimator to use.

step_sizeint

Step size between elements for the state space reconstruction.

src_hist_len, dest_hist_lenint

Number of past observations to consider for the source and destination data.

prop_timeint, optional

Number of positions to shift the data arrays relative to each other. Delay/lag/shift between the variables. Default is no shift. Assumed time taken by info to transfer from source to destination. Not compatible with the cond parameter / conditional TE. Alternatively called offset.

*args: tuple

Additional arguments to pass to the estimator.

**kwargs: dict

Additional keyword arguments to pass to the estimator.

Returns:
float

The calculated transfer entropy.

Raises:
ValueError

If the estimator is not recognized.

infomeasure.transfer_entropy(*data, approach: str, **kwargs: any)[source]#

Calculate the transfer entropy using a functional interface of different estimators.

Supports the following approaches:

  1. discrete: Discrete transfer entropy estimator.

  2. kernel: Kernel transfer entropy estimator.

  3. [metric, ksg]: Kraskov-Stoegbauer-Grassberger transfer entropy estimator.

  4. renyi: Renyi transfer entropy estimator.

  5. [ordinal, symbolic, permutation]: Ordinal transfer entropy estimator.

  6. tsallis: Tsallis transfer entropy estimator.

Parameters:
source, destarray_like

The source (X) and destination (Y) data used to estimate the transfer entropy.

condarray_like, optional

The conditional data used to estimate the conditional transfer entropy.

approachstr

The name of the estimator to use.

step_sizeint

Step size between elements for the state space reconstruction.

src_hist_len, dest_hist_lenint

Number of past observations to consider for the source and destination data.

prop_timeint, optional

Number of positions to shift the data arrays relative to each other. Delay/lag/shift between the variables. Default is no shift. Assumed time taken by info to transfer from source to destination. Not compatible with the cond parameter / conditional TE. Alternatively called offset.

*args: tuple

Additional arguments to pass to the estimator.

**kwargs: dict

Additional keyword arguments to pass to the estimator.

Returns:
float

The calculated transfer entropy.

Raises:
ValueError

If the estimator is not recognized.

Contents