infomeasure.utils package

infomeasure.utils package#

Submodules#

infomeasure.utils.config module#

Utility module for configuration settings.

class infomeasure.utils.config.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)

  • statistical_test_method: “permutation_test”

  • statistical_test_n_tests: 200

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 recognised.

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 recognised.

infomeasure.utils.data module#

Data structures and containers for the infomeasure package.

class infomeasure.utils.data.DiscreteData(uniq: ndarray, counts: ndarray, data: ndarray = None)[source]#

Bases: object

Container for discrete random variable data.

Attributes:
uniqndarray

Array of unique values in the discrete data.

countsndarray

Array of counts for each unique value.

datandarray, optional

Original data array. Defaults to None.

Nint, optional

Total number of samples (length of data). Defaults to None.

Kint, optional

Number of unique values (len(uniq)). Defaults to None.

Methods

from_counts(uniq, counts)

Constructs a DiscreteData instance from unique values and their counts.

from_data(data)

Create a DiscreteData object from a data array.
K: int = <dataclasses._MISSING_TYPE object>#
N: int = <dataclasses._MISSING_TYPE object>#
counts: ndarray = <dataclasses._MISSING_TYPE object>#
data: ndarray = None#
property distribution_dict: dict#

Dictionary mapping unique elements to their corresponding probabilities.

Returns:
dict

A dictionary where keys are unique elements and values are their corresponding probabilities.

classmethod from_counts(uniq: ndarray, counts: ndarray) → DiscreteData[source]#

Constructs a DiscreteData instance from unique values and their counts.

This class method creates an instance of the DiscreteData class by specifying the unique values and their corresponding counts. The data attribute of the created instance is set to None.

Parameters:
uniqndarray

An array of unique values.

countsndarray

An array of counts corresponding to the unique values.

Returns:
DiscreteData

A new instance of the DiscreteData class initialized with the given unique values and their counts.

classmethod from_data(data: ndarray) → DiscreteData[source]#

Create a DiscreteData object from a data array.

Parameters:
datandarray

Raw data array to analyse.

Returns:
DiscreteData

New instance with computed unique values and counts.

property probabilities: ndarray#

Computes and returns the probabilities by normalizing counts.

The probabilities property calculates the probabilities as the ratio of counts to the total value N. This provides a normalized representation of counts as probabilities.

Returns:
ndarray

An array containing the probabilities, calculated by dividing counts by N.

uniq: ndarray = <dataclasses._MISSING_TYPE object>#
class infomeasure.utils.data.StatisticalTestResult(p_value: float, t_score: float, test_values: ndarray, observed_value: float, null_mean: float, null_std: float, n_tests: int, method: str)[source]#

Bases: object

Comprehensive statistical test result containing p-value, t-score, and confidence intervals.

Attributes:
p_valuefloat

The p-value of the statistical test.

t_scorefloat

The t-score (standardized test statistic).

test_valuesndarray

The test values from permutation/bootstrap sampling.

observed_valuefloat

The observed value being tested.

null_meanfloat

Mean of the null distribution (test values).

null_stdfloat

Standard deviation of the null distribution.

n_testsint

Number of tests performed (permutations or bootstrap samples).

methodstr

The statistical test method used (“permutation_test” or “bootstrap”).

Methods

confidence_interval(confidence_level[, method])

Get confidence interval for the specified confidence level.

percentile(q[, method])

Compute the q-th percentile of the test values.
confidence_interval(confidence_level, method='linear')[source]#

Get confidence interval for the specified confidence level.

This is a convenience function that converts a confidence level (e.g., 95 for 95% CI) to the appropriate percentile calls.

Parameters:
confidence_levelfloat

Confidence level as a percentage (e.g., 95 for 95% CI). Must be between 0 and 100.

methodstr, optional

Method to use for estimating the percentile. Default is “linear”. See numpy.percentile() for available methods.

Returns:
ndarray

Array containing [lower_bound, upper_bound] of the confidence interval.

Raises:
ValueError

If confidence_level is not between 0 and 100.

Examples

>>> result = estimator.statistical_test(n_tests=100)
>>> result.confidence_interval(95)  # 95% CI
>>> result.confidence_interval(90, method="nearest")  # 90% CI with nearest method
method: str = <dataclasses._MISSING_TYPE object>#
n_tests: int = <dataclasses._MISSING_TYPE object>#
null_mean: float = <dataclasses._MISSING_TYPE object>#
null_std: float = <dataclasses._MISSING_TYPE object>#
observed_value: float = <dataclasses._MISSING_TYPE object>#
p_value: float = <dataclasses._MISSING_TYPE object>#
percentile(q, method='linear')[source]#

Compute the q-th percentile of the test values.

This method wraps numpy’s percentile function to compute percentiles of the test values from the statistical test.

Parameters:
qarray_like of float

Percentage or sequence of percentages for the percentiles to compute. Values must be between 0 and 100 inclusive.

methodstr, optional

Method to use for estimating the percentile. Default is “linear”. See numpy.percentile() for available methods.

Returns:
percentilescalar or ndarray

If q is a single percentile, returns a scalar. If multiple percentiles are given, returns an array.

See also

numpy.percentile

Compute percentiles along specified axes.

Notes

For details on the method parameter, reference numpy.percentile().

Examples

>>> result = estimator.statistical_test(n_tests=100,method="permutation_test")
>>> result.percentile(50)  # Median
>>> result.percentile([25, 75])  # Quartiles
>>> result.percentile(95, method="nearest")  # 95th percentile with nearest method
t_score: float = <dataclasses._MISSING_TYPE object>#
test_values: ndarray = <dataclasses._MISSING_TYPE object>#

infomeasure.utils.exceptions module#

Custom exceptions for the infomeasure package.

exception infomeasure.utils.exceptions.TheoreticalInconsistencyError[source]#

Bases: Exception

Exception raised when a method cannot be implemented due to theoretical inconsistencies.

This exception is used for cases where the mathematical or theoretical foundation of a method makes it inappropriate or impossible to implement in a meaningful way. Examples include cross-entropy for estimators that mix bias corrections from different distributions, or methods that violate fundamental assumptions.

This is different from NotImplementedError, which indicates that implementation is planned but not yet done. TheoreticalInconsistencyError indicates that implementation is not theoretically sound or appropriate.

infomeasure.utils.types module#

Type definitions for the infomeasure package.

Module contents#

Utility functions for infomeasure.

class infomeasure.utils.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)

  • statistical_test_method: “permutation_test”

  • statistical_test_n_tests: 200

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 recognised.

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 recognised.