DOCSEARCHbyAlgolia
Submit Docs

EntropyHub

repository·main·Indexed 41 days ago

https://github.com/mattwillflood/entropyhub

An open-source toolkit for entropic data analysis providing consistent implementations of univariate, multivariate, and multiscale entropy methods across MatLab, Python, and Julia. It includes a comprehensive set of functions for estimating entropy from discrete data sequences, including base, cross, bidimensional, and multiscale approaches. Supports Python > 3.6, MatLab >= 2016a, and Julia >= 1.2.

Tokens
18.6K
Snippets
67
Records
100
Agent score
45%

What's inside EntropyHub

  1. Overview of EntropyHub MatLab function categories

    main

    EntropyHub provides a comprehensive suite of MatLab functions for entropic data analysis, organized into eight functional categories based on the dimensionality and scale of the input data:

    1. Base: Estimating entropy for a single univariate time series.
    2. Cross: Estimating entropy between two univariate time series.
    3. Multivariate: Estimating entropy for a multivariate dataset.
    4. Bidimensional (2D): Estimating entropy for a two-dimensional univariate matrix.
    5. Multiscale: Estimating multiscale entropy of a single univariate time series using Base entropy functions.
    6. Multiscale Cross: Estimating multiscale entropy between two univariate time series using Cross-entropy functions.
    7. Multiscale Multivariate: Estimating multivariate multiscale entropy of a multivariate dataset using Multivariate-entropy functions.
    8. Other: Supplementary functions for signal processing and data management.

  2. Overview of EntropyHub

    main

    EntropyHub is an open-source toolkit designed for entropic data analysis, specifically focusing on estimating entropy from discrete data sequences using principles from information and probability theory (Shannon entropy). It provides a comprehensive set of functions with a consistent syntax for implementing basic to advanced entropy methods, including multivariate and multiscale approaches.

    Note: The entropy functions in this toolkit are defined in the context of probability and information theory, not thermodynamic entropy from classical physics.

  3. Overview of EntropyHub function categories

    main

    EntropyHub provides entropic analysis functions organized into 8 distinct categories based on the data structure and the relationship being analyzed:

    1. Base: Estimating entropy for a single univariate time series.
    2. Cross: Estimating entropy between two univariate time series.
    3. Multivariate: Estimating entropy for a multivariate dataset.
    4. Bidimensional: Estimating entropy for a two-dimensional univariate matrix.
    5. Multiscale: Estimating multiscale entropy for a single univariate time series using any of the Base functions.
    6. Multiscale Cross: Estimating multiscale entropy between two univariate time series using any of the Cross functions.
    7. Multivariate Multiscale: Estimating multivariate multiscale entropy for multivariate datasets using any of the Multivariate functions.
    8. Other: Supplementary tools for signal processing and data handling.

  4. Overview of EntropyHub Python function categories

    main

    EntropyHub provides a comprehensive suite of Python functions for entropic data analysis, organized into eight functional categories based on the data structure and the type of entropy being calculated:

    1. Base: Estimating entropy for a single univariate time series.
    2. Cross: Estimating entropy between two univariate time series.
    3. Multivariate: Estimating entropy for a multivariate dataset.
    4. Bidimensional (2D): Estimating entropy for a two-dimensional univariate matrix.
    5. Multiscale: Estimating multiscale entropy of a single univariate time series using any of the Base functions.
    6. Multiscale Cross: Estimating multiscale entropy between two univariate time series using any of the Cross functions.
    7. Multivariate Multiscale: Estimating multivariate multiscale entropy of a multivariate dataset using any of the Multivariate functions.
    8. Other: Supplementary functions for signal processing and data management.

  5. How multiscale cross-entropy works in MATLAB

    main

    Multiscale cross-entropy allows you to estimate the relationship between two univariate time series across multiple scales. You can use any of the following base cross-entropy functions to perform this analysis:

    • XApEn (Approximate Entropy)
    • XSampEn (Sample Entropy)
    • XK2En (K2 Entropy)
    • XCondEn (Conditional Entropy)
    • XPermEn (Permutation Entropy)
    • XSpecEn (Spectral Entropy)
    • XDistEn (Distribution Entropy)
    • XFuzzEn (Fuzzy Entropy)

    To perform the calculation, you must first wrap your multiscale parameters into an MSobject (multiscale object). This object is then passed as an argument to the multiscale cross-entropy functions.

  6. Use different length sequences in cross-entropy

    main

    As of v1.0, EntropyHub supports cross-entropy (and multiscale cross-entropy) estimation between signals of different lengths.

    Requirement: For these functions, you must provide a separate input for each sequence (e.g., Sig1, Sig2).

    Exceptions: This capability does not apply to XCondEn and XPermEn.

  7. How multiscale entropy functions work

    main

    EntropyHub uses a specific pattern for transitioning from base entropy methods to multiscale versions:

    1. MSobject(): To use multiscale, multiscale cross-, or multivariate multiscale entropy functions, you must provide a multiscale entropy object created via MSobject().
    2. Function Passing: Parameters for base, cross-, or multivariate entropy methods are passed to the multiscale functions via this MSobject(). The base method is declared within MSobject() using a string of the function name.

    Example Pattern:

    # Conceptual pattern
ms_obj = EH.MSobject('SampEn')
# The multiscale function then uses this object
result = EH.MSE(data, ms_obj)

  8. Data constraints in hierarchical multiscale entropy

    main

    When using hierarchical multiscale entropy (hMSEn()) or hierarchical multiscale cross-entropy (hXMSEn()), the length of the time series signal(s) is halved at each scale.

    As a result, these functions only utilize the first $2^N$ data points where $2^N \le$ the length of the original signal.

    Examples of data truncation:

    • A signal of 5000 points: only the first 4096 points are used.
    • A signal of 1500 points: only the first 1024 points are used.

  9. Estimate entropy for 2D matrices using Bidimensional Entropies

    main

    EntropyHub provides a suite of functions to estimate the entropy of two-dimensional (2D) univariate matrices, which is particularly useful for image and texture analysis.

    Available functions include:

    • SampEn2D
    • FuzzEn2D
    • DistEn2D
    • DispEn2D
    • PermEn2D
    • EspEn2D

    These functions are accessible directly from the main EntropyHub module.

    import EntropyHub as EH

# Example of accessing the bidimensional functions
# (Actual function calls depend on specific parameter requirements)
result = EH.SampEn2D(matrix, ...)

  10. Manage matrix size limits for bidimensional entropy functions

    main

    By default, all bidimensional entropy functions (SampEn2D, FuzzEn2D, DistEn2D, DispEn2D, PermEn2D, EspEn2D) are locked to prevent memory errors.

    • Default Behavior: Lock = true. This restricts input matrices to a maximum size of 128 x 128.
    • Why the limit exists: Estimating bidimensional entropy involves hundreds of millions of pairwise calculations. For example, a [200 x 200] matrix with m = 3 and tau = 1 requires over 753 million pairwise comparisons, which can cause MATLAB to crash due to RAM exhaustion.
    • How to use larger matrices: To process matrices larger than 128 x 128, you must explicitly set the Lock keyword argument to false.

    CAUTION: Unlocking the matrix size may cause your MATLAB application to crash if the system runs out of memory.

    %% Example: Unlocking for a larger matrix
% result = SampEn2D(myLargeMatrix, m, tau, 'Lock', false);

  11. How to use bidimensional entropy functions in MATLAB

    main

    EntropyHub provides functions to estimate the entropy of two-dimensional (2D) matrices, which is useful for applications like image or texture analysis. These functions allow you to analyze the complexity of 2D data structures rather than standard univariate sequences.

    Available functions include:

    • SampEn2D
    • FuzzEn2D
    • DistEn2D
    • DispEn2D
    • PermEn2D
    • EspEn2D

  12. How multiscale cross-entropy functions work

    main

    Multiscale cross-entropy allows you to estimate the relationship between two univariate time series across multiple scales. To perform this analysis, you must provide two data sequences and a multiscale entropy object (Mobj).

    All multiscale cross-entropy functions follow a consistent signature requiring three positional arguments:

    1. Sig1: The first data sequence (must be a vector with > 10 elements).
    2. Sig2: The second data sequence (must be a vector with > 10 elements).
    3. Mobj: A multiscale entropy object created using the MSobject function.

    You can use any of the following cross-entropy base methods with the multiscale approach:

    • XApEn (Approximate Entropy)
    • XSampEn (Sample Entropy)
    • XK2En (K2 Entropy)
    • XCondEn (Conditional Entropy)
    • XPermEn (Permutation Entropy)
    • XSpecEn (Spectral Entropy)
    • XDistEn (Distribution Entropy)
    • XFuzzEn (Fuzzy Entropy)
    # Conceptual usage pattern
# mobj = MSobject(...)
# result = XMSEn(Sig1, Sig2, mobj)