Settings

Settings#

The package configuration can be done using the im.Config module. This will set the default values for the running kernel.

import infomeasure as im
import numpy as np
rng = np.random.default_rng()

Permanently changing the logarithmic base#

The default logarithmic base for the information measures is \(e\), ergo, results are in the natural unit of information. You can change this by using the im.Config.set_logarithmic_unit() function or directly setting the base.

# To find out the current logarithmic unit and it's description
im.Config.get_logarithmic_unit(), im.Config.get_logarithmic_unit_description()

('nat/nit/nepit',
 'This base is best suited for continuous probability distributions.')

im.Config.set_logarithmic_unit("bits")  #  / "shannons"
# equivalent to
im.Config.set("base", 2)  # int | float

im.Config.set_logarithmic_unit("nats")
# equivalent to
im.Config.set("base", "e")  # special value

im.Config.set_logarithmic_unit("hartleys")  # / "bans" / "dits"
# equivalent to
im.Config.set("base", 10)  # int | float

Any calculation after this will use the new base. Only in the case of restarting the kernel, the base will be reset to the default value. When using multiple bases it is recommended to directly pass the base argument to the estimator functions, like so:

im.entropy([1, 0, 1, 0], approach="discrete", base='e'), \
  im.entropy([1, 0, 1, 0], approach="discrete", base=2)

(np.float64(0.6931471805599453), np.float64(1.0))

Statistical Testing Configuration#

The package provides comprehensive statistical testing capabilities through the statistical_test() method. This method returns a StatisticalTestResult object containing p-values, t-scores, and additional metadata.

Statistical Test Methods#

Two statistical test methods are available:

  • Permutation test (default): Uses permuted data to generate null distribution

  • Bootstrap test: Uses resampled data with repetition

The choice depends on your data characteristics and sample size. You can set the default method globally:

im.Config.set("statistical_test_method", "permutation_test")  # or "bootstrap"
im.Config.get("statistical_test_method")

'permutation_test'

Default Number of Tests#

You can configure the default number of statistical tests performed:

im.Config.set("statistical_test_n_tests", 200)  # default number of tests
im.Config.get("statistical_test_n_tests")

200

Using Statistical Tests#

The statistical testing functionality provides comprehensive results in a single method call:

a = rng.integers(0, 2, size=1000)
est = im.estimator(a, np.roll(a, -1), measure="te", approach="discrete")

# Use configuration set by the Config
result_config = est.statistical_test()
print(f"Default: p-value = {result_config.p_value:.4f}, t-score = {result_config.t_score:.4f}")

# Override global settings
result_permutation = est.statistical_test(n_tests=50, method="permutation_test")
print(f"Permutation: p-value = {result_permutation.p_value:.4f}, t-score = {result_permutation.t_score:.4f}")

# Access additional information
print(f"Method used: {result_config.method}")
print(f"Number of tests: {result_config.n_tests}")
print(f"Observed value: {result_config.observed_value:.4f}")

Default: p-value = 0.3950, t-score = -0.0397
Permutation: p-value = 0.3400, t-score = -0.0120
Method used: permutation_test
Number of tests: 200
Observed value: 0.0004

Statistical Test Results#

The StatisticalTestResult object provides rich information:

# Calculate confidence intervals
ci_95 = result_config.confidence_interval(0.95)
print(f"95% Confidence Interval: [{ci_95[0]:.4f}, {ci_95[1]:.4f}]")

# Access percentiles of the test distribution
median = result_config.percentile(50)
print(f"Median of null distribution: {median:.4f}")

# Access all test values for custom analysis
test_values = result_config.test_values
print(f"Number of test values: {len(test_values)}")

95% Confidence Interval: [0.0003, 0.0003]
Median of null distribution: 0.0003
Number of test values: 200

Logging#

The package uses the Python logging library for logging purposes. By default, a logger called “infomeasure” is set up with a NullHandler to avoid any unintended logging output. You can configure the logging settings to suit your needs.

You can change the logging level using the im.Config.set_log_level() function. This allows you to control the verbosity of the logging output. Debug logs will show the progress of the computation.

im.Config.set_log_level("DEBUG")  # / "INFO" / "WARNING" / "ERROR" / "CRITICAL"

The logging level can be set to one of the standard logging levels provided by the logging module. This allows you to control the verbosity of the logging output and filter out less important messages. If you want to further customize the logging behaviour, you can access the logger directly and configure it as needed.

import logging
logger = logging.getLogger("infomeasure")
logger.getEffectiveLevel()

10