### Development setup with pip

Source: https://github.com/cbueth/infomeasure/blob/main/README.md

Install the package in editable mode using pip, which also installs development dependencies.

```bash
pip install -e ".[all]"
```

--------------------------------

### Development setup with micromamba

Source: https://github.com/cbueth/infomeasure/blob/main/README.md

Set up a development environment using micromamba, install build and test dependencies, and install the package in editable mode.

```bash
micromamba create -n im_env -c conda-forge python
```

```bash
micromamba activate im_env
```

```bash
micromamba install -f requirements/build_requirements.txt \
  -f requirements/linter_requirements.txt \
  -f requirements/test_requirements.txt \
  -f requirements/doc_requirements.txt
```

```bash
pip install --no-build-isolation --no-deps -e .
```

--------------------------------

### Progress Bar Output Example

Source: https://github.com/cbueth/infomeasure/blob/main/docs/demos/Time_Performance.ipynb

This is an example of the progress bar output during the benchmarking process, showing the current key being processed and the progress percentage.

```text
Output:\nkey: kernel(gaussian) ||######                        | |  22% (ETA:   0:37:02)
```

--------------------------------

### Install infomeasure using pip

Source: https://github.com/cbueth/infomeasure/blob/main/README.md

Install the infomeasure package from PyPI using pip. This command automatically handles dependency installation.

```bash
pip install infomeasure
```

--------------------------------

### Set up Development Environment

Source: https://github.com/cbueth/infomeasure/blob/main/CONTRIBUTING.md

Installs development dependencies and the package in editable mode for local development. Activate the created conda environment before running pip install.

```bash
conda create -n im_env -c conda-forge python -f requirements/build_requirements.txt \
  -f requirements/linter_requirements.txt \
  -f requirements/test_requirements.txt \
  -f requirements/doc_requirements.txt \
  -f requirements/packaging_requirements.txt
conda activate im_env
pip install --no-build-isolation --no-deps -e .
```

--------------------------------

### Install infomeasure using conda

Source: https://github.com/cbueth/infomeasure/blob/main/README.md

Install infomeasure from the conda-forge channel. It's recommended to use a virtual environment like conda or mamba.

```bash
conda create -n im_env -c conda-forge python
```

```bash
conda activate im_env
```

```bash
conda install -c conda-forge infomeasure
```

--------------------------------

### Set up Jupyter kernel for infomeasure environment

Source: https://github.com/cbueth/infomeasure/blob/main/README.md

Install ipykernel and register the 'im_env' environment as a Jupyter kernel. This allows using the infomeasure environment within Jupyter notebooks.

```bash
pip install --user ipykernel
```

```bash
python -m ipykernel install --user --name=im_env
```

--------------------------------

### Benchmark Transfer Entropy Computation Setup

Source: https://github.com/cbueth/infomeasure/blob/main/docs/demos/Time_Performance.ipynb

Initializes the benchmark parameters for Transfer Entropy (TE) computation, analogous to entropy and mutual information. Sets the maximum benchmark time and total number of keys to process.

```python
benchmark_max_time = 600
total_keys = len(combinations)
```

--------------------------------

### Get Estimator Instance and Local Values

Source: https://github.com/cbueth/infomeasure/blob/main/docs/guide/entropy/kernel.md

Instantiate a kernel entropy estimator and retrieve both the overall result and the local entropy values for each data point.

```python
est = im.estimator(data, measure="h", approach="kernel", kernel="box", bandwidth=0.5)
est.result(), est.local_vals()
```

--------------------------------

### Time Limit Exceeded Message Example

Source: https://github.com/cbueth/infomeasure/blob/main/docs/demos/Time_Performance.ipynb

This message is displayed when the benchmarking process for a specific approach and dataset index exceeds the predefined `benchmark_max_time`.

```text
Output:\nTime limit exceeded for kernel(box) at index 18
```

--------------------------------

### Calculate Ordinal Entropy, MI, and TE

Source: https://github.com/cbueth/infomeasure/blob/main/docs/guide/estimator_selection.md

Demonstrates how to calculate ordinal entropy, mutual information, and transfer entropy using sample time series data. Ensure the 'infomeasure' library is installed and time series data is provided.

```python
import infomeasure as im
import numpy as np

# Example time series data
np.random.seed(666)
time_series = np.random.normal(0, 1, 1000)

# Ordinal entropy with embedding dimension 3
entropy_ordinal = im.entropy(time_series, approach="ordinal", embedding_dim=3)
print(f"Ordinal Entropy: {entropy_ordinal:.4f}")

# Ordinal mutual information between two time series
time_series_2 = np.random.normal(0, 1, 1000)
mi_ordinal = im.mutual_information(time_series, time_series_2, approach="ordinal", embedding_dim=3)
print(f"Ordinal MI: {mi_ordinal:.4f}")

# Ordinal transfer entropy for causal analysis
te_ordinal = im.transfer_entropy(time_series, time_series_2, approach="ordinal", embedding_dim=3)
print(f"Ordinal TE: {te_ordinal:.4f}")
```

--------------------------------

### Initialize infomeasure and plotting

Source: https://github.com/cbueth/infomeasure/blob/main/docs/demos/Schreiber_Article.ipynb

Sets up the infomeasure library for bit-based logarithmic units and imports necessary libraries for numerical operations and plotting.

```python
import infomeasure as im
import numpy as np
import matplotlib.pyplot as plt

im.Config.set_logarithmic_unit("bits")
```

--------------------------------

### GET /api/transfer_entropy/effective_val

Source: https://github.com/cbueth/infomeasure/blob/main/docs/guide/estimator_usage.md

Retrieves the effective Transfer Entropy value.

```APIDOC
## GET /api/transfer_entropy/effective_val

### Description
Retrieves the effective Transfer Entropy value. This represents the minimal information required to reproduce the observed dynamics and is calculated using the `effective_val` method.

### Method
GET

### Endpoint
`/api/transfer_entropy/effective_val`

### Query Parameters
- **estimator_type** (string) - Required - The type of Transfer Entropy estimator to use.
- **dataset_id** (string) - Required - The identifier for the dataset.

### Response
#### Success Response (200)
- **effective_value** (float) - The calculated effective Transfer Entropy value.

#### Response Example
```json
{
  "effective_value": 0.65
}
```
```

--------------------------------

### GET /api/transfer_entropy/statistical_test

Source: https://github.com/cbueth/infomeasure/blob/main/docs/guide/estimator_usage.md

Performs statistical tests on Transfer Entropy estimates.

```APIDOC
## GET /api/transfer_entropy/statistical_test

### Description
Performs comprehensive statistical tests on the Transfer Entropy estimates. This endpoint returns metrics such as p-value, t-score, and confidence intervals to assess the significance of the estimated TE.

### Method
GET

### Endpoint
`/api/transfer_entropy/statistical_test`

### Query Parameters
- **estimator_type** (string) - Required - The type of Transfer Entropy estimator to use.
- **dataset_id** (string) - Required - The identifier for the dataset.
- **significance_level** (float) - Optional - The significance level for the statistical tests (default: 0.05).

### Response
#### Success Response (200)
- **p_value** (float) - The p-value from the statistical test.
- **t_score** (float) - The t-score from the statistical test.
- **confidence_interval** (object) - An object containing the lower and upper bounds of the confidence interval.
  - **lower_bound** (float)
  - **upper_bound** (float)

#### Response Example
```json
{
  "p_value": 0.01,
  "t_score": 2.58,
  "confidence_interval": {
    "lower_bound": 0.2,
    "upper_bound": 0.9
  }
}
```
```

--------------------------------

### GET /api/transfer_entropy/local_vals

Source: https://github.com/cbueth/infomeasure/blob/main/docs/guide/estimator_usage.md

Retrieves the local Transfer Entropy values for a specified estimator and dataset.

```APIDOC
## GET /api/transfer_entropy/local_vals

### Description
Retrieves the local Transfer Entropy values calculated by a specified estimator. This provides a time-series or element-wise breakdown of the information flow.

### Method
GET

### Endpoint
`/api/transfer_entropy/local_vals`

### Query Parameters
- **estimator_type** (string) - Required - The type of Transfer Entropy estimator to use (e.g., 'discrete', 'kernel', 'ksg').
- **dataset_id** (string) - Required - The identifier for the dataset to be used for calculation.

### Response
#### Success Response (200)
- **local_values** (array of floats) - An array containing the local Transfer Entropy values.

#### Response Example
```json
{
  "local_values": [0.1, 0.5, 0.8, 0.3]
}
```
```

--------------------------------

### Calculate entropy with different bases

Source: https://github.com/cbueth/infomeasure/blob/main/docs/guide/settings.md

Demonstrates how to calculate entropy using different logarithmic bases by passing the 'base' argument directly to the estimator function. This is recommended when using multiple bases.

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

--------------------------------

### GET /api/transfer_entropy/result

Source: https://github.com/cbueth/infomeasure/blob/main/docs/guide/estimator_usage.md

Retrieves the global Transfer Entropy value for a specified estimator and dataset.

```APIDOC
## GET /api/transfer_entropy/result

### Description
Retrieves the global Transfer Entropy value calculated by a specified estimator. This endpoint is useful for obtaining a single, aggregated measure of information flow between two variables.

### Method
GET

### Endpoint
`/api/transfer_entropy/result`

### Query Parameters
- **estimator_type** (string) - Required - The type of Transfer Entropy estimator to use (e.g., 'discrete', 'kernel', 'ksg').
- **dataset_id** (string) - Required - The identifier for the dataset to be used for calculation.

### Response
#### Success Response (200)
- **global_value** (float) - The calculated global Transfer Entropy value.

#### Response Example
```json
{
  "global_value": 0.75
}
```
```

--------------------------------

### Instantiate KL Entropy Estimator and Access Local Values

Source: https://github.com/cbueth/infomeasure/blob/main/docs/guide/entropy/kozachenko_leonenko.md

Create an instance of the Kozachenko-Leonenko entropy estimator to access both the overall result and local entropy values for each data point. This requires the `infomeasure` library.

```python
est = im.estimator(data, measure="h", approach="metric", k=4)
est.result(), est.local_vals()
```

--------------------------------

### Get Effective Transfer Entropy Value

Source: https://github.com/cbueth/infomeasure/blob/main/docs/guide/transfer_entropy/kernel.md

Calculates the effective transfer entropy value from an estimator instance.

```python
est.effective_val()
```

--------------------------------

### Get Local Transfer Entropy Values

Source: https://github.com/cbueth/infomeasure/blob/main/docs/guide/transfer_entropy/kernel.md

Retrieves the local transfer entropy values from a pre-initialized estimator object.

```python
est.local_vals()
```

--------------------------------

### Run All Tests

Source: https://github.com/cbueth/infomeasure/blob/main/CONTRIBUTING.md

Executes all tests in the project to verify code changes. Ensure your development environment is set up and activated.

```bash
pytest tests/
```

--------------------------------

### Compare Multiple Entropy Estimators

Source: https://github.com/cbueth/infomeasure/blob/main/docs/guide/entropy/discrete.md

Compares the results of various entropy estimators on the same dataset. Ensure the 'estimators' list contains the desired approach names.

```python
estimators = ["discrete", "miller_madow", "grassberger", "shrink", "chao_shen", "nsb"]
results = {}

for estimator in estimators:
    result = im.entropy(data_small, approach=estimator, base=2)
    results[estimator] = result
    print(f"{estimator:15}: {result:.4f} bits")
```

--------------------------------

### Get current logarithmic unit

Source: https://github.com/cbueth/infomeasure/blob/main/docs/guide/settings.md

Retrieve the current logarithmic unit and its description to understand the default or currently set base.

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

--------------------------------

### Calculate Transfer Entropy with History and Lag

Source: https://context7.com/cbueth/infomeasure/llms.txt

Demonstrates calculating transfer entropy using the 'metric' approach, specifying history lengths for source and destination, and step size. Also shows how to incorporate propagation time (lag).

```python
te_history = im.transfer_entropy(
    source, dest,
    approach="metric",
    src_hist_len=2,    # Consider 2 past values of source
    dest_hist_len=2,   # Consider 2 past values of destination
    step_size=1,       # Step between consecutive observations
    prop_time=0,       # Propagation time/lag
    k=4,
    noise_level=1e-8
)
print(f"TE with history: {te_history:.4f}")
```

```python
# With propagation time (lag between source and destination)
te_lagged = im.transfer_entropy(source, dest, approach="metric", prop_time=1, k=4, noise_level=1e-8)
print(f"TE with prop_time=1: {te_lagged:.4f}")
```

```python
# Shorthand
te_short = im.te(source, dest, approach="discrete")
```

--------------------------------

### Configure InfoMeasure Settings

Source: https://context7.com/cbueth/infomeasure/llms.txt

Manages global settings for logarithmic units, statistical testing defaults, and logging levels. Settings can be changed and reset to defaults.

```python
import infomeasure as im
import numpy as np

# Check current settings
print(f"Current base: {im.Config.get('base')}")
print(f"Current unit: {im.Config.get_logarithmic_unit()}")

# Change logarithmic base/unit
im.Config.set_logarithmic_unit("bits")  # base 2
print(f"After setting bits: {im.Config.get('base')}, {im.Config.get_logarithmic_unit()}")

im.Config.set_logarithmic_unit("nats")  # base e (natural log) - default
print(f"After setting nats: {im.Config.get('base')}")

im.Config.set_logarithmic_unit("hartleys")  # base 10
print(f"After setting hartleys: {im.Config.get('base')}")

# Or set base directly
im.Config.set("base", 2)  # bits
im.Config.set("base", "e")  # nats

# Statistical testing defaults
im.Config.set("statistical_test_method", "permutation_test")  # or "bootstrap"
im.Config.set("statistical_test_n_tests", 1000)

print(f"Test method: {im.Config.get('statistical_test_method')}")
print(f"Number of tests: {im.Config.get('statistical_test_n_tests')}")

# Reset to defaults
im.Config.reset()

# Set logging level
im.Config.set_log_level("DEBUG")  # Show detailed logs
im.Config.set_log_level("WARNING")  # Only warnings and errors

# Example: entropy changes with different bases
data = [0, 1, 0, 1, 0, 1]
im.Config.set("base", "e")
h_nats = im.entropy(data, approach="discrete")
im.Config.set("base", 2)
h_bits = im.entropy(data, approach="discrete")
print(f"Entropy in nats: {h_nats:.4f}, in bits: {h_bits:.4f}")
print(f"Ratio (should be ln(2)): {h_nats/h_bits:.4f}")

im.Config.reset()  # Reset to defaults
```

--------------------------------

### Calculate Entropy using metric approach

Source: https://github.com/cbueth/infomeasure/blob/main/docs/guide/estimator_usage.md

Demonstrates calculating entropy for continuous data using the 'metric' approach with `im.entropy()`. This function can also be used for cross-entropy calculations by passing two variables.

```python
im.entropy(data_P, data_Q, approach="metric")
```

--------------------------------

### Calculate MI with Box Kernel and Offset

Source: https://github.com/cbueth/infomeasure/blob/main/docs/guide/mutual_information/kernel.md

Demonstrates the effect of an 'offset' parameter on MI estimation using a box kernel. A non-zero offset can significantly decrease the estimated MI if it misaligns data pairs.

```python
im.mutual_information(x, y, approach="kernel", kernel="box", bandwidth=0.7, offset=1)
```

--------------------------------

### Calculate Bayesian KLD

Source: https://github.com/cbueth/infomeasure/blob/main/docs/guide/KLD.md

Computes KLD using Bayesian estimators with specified priors. For example, 'laplace' prior can be used. Requires distributions to be provided as lists or arrays.

```python
im.kld(p, q, approach='bayes', alpha="laplace")
```

--------------------------------

### Run Pre-commit Hooks

Source: https://github.com/cbueth/infomeasure/blob/main/CONTRIBUTING.md

Applies pre-commit hooks to format code and run checks before committing. This ensures code quality and consistency.

```bash
pre-commit run --all-files
```

--------------------------------

### Calculate Multivariate Conditional Mutual Information

Source: https://context7.com/cbueth/infomeasure/llms.txt

Computes multivariate conditional mutual information, for example, I(X;Y;W|Z), involving multiple variables conditioned on another set of variables.

```python
cmi_multi = im.conditional_mutual_information(x, y, w, cond=z, approach="kernel", bandwidth=0.2)
print(f"Multivariate CMI: {cmi_multi:.4f}")
```

--------------------------------

### Basic Statistical Test for Mutual Information

Source: https://github.com/cbueth/infomeasure/blob/main/docs/guide/statistical_tests.md

Perform a statistical test for mutual information using global configuration settings. This example generates moderately correlated data and discretizes it.

```python
# Generate sample data with moderate relationship
rng = np.random.default_rng(456)
n_samples = 500

# Create moderately correlated data
x = rng.normal(0, 1, n_samples)
y = 0.25 * x + np.sqrt(1 - 0.25**2) * rng.normal(0, 1, n_samples)

# Discretize for discrete estimators
x_discrete = np.digitize(x, bins=np.linspace(-3, 3, 6))
y_discrete = np.digitize(y, bins=np.linspace(-3, 3, 6))

# Create estimator and perform statistical test
est = im.estimator(x_discrete, y_discrete, measure="mi", approach="discrete")

# Use global configuration
result = est.statistical_test()
print(f"Mutual Information: {est.global_val():.4f}")
print(f"p-value: {result.p_value:.4f}")
print(f"t-score: {result.t_score:.4f}")
print(f"Method: {result.method}")
```

--------------------------------

### Import necessary libraries

Source: https://github.com/cbueth/infomeasure/blob/main/docs/guide/settings.md

Import the infomeasure library and numpy for numerical operations.

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

--------------------------------

### Import Libraries and Initialize RNG

Source: https://github.com/cbueth/infomeasure/blob/main/docs/demos/gaussian_data.md

Imports necessary libraries (infomeasure, numpy, matplotlib) and initializes a random number generator for reproducible results.

```python
import infomeasure as im
import numpy as np
import matplotlib.pyplot as plt
rng = np.random.default_rng(29615)
```

--------------------------------

### Get Estimator Class Programmatically

Source: https://context7.com/cbueth/infomeasure/llms.txt

Retrieve estimator classes dynamically based on the desired measure and approach. This is useful for programmatic access and when the specific estimator class is not known beforehand.

```python
import infomeasure as im
from infomeasure.estimators.entropy.discrete import DiscreteEntropyEstimator
from infomeasure.estimators.entropy.kernel import KernelEntropyEstimator
from infomeasure.estimators.mutual_information.kraskov_stoegbauer_grassberger import KSGMIEstimator
import numpy as np

rng = np.random.default_rng(42)

# Get estimator class programmatically
EntropyClass = im.get_estimator_class(measure="entropy", approach="discrete")
MIClass = im.get_estimator_class(measure="mutual_information", approach="ksg")
TEClass = im.get_estimator_class(measure="transfer_entropy", approach="kernel")
```

--------------------------------

### Performing Statistical Test on Estimator

Source: https://github.com/cbueth/infomeasure/blob/main/docs/guide/estimator_usage.md

Conducts a statistical test on the estimator's global value to assess significance. This example uses a kernel approach for mutual information and a permutation test.

```python
est = im.estimator(a, b, measure="mutual_information",
                   approach="kernel", bandwidth=0.2, kernel="box")
stat_test = est.statistical_test(n_tests=50, method="permutation_test")
(est.result(), stat_test.p_value, stat_test.t_score,
 stat_test.confidence_interval(90), stat_test.percentile(50))
```

--------------------------------

### Create Estimator Instance and Perform Statistical Test

Source: https://github.com/cbueth/infomeasure/blob/main/docs/guide/mutual_information/kraskov_stoegbauer_grassberger.md

Instantiate an estimator for mutual information using `im.estimator` and perform a statistical test. This is required for local mutual information and hypothesis testing.

```python
est = im.estimator(data_x, data_y, measure="mi", approach="metric")
stat_test = est.statistical_test(n_tests=50, method="permutation_test")
est.local_vals(), stat_test.p_value, stat_test.t_score, stat_test.confidence_interval(90), stat_test.percentile(50)
```

--------------------------------

### Import Libraries for Benchmarking

Source: https://github.com/cbueth/infomeasure/blob/main/docs/demos/Time_Performance.ipynb

Imports necessary libraries for time measurement, plotting, numerical operations, and the infomeasure package.

```python
import time  # for measuring elapsed time
import timeit  # for benchmarking

import matplotlib.pyplot as plt
import numpy as np
import progressbar

import infomeasure as im
```

--------------------------------

### Statistical Test for Transfer Entropy

Source: https://github.com/cbueth/infomeasure/blob/main/docs/guide/statistical_tests.md

Test for transfer entropy between two time series, assessing the causal relationship in both directions. This example discretizes time series data and performs tests with a specified number of permutations.

```python
# Generate time series with moderate causal relationship
rng_te = np.random.default_rng(2354)
n_time = 500
x_ts = rng_te.normal(0, 1, n_time)
y_ts = np.zeros(n_time)

# Create moderate causal relationship: Y(t) depends on X(t-1)
for t in range(1, n_time):
    y_ts[t] = 0.3 * x_ts[t-1] + np.sqrt(1 - 0.2**2) * rng_te.normal(0, 1)

# Discretize time series
x_discrete = np.digitize(x_ts, bins=np.linspace(-3, 3, 4))
y_discrete = np.digitize(y_ts, bins=np.linspace(-3, 3, 4))

# Test transfer entropy
te_est = im.estimator(x_discrete, y_discrete, measure="te", approach="discrete")
te_result = te_est.statistical_test(n_tests=200)

print(f"Transfer Entropy X→Y: {te_est.global_val():.4f}")
print(f"p-value: {te_result.p_value:.4f}")
print(f"Significance: {'Yes' if te_result.p_value < 0.05 else 'No'} (α = 0.05)")

# Test reverse direction
te_est_reverse = im.estimator(y_discrete, x_discrete, measure="te", approach="discrete")
te_result_reverse = te_est_reverse.statistical_test(n_tests=200)

print(f"Transfer Entropy Y→X: {te_est_reverse.global_val():.4f}")
print(f"p-value: {te_result_reverse.p_value:.4f}")
print(f"Significance: {'Yes' if te_result_reverse.p_value < 0.05 else 'No'} (α = 0.05)")
```

--------------------------------

### Direct Usage of KernelEntropyEstimator

Source: https://context7.com/cbueth/infomeasure/llms.txt

Instantiate and use the KernelEntropyEstimator with continuous data, specifying parameters like bandwidth and kernel type. This is suitable for smooth continuous distributions.

```python
# Kernel entropy with parameters
cont_data = rng.normal(0, 1, 500)
kernel_est = KernelEntropyEstimator(cont_data, bandwidth=0.3, kernel="gaussian")
print(f"Kernel entropy: {kernel_est.result():.4f}")
```

--------------------------------

### Calculate CMI with Different Discrete Estimators

Source: https://github.com/cbueth/infomeasure/blob/main/docs/guide/cond_mi/index.md

Shows how to compute Conditional Mutual Information (CMI) using various discrete estimators provided by the infomeasure package. Examples include 'discrete', 'ksg', 'kernel', and 'symbolic' approaches.

```python
import infomeasure as im

x = [0, 1, 1, 1, 0, 0, 1, 0, 0, 1, 0, 1, 1, 0, 0]
y = [1, 1, 0, 0, 2, 2, 1, 1, 0, 2, 0, 0, 2, 0, 0]
z = [0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0]
cmi = im.cmi(x, y, cond=z, approach='discrete')
cmi_ksg = im.cmi(x, y, cond=z, approach='ksg')
cmi_kernel = im.cmi(x, y, cond=z, approach='kernel', kernel='box', bandwidth=1.5)
cmi_symbolic = im.cmi(x, y, cond=z, approach='symbolic', embedding_dim=3)
cmi, cmi_ksg, cmi_kernel, cmi_symbolic
```

--------------------------------

### Estimate MI with Offset

Source: https://github.com/cbueth/infomeasure/blob/main/docs/guide/mutual_information/renyi_tsallis.md

Demonstrates the effect of an 'offset' parameter on Rényi and Tsallis MI estimations. A non-zero offset can significantly decrease the estimated MI.

```python
(im.mutual_information(x, y, approach="renyi", alpha=1.0, offset=1),
 im.mutual_information(x, y, approach="tsallis", q=1.0, offset=1))
```

--------------------------------

### Calculate Conditional Transfer Entropy

Source: https://context7.com/cbueth/infomeasure/llms.txt

Shows how to compute conditional transfer entropy T(X->Y|Z) to measure information transfer from X to Y while accounting for Z's influence. Includes examples using 'ordinal' and 'discrete' approaches, and a shorthand function.

```python
import infomeasure as im
import numpy as np

rng = np.random.default_rng(42)

# Generate data: Z influences both X and Y, X also influences Y
n = 500
z = rng.normal(0, 1, n)
x = np.zeros(n)
y = np.zeros(n)

for t in range(1, n):
    x[t] = 0.3 * z[t-1] + rng.normal(0, 0.5)
    y[t] = 0.4 * x[t-1] + 0.3 * z[t-1] + rng.normal(0, 0.3)

# Conditional transfer entropy X -> Y | Z
cte = im.conditional_transfer_entropy(
    x, y, cond=z,
    approach="ordinal",
    embedding_dim=3,
    src_hist_len=2,
    dest_hist_len=2,
    cond_hist_len=1
)
print(f"CTE X->Y|Z: {cte:.4f}")
```

```python
# Can also use cond parameter with transfer_entropy
cte_alt = im.transfer_entropy(x, y, cond=z, approach="discrete")
print(f"CTE via transfer_entropy: {cte_alt:.4f}")
```

```python
# Shorthand
cte_short = im.cte(x, y, cond=z, approach="discrete")
```

--------------------------------

### Define Combinations for Analysis

Source: https://github.com/cbueth/infomeasure/blob/main/docs/demos/Time_Performance.ipynb

Defines a dictionary of different approaches and their corresponding keyword arguments to be used in the analysis and benchmarking. This includes discrete, kernel, metric, ordinal, renyi, and tsallis methods.

```python
combinations = {
    "discrete": {"approach": "discrete", "kwargs": {}},
    "kernel(box)": {
        "approach": "kernel",
        "kwargs": {"bandwidth": 0.5, "kernel": "box"},
    },
    "kernel(gaussian)": {
        "approach": "kernel",
        "kwargs": {"bandwidth": 0.5, "kernel": "gaussian"},
    },
    "metric": {"approach": "metric", "kwargs": {"k": 4, "minkowski_p": np.inf}},
    "ordinal($d$=3)": {"approach": "ordinal", "kwargs": {"embedding_dim": 3}},
    "ordinal($d$=8)": {"approach": "ordinal", "kwargs": {"embedding_dim": 3}},
    r"renyi($\alpha$=1)": {"approach": "renyi", "kwargs": {"alpha": 1}},
    r"renyi($\alpha$=1.5)": {"approach": "renyi", "kwargs": {"alpha": 1.5}},
    "tsallis($q$=1.05)": {"approach": "tsallis", "kwargs": {"q": 1.05}},
    # 'miller-madow': {'approach': 'miller_madow', 'kwargs': {}},
    # r'bayes($\alpha$=0.5)': {'approach': 'bayes', 'kwargs': {'alpha': 0.5}},
    # 'shrinkage': {'approach': 'shrink', 'kwargs': {}},
    # 'grassberger': {'approach': 'grassberger', 'kwargs': {}},
    # 'chao_wang_jost': {'approach': 'chao_wang_jost', 'kwargs': {}},
    # 'ansb(K=N/100)': {'approach': 'ansb', 'kwargs': {'undersampled': np.inf}},
    # 'nsb(K=N/100)': {'approach': 'nsb', 'kwargs': {}},
    # 'zhang': {'approach': 'zhang', 'kwargs': {}},
    # 'bonachela': {'approach': 'bonachela', 'kwargs': {}},
}
```

--------------------------------

### Transfer Entropy Calculation (Ordinal Approach)

Source: https://github.com/cbueth/infomeasure/blob/main/docs/guide/transfer_entropy/ordinal.md

Demonstrates how to calculate Transfer Entropy using the ordinal approach with direct function calls.

```APIDOC
## Calculate Transfer Entropy (Ordinal Approach)

### Description
Calculates the Transfer Entropy from a source process X to a target process Y using the ordinal (symbolic) method.

### Method
`infomeasure.transfer_entropy`

### Parameters
- **data_x** (numpy.ndarray) - The source time series data.
- **data_y** (numpy.ndarray) - The target time series data.
- **approach** (str) - Set to "ordinal" for this method.
- **embedding_dim** (int) - The embedding dimension (k for source, l for target).
- **step_size** (int) - The step size for embedding.
- **prop_time** (int) - The propagation time.
- **src_hist_len** (int) - The history length for the source embedding.
- **dest_hist_len** (int) - The history length for the target embedding.

### Request Example
```python
import infomeasure as im
import numpy as np

rng = np.random.default_rng(5673267189)
data_x = rng.normal(size=1000)
data_y = np.roll(data_x, 1)

transfer_entropy_value = im.transfer_entropy(
    data_x,  # source
    data_y,  # target
    approach="ordinal", embedding_dim = 3,
    step_size = 1, prop_time = 0, src_hist_len = 1, dest_hist_len = 1,
)
```

### Response
#### Success Response (200)
- **transfer_entropy_value** (float) - The calculated Transfer Entropy value.
```

--------------------------------

### Time Lag Selection for Transfer Entropy with P-value Evaluation

Source: https://github.com/cbueth/infomeasure/blob/main/docs/guide/estimator_selection.md

This example demonstrates how to test transfer entropy for different time lags and evaluate their statistical significance using permutation tests. It helps identify the optimal time lag for causal influence in time series data.

```python
# Generate time series data with known causal relationship
np.random.seed(777)  # For reproducible results
n_samples = 200

# Create source time series
source = np.random.choice([0, 1, 2], size=n_samples, p=[0.4, 0.4, 0.2])

# Create destination time series with causal influence from source (lag=3 is optimal)
dest = np.zeros(n_samples, dtype=int)
dest[0] = np.random.choice([0, 1, 2])  # Random initial value

for i in range(1, n_samples):
    if i >= 3:  # True causal lag is 3
        # 20% chance to be influenced by source[i-3], 80% random
        if np.random.random() < 0.2:
            dest[i] = source[i-3]
        else:
            dest[i] = np.random.choice([0, 1, 2])
    else:
        dest[i] = np.random.choice([0, 1, 2])

# Test different time lags (1 to 5) and evaluate p-values
print("Testing Transfer Entropy with different time lags:")
print("Lag\tTE Value\tP-value")
print("-" * 32)

lag_results = []
for lag in range(1, 6):
    # Create TE estimator with specific time lag
    te_estimator = im.estimator(
        source, dest,
        measure="transfer_entropy",
        approach="discrete",
        prop_time=lag
    )

    # Get TE value
    te_value = te_estimator.result()

    # Perform statistical test to get p-value
    stat_result = te_estimator.statistical_test(n_tests=100, method="permutation_test")
    p_value = stat_result.p_value

    lag_results.append((lag, te_value, p_value))
    print(f"{lag}\t{te_value:.4f}\t\t{p_value:.4f}")

# Find the lag with the best (lowest) p-value
best_lag, best_te, best_p = min(lag_results, key=lambda x: x[2])

print(f"\nBest time lag: {best_lag}")
print(f"TE value at best lag: {best_te:.4f}")
print(f"Best p-value: {best_p:.4f}")

# Additional analysis: show confidence interval for the best lag
best_estimator = im.estimator(
    source, dest,
    measure="transfer_entropy",
    approach="discrete",
    prop_time=best_lag
)
best_stat_result = best_estimator.statistical_test(n_tests=1000, method="permutation_test")
ci_95 = best_stat_result.percentile([2.5, 97.5])
print(f"95% Confidence Interval for best lag: [{ci_95[0]:.4f}, {ci_95[1]:.4f}]")
```

--------------------------------

### Initialize and Use Transfer Entropy Estimator

Source: https://github.com/cbueth/infomeasure/blob/main/docs/guide/transfer_entropy/kraskov_stoegbauer_grassberger.md

Creates an instance of the transfer entropy estimator and calculates its local values. Use this for more detailed analysis or when multiple measures are needed from the same data.

```python
est = im.estimator(
    data_x,  # source
    data_y,  # target
    measure='te',  # or 'transfer_entropy'
    approach="metric",
    step_size = 1, prop_time = 0, src_hist_len = 1, dest_hist_len = 1,
)
est.local_vals()
```

--------------------------------

### Initialize Kernel TE Estimator

Source: https://github.com/cbueth/infomeasure/blob/main/docs/guide/transfer_entropy/kernel.md

Creates an instance of the kernel TE estimator. Specify source and target data, measure type, and kernel parameters like bandwidth and history lengths.

```python
est = im.estimator(
    data_x,  # source
    data_y,  # target
    measure='te',  # or 'transfer_entropy'
    approach="kernel", kernel="box", bandwidth=0.7,
    step_size = 1, prop_time = 0, src_hist_len = 1, dest_hist_len = 1,
)
```

--------------------------------

### Benchmarking Entropy Calculation Approaches

Source: https://github.com/cbueth/infomeasure/blob/main/docs/demos/Time_Performance.ipynb

This code iterates through different entropy calculation approaches, benchmarks them using the `benchmark_approach` function, and stops if a time limit is exceeded. It calculates and stores the mean and standard deviation of execution times for each approach and dataset size.

```python
import time\nimport progressbar\nimport numpy as np\nimport infomeasure as im\n\nbenchmark_max_time = 400  # if exceeded, stop benchmarking current approach\ntotal_keys = len(combinations)\n\n# Create a progress bar for the outer loop with customized widgets\nwidgets = [\n    progressbar.DynamicMessage("key"),\n    " |",\n    progressbar.Bar(),\n    " | ",\n    progressbar.Percentage(),\n    " (",\n    progressbar.ETA(),\n    ")",\n]\n\nwith progressbar.ProgressBar(max_value=total_keys, widgets=widgets) as pbar:\n    for i, (key, combination) in enumerate(combinations.items()):\n        pbar.update(i, key=key)  # Update the progress bar with the current key\n\n        data = data_h if combination["approach"] != "discrete" else data_h_discrete\n        times_h = [None] * len(data)\n\n        for n in range(len(data)):\n            t0 = time.time()\n            times_h[n] = benchmark_approach(\n                im.entropy,\n                data[n],\n                approach=combination["approach"],\n                **combination["kwargs"],\n            )\n            if time.time() - t0 > benchmark_max_time:\n                print(f"Time limit exceeded for {key} at index {n}")\n                break\n\n        means_h = [\n            np.mean(times_h[n]) if times_h[n] is not None else np.nan\n            for n in range(len(data))\n        ]\n        stds_h = [\n            np.std(times_h[n]) if times_h[n] is not None else np.nan\n            for n in range(len(data))\n        ]\n        combinations[key]["h_means"] = means_h\n        combinations[key]["h_times"] = times_h\n        combinations[key]["h_stds"] = stds_h
```

--------------------------------

### Creating an Estimator Instance in InfoMeasure

Source: https://github.com/cbueth/infomeasure/blob/main/docs/guide/estimator_usage.md

Instantiates an estimator for calculating information measures. Specify the data, the desired measure (e.g., 'entropy', 'mutual_information'), and the approach (e.g., 'discrete', 'kernel').

```python
a = rng.integers(0, 10, size=1000)
b = rng.integers(0, 10, size=1000)
est = im.estimator(
    a.astype(int),       # data: x | x, y, ... | source, dest
    measure="entropy",   # "mutual_information", "transfer_entropy", "h", "mi", "te",
                         # "conditional_mutual_information", "cmi",
                         # "conditional_transfer_entropy", "cte"
    approach="discrete"  # "kernel", "metric", "kl", "ksg", "ordinal", "symbolic",
                         # "permutation", "renyi", "tsallis"
    # additional parameters for each approach, e.g. `cond = ...` to conditionalize
)
est.result(), est.local_vals()
```

--------------------------------

### Estimator Objects for Entropy and Mutual Information

Source: https://context7.com/cbueth/infomeasure/llms.txt

Illustrates creating estimator objects for discrete entropy and mutual information calculations. Shows how to retrieve global (average) and local (point-wise) values.

```python
import infomeasure as im
import numpy as np

rng = np.random.default_rng(42)

# Create estimator object
data = rng.integers(0, 10, size=1000)
est = im.estimator(
    data,
    measure="entropy",
    approach="discrete"
)

# Get global value (average entropy)
global_val = est.result()  # or est.global_val()
print(f"Global entropy: {global_val:.4f}")

# Get local values (entropy per observation)
local_vals = est.local_vals()
print(f"Local values shape: {local_vals.shape}")
print(f"First 5 local values: {local_vals[:5]}")
print(f"Mean of local values: {np.mean(local_vals):.4f}")  # Should equal global
```

```python
# Mutual information estimator with local values
x = rng.integers(0, 5, 500)
y = rng.integers(0, 5, 500)
mi_est = im.estimator(x, y, measure="mutual_information", approach="discrete")
mi_global = mi_est.result()
mi_local = mi_est.local_vals()
print(f"MI global: {mi_global:.4f}, Local mean: {np.mean(mi_local):.4f}")
```

--------------------------------

### Correct Usage of InfoMeasure Utility Functions

Source: https://github.com/cbueth/infomeasure/blob/main/docs/guide/estimator_usage.md

Demonstrates the correct way to pass data to InfoMeasure utility functions, emphasizing var-positional parameters for data and keyword arguments for conditional data.

```python
im.mi(a, b, ...)
im.te(a, b, cond=c, ...)
```

--------------------------------

### Prepare and Print Data Lengths

Source: https://github.com/cbueth/infomeasure/blob/main/docs/demos/Time_Performance.ipynb

Generates datasets of varying lengths for H, MI, and TE calculations, including discrete versions. It also prints the shortest and longest sequence lengths used in the benchmark.

```python
# Generate the data for different lengths of sequences
data_lengths = [
    2**k for k in range(3, 25) 
]  # reduce for testing. Needs to be increasing lengths
rng = np.random.default_rng(925847)

data_h = [generate_data_h(N) for N in data_lengths]
data_mi = [generate_data_mi(N) for N in data_lengths]
data_te = [(var, np.roll(var, 1)) for var in data_h]

# discrete versions for the discrete approach
data_h_discrete = [var.astype(int) for var in data_h]
data_mi_discrete = [(var[0].astype(int), var[1].astype(int)) for var in data_mi]
data_te_discrete = [(var[0].astype(int), var[1].astype(int)) for var in data_te]
print(f"Shortest sequence length: {min(data_lengths)}")
print(f"Longest sequence length: {max(data_lengths):e}")
```

--------------------------------

### Ordinal Entropy Estimator with Distribution Dictionary

Source: https://github.com/cbueth/infomeasure/blob/main/docs/guide/entropy/ordinal.md

Instantiates an ordinal entropy estimator and prints the calculated entropy, the distribution dictionary of ordinal patterns, and the sum of probabilities.

```python
est = im.estimator(data, measure="h", approach="ordinal", embedding_dim=3)
print(f"Entropy: {est.result():.4f} bits")
print(f"Distribution: {est.dist_dict}")
print(f"Probabilities sum to: {sum(est.dist_dict.values()):.1f}")
```

--------------------------------

### Create Progress Bar with Custom Widgets

Source: https://github.com/cbueth/infomeasure/blob/main/docs/demos/Time_Performance.ipynb

Initializes a progress bar for an outer loop with custom display elements including dynamic messages, bar, percentage, and estimated time of arrival. This is useful for tracking long-running computations.

```python
widgets = [
    progressbar.DynamicMessage("key"),
    " |",
    progressbar.Bar(),
    " | ",
    progressbar.Percentage(),
    " (",
    progressbar.ETA(),
    ")",
]

with progressbar.ProgressBar(max_value=total_keys, widgets=widgets) as pbar:
    for i, (key, combination) in enumerate(combinations.items()):
        pbar.update(i, key=key)  # Update the progress bar with the current key

        data = data_te if combination["approach"] != "discrete" else data_te_discrete
        times_te = [None] * len(data)

        for n in range(len(data)):
            t0 = time.time()
            times_te[n] = benchmark_approach(
                im.entropy,
                data[n],
                approach=combination["approach"],
                **combination["kwargs"],
            )
            if time.time() - t0 > benchmark_max_time:
                # print(f"Time limit exceeded for {key} at index {n}")
                break

        means_te = [
            np.mean(times_te[n]) if times_te[n] is not None else np.nan
            for n in range(len(data))
        ]
        stds_te = [
            np.std(times_te[n]) if times_te[n] is not None else np.nan
            for n in range(len(data))
        ]
        combinations[key]["te_means"] = means_te
        combinations[key]["te_times"] = times_te
        combinations[key]["te_stds"] = stds_te
```

--------------------------------

### Calculate Discrete Entropy (Maximum Likelihood)

Source: https://github.com/cbueth/infomeasure/blob/main/docs/guide/entropy/discrete.md

Uses the plug-in method to estimate entropy by counting occurrences. Suitable as a baseline but can be biased for small samples.

```python
import infomeasure as im
import numpy as np

data = [0, 1, 0, 1, 0, 1, 0, 1]
im.entropy(data, approach="discrete", base=2)
```

--------------------------------

### Save Benchmark Data to Pickle File

Source: https://github.com/cbueth/infomeasure/blob/main/docs/demos/Time_Performance.ipynb

Saves the computed benchmark data, including data lengths and combinations, to a binary pickle file. This allows for later loading and analysis without re-running the benchmarks.

```python
import pickle

# Save data to pickle file
with open("time_data.pkl", "wb") as f:
    pickle.dump((data_lengths, combinations), f)
```

--------------------------------

### Calculate Tsallis Entropy (q!=1)

Source: https://github.com/cbueth/infomeasure/blob/main/docs/guide/entropy/tsallis.md

Calculates the Tsallis entropy for q != 1 using reweighted data points. This demonstrates the flexibility of the Tsallis entropy for different q values.

```python
(im.entropy(data, approach="tsallis", q=0.8),
 im.entropy(data, approach="tsallis", q=1.2))
```

--------------------------------

### Advanced Analysis with Estimator Instance

Source: https://github.com/cbueth/infomeasure/blob/main/docs/guide/transfer_entropy/discrete.md

Create an estimator instance for advanced analysis including local values, effective TE, and statistical testing. This requires source and target data, measure type, and approach.

```python
# Create data with weaker coupling for statistical testing demonstration
rng_stat = np.random.default_rng(12345)
data_x_stat = rng_stat.integers(4, size=200)
data_y_stat = np.zeros_like(data_x_stat)
for i in range(1, len(data_x_stat)):
    if rng_stat.random() < 0.1:  # Only 10% chance to follow pattern
        data_y_stat[i] = data_x_stat[i-1]
    else:
        data_y_stat[i] = rng_stat.integers(4)

# Create estimator instance for advanced analysis
est = im.estimator(
    data_x_stat,  # source
    data_y_stat,  # target
    measure='te',  # or 'transfer_entropy'
    approach='discrete',
    step_size=1, prop_time=0, src_hist_len=1, dest_hist_len=1,
    base=2,
)

# Calculate local transfer entropy values
local_te = est.local_vals()
print(f"Local TE values (first 10): {local_te[:10]}")

# Calculate effective transfer entropy
effective_te = est.effective_val()
print(f"Effective TE: {effective_te:.6f} bits")

# Perform statistical testing
stat_test = est.statistical_test(n_tests=50, method="permutation_test")
print(f"P-value: {stat_test.p_value:.4f}")
print(f"T-score: {stat_test.t_score:.4f}")
print(f"90% CI: {stat_test.confidence_interval(0.90)}")
print(f"Median of null distribution: {stat_test.percentile(50):.4f}")
```