Source code for neurokit2.complexity.entropy_multiscale

# -*- coding: utf-8 -*-
import matplotlib.pyplot as plt
import numpy as np
import pandas as pd

from ..misc import copyfunction
from .complexity_lempelziv import complexity_lempelziv
from .entropy_approximate import entropy_approximate
from .entropy_cosinesimilarity import entropy_cosinesimilarity
from .entropy_increment import entropy_increment
from .entropy_permutation import entropy_permutation
from .entropy_sample import entropy_sample
from .entropy_slope import entropy_slope
from .entropy_symbolicdynamic import entropy_symbolicdynamic
from .optim_complexity_tolerance import complexity_tolerance
from .utils_complexity_coarsegraining import _get_scales, complexity_coarsegraining
from .utils_entropy import _phi, _phi_divide

[docs] def entropy_multiscale( signal, scale="default", dimension=3, tolerance="sd", method="MSEn", show=False, **kwargs, ): """**Multiscale entropy (MSEn) and its Composite (CMSEn), Refined (RCMSEn) or fuzzy versions** One of the limitation of :func:`SampEn <entropy_sample>` is that it characterizes complexity strictly on the time scale defined by the sampling procedure (via the ``delay`` argument). To address this, Costa et al. (2002) proposed the multiscale entropy (MSEn), which computes sample entropies at multiple scales. The conventional MSEn algorithm consists of two steps: 1. A :func:`coarse-graining <complexity_coarsegraining>` procedure is used to represent the signal at different time scales. 2. :func:`Sample entropy <entropy_sample>` (or other function) is used to quantify the regularity of a coarse-grained time series at each time scale factor. However, in the traditional coarse-graining procedure, the larger the scale factor is, the shorter the coarse-grained time series is. As such, the variance of the entropy of the coarse-grained series estimated by SampEn increases as the time scale factor increases, making it problematic for shorter signals. * **CMSEn**: In order to reduce the variance of estimated entropy values at large scales, Wu et al. (2013) introduced the **Composite Multiscale Entropy** algorithm, which computes multiple coarse-grained series for each scale factor (via the **time-shift** method for :func:`coarse-graining <complexity_coarsegraining>`). * **RCMSEn**: Wu et al. (2014) further **Refined** their CMSEn by averaging not the entropy values of each subcoarsed vector, but its components at a lower level. * **MMSEn**: Wu et al. (2013) also introduced the **Modified Multiscale Entropy** algorithm, which is based on rolling-average :func:`coarse-graining <complexity_coarsegraining>`. * **IMSEn**: Liu et al. (2012) introduced an adaptive-resampling procedure to resample the coarse-grained series. We implement a generalization of this via interpolation that can be referred to as **Interpolated Multiscale Entropy**. .. warning:: Interpolated Multiscale variants don't work as expected. Help is needed to fix this procedure. Their :func:`Fuzzy <entropy_fuzzy>` version can be obtained by setting ``fuzzy=True``. This function can be called either via ``entropy_multiscale()`` or ``complexity_mse()``. Moreover, variants can be directly accessed via ``complexity_cmse()``, `complexity_rcmse()``, ``complexity_fuzzymse()``, ``complexity_fuzzycmse()`` and ``complexity_fuzzyrcmse()``. Parameters ---------- signal : Union[list, np.array, pd.Series] The signal (i.e., a time series) in the form of a vector of values. or dataframe. scale : str or int or list A list of scale factors used for coarse graining the time series. If 'default', will use ``range(len(signal) / (dimension + 10))`` (see discussion `here <>`_). If 'max', will use all scales until half the length of the signal. If an integer, will create a range until the specified int. See :func:`complexity_coarsegraining` for details. dimension : int Embedding Dimension (*m*, sometimes referred to as *d* or *order*). See :func:`complexity_dimension` to estimate the optimal value for this parameter. tolerance : float Tolerance (often denoted as *r*), distance to consider two data points as similar. If ``"sd"`` (default), will be set to :math:`0.2 * SD_{signal}`. See :func:`complexity_tolerance` to estimate the optimal value for this parameter. method : str What version of multiscale entropy to compute. Can be one of ``"MSEn"``, ``"CMSEn"``, ``"RCMSEn"``, ``"MMSEn"``, ``"IMSEn"``, ``"MSApEn"``, ``"MSPEn"``, ``"CMSPEn"``, ``"MMSPEn"``, ``"IMSPEn"``, ``"MSWPEn"``, ``"CMSWPEn"``, ``"MMSWPEn"``, ``"IMSWPEn"`` (case sensitive). show : bool Show the entropy values for each scale factor. **kwargs Optional arguments. Returns ---------- float The point-estimate of multiscale entropy (MSEn) of the single time series corresponding to the area under the MSEn values curve, which is essentially the sum of sample entropy values over the range of scale factors. dict A dictionary containing additional information regarding the parameters used to compute multiscale entropy. The entropy values corresponding to each ``"Scale"`` factor are stored under the ``"Value"`` key. See Also -------- complexity_coarsegraining, entropy_sample, entropy_fuzzy, entropy_permutation Examples ---------- **MSEn** (basic coarse-graining) .. ipython:: python import neurokit2 as nk signal = nk.signal_simulate(duration=2, frequency=[5, 12, 40]) @savefig p_entropy_multiscale1.png scale=100% msen, info = nk.entropy_multiscale(signal, show=True) @suppress plt.close() **CMSEn** (time-shifted coarse-graining) .. ipython:: python @savefig p_entropy_multiscale2.png scale=100% cmsen, info = nk.entropy_multiscale(signal, method="CMSEn", show=True) @suppress plt.close() **RCMSEn** (refined composite MSEn) .. ipython:: python @savefig p_entropy_multiscale3.png scale=100% rcmsen, info = nk.entropy_multiscale(signal, method="RCMSEn", show=True) @suppress plt.close() **MMSEn** (rolling-window coarse-graining) .. ipython:: python @savefig p_entropy_multiscale4.png scale=100% mmsen, info = nk.entropy_multiscale(signal, method="MMSEn", show=True) @suppress plt.close() **IMSEn** (interpolated coarse-graining) .. ipython:: python @savefig p_entropy_multiscale5.png scale=100% imsen, info = nk.entropy_multiscale(signal, method="IMSEn", show=True) @suppress plt.close() **MSApEn** (based on ApEn instead of SampEn) .. ipython:: python @savefig p_entropy_multiscale6.png scale=100% msapen, info = nk.entropy_multiscale(signal, method="MSApEn", show=True) @suppress plt.close() **MSPEn** (based on PEn), **CMSPEn**, **MMSPEn** and **IMSPEn** .. ipython:: python @savefig p_entropy_multiscale7.png scale=100% mspen, info = nk.entropy_multiscale(signal, method="MSPEn", show=True) @suppress plt.close() .. ipython:: python cmspen, info = nk.entropy_multiscale(signal, method="CMSPEn") cmspen mmspen, info = nk.entropy_multiscale(signal, method="MMSPEn") mmspen imspen, info = nk.entropy_multiscale(signal, method="IMSPEn") imspen **MSWPEn** (based on WPEn), **CMSWPEn**, **MMSWPEn** and **IMSWPEn** .. ipython:: python mswpen, info = nk.entropy_multiscale(signal, method="MSWPEn") cmswpen, info = nk.entropy_multiscale(signal, method="CMSWPEn") mmswpen, info = nk.entropy_multiscale(signal, method="MMSWPEn") imswpen, info = nk.entropy_multiscale(signal, method="IMSWPEn") **FuzzyMSEn**, **FuzzyCMSEn** and **FuzzyRCMSEn** .. ipython:: python @savefig p_entropy_multiscale8.png scale=100% fuzzymsen, info = nk.entropy_multiscale(signal, method="MSEn", fuzzy=True, show=True) @suppress plt.close() .. ipython:: python fuzzycmsen, info = nk.entropy_multiscale(signal, method="CMSEn", fuzzy=True) fuzzycmsen fuzzyrcmsen, info = nk.entropy_multiscale(signal, method="RCMSEn", fuzzy=True) fuzzycmsen References ----------- * Costa, M., Goldberger, A. L., & Peng, C. K. (2002). Multiscale entropy analysis of complex physiologic time series. Physical review letters, 89(6), 068102. * Costa, M., Goldberger, A. L., & Peng, C. K. (2005). Multiscale entropy analysis of biological signals. Physical review E, 71(2), 021906. * Wu, S. D., Wu, C. W., Lee, K. Y., & Lin, S. G. (2013). Modified multiscale entropy for short-term time series analysis. Physica A: Statistical Mechanics and its Applications, 392 (23), 5865-5873. * Wu, S. D., Wu, C. W., Lin, S. G., Wang, C. C., & Lee, K. Y. (2013). Time series analysis using composite multiscale entropy. Entropy, 15(3), 1069-1084. * Wu, S. D., Wu, C. W., Lin, S. G., Lee, K. Y., & Peng, C. K. (2014). Analysis of complex time series using refined composite multiscale entropy. Physics Letters A, 378(20), 1369-1374. * Gow, B. J., Peng, C. K., Wayne, P. M., & Ahn, A. C. (2015). Multiscale entropy analysis of center-of-pressure dynamics in human postural control: methodological considerations. Entropy, 17(12), 7926-7947. * Norris, P. R., Anderson, S. M., Jenkins, J. M., Williams, A. E., & Morris Jr, J. A. (2008). Heart rate multiscale entropy at three hours predicts hospital mortality in 3,154 trauma patients. Shock, 30(1), 17-22. * Liu, Q., Wei, Q., Fan, S. Z., Lu, C. W., Lin, T. Y., Abbod, M. F., & Shieh, J. S. (2012). Adaptive computation of multiscale entropy and its application in EEG signals for monitoring depth of anesthesia during surgery. Entropy, 14(6), 978-992. """ # Sanity checks if isinstance(signal, (np.ndarray, pd.DataFrame)) and signal.ndim > 1: raise ValueError( "Multidimensional inputs (e.g., matrices or multichannel data) are not supported yet." ) # Prevent multiple arguments error in case 'delay' is passed in kwargs if "delay" in kwargs: kwargs.pop("delay") # Default parameters algorithm = entropy_sample refined = False coarsegraining = "nonoverlapping" # Parameters adjustement for variants if method in ["MSEn", "SampEn"]: pass # The default arguments are good elif method in ["MSApEn", "ApEn", "MSPEn", "PEn", "MSWPEn", "WPEn"]: if method in ["MSApEn", "ApEn"]: algorithm = entropy_approximate if method in ["MSPEn", "PEn"]: algorithm = entropy_permutation if method in ["MSWPEn", "WPEn"]: algorithm = copyfunction(entropy_permutation, weighted=True) elif method in ["MMSEn", "MMSPEn", "MMSWPEn"]: coarsegraining = "rolling" if method in ["MMSPEn"]: algorithm = entropy_permutation if method in ["MMSWPEn"]: algorithm = copyfunction(entropy_permutation, weighted=True) elif method in ["IMSEn", "IMSPEn", "IMSWPEn"]: coarsegraining = "interpolate" if method in ["IMSPEn"]: algorithm = entropy_permutation if method in ["IMSWPEn"]: algorithm = copyfunction(entropy_permutation, weighted=True) elif method in ["CMSEn", "RCMSEn", "CMSPEn", "CMSWPEn"]: coarsegraining = "timeshift" if method in ["CMSPEn"]: algorithm = entropy_permutation if method in ["CMSWPEn"]: algorithm = copyfunction(entropy_permutation, weighted=True) if method in ["RCMSEn"]: refined = True elif method in ["MSCoSiEn", "CoSiEn"]: algorithm = entropy_cosinesimilarity elif method in ["MSIncrEn", "IncrEn"]: algorithm = entropy_increment elif method in ["MSSlopEn", "SlopEn"]: algorithm = entropy_slope elif method in ["MSLZC", "LZC"]: algorithm = complexity_lempelziv elif method in ["MSPLZC", "PLZC"]: algorithm = copyfunction(complexity_lempelziv, permutation=True) elif method in ["MSSyDyEn", "SyDyEn", "MMSyDyEn"]: algorithm = entropy_symbolicdynamic if method in ["MMSyDyEn"]: coarsegraining = "rolling" else: raise ValueError( "Method '{method}' is not supported. Please use " "'MSEn', 'CMSEn', 'RCMSEn', 'MMSEn', 'IMSPEn'," "'MSPEn', 'CMSPEn', 'MMSPEn', 'IMSPEn'," "'MSWPEn', 'CMSWPEn', 'MMSWPEn', 'IMSWPEn'," "'MSCoSiEn', 'MSIncrEn', 'MSSlopEn', 'MSSyDyEn'" "'MSLZC', 'MSPLZC'" " or 'MSApEn' (case sensitive)." ) # Store parameters info = { "Method": method, "Algorithm": algorithm.__name__, "Coarsegraining": coarsegraining, "Dimension": dimension, "Scale": _get_scales(signal, scale=scale, dimension=dimension), "Tolerance": complexity_tolerance( signal, method=tolerance, dimension=dimension, show=False, )[0], } # Compute entropy for each coarsegrained segment info["Value"] = np.array( [ _entropy_multiscale( signal, scale=scale, coarsegraining=coarsegraining, algorithm=algorithm, dimension=dimension, tolerance=info["Tolerance"], refined=refined, **kwargs, ) for scale in info["Scale"] ] ) # Remove inf, nan and 0 mse = info["Value"][np.isfinite(info["Value"])] # The MSE index is quantified as the area under the curve (AUC), # which is like the sum normalized by the number of values. It's similar to the mean. mse = np.trapz(mse) / len(mse) # Plot overlay if show is True: _entropy_multiscale_plot(mse, info) return mse, info
# ============================================================================= # Internal # ============================================================================= def _entropy_multiscale_plot(mse, info): fig = plt.figure(constrained_layout=False) fig.suptitle("Entropy values across scale factors") plt.title(f"(Total {info['Method']} = {np.round(mse, 3)})") plt.ylabel("Entropy values") plt.xlabel("Scale") plt.plot( info["Scale"][np.isfinite(info["Value"])], info["Value"][np.isfinite(info["Value"])], color="#FF9800", ) return fig # ============================================================================= # Methods # ============================================================================= def _entropy_multiscale( signal, scale, coarsegraining, algorithm, dimension, tolerance, refined=False, **kwargs, ): """Wrapper function that works both on 1D and 2D coarse-grained (for composite)""" # Get coarse-grained signal coarse = complexity_coarsegraining(signal, scale=scale, method=coarsegraining) # For 1D coarse-graining if coarse.ndim == 1: # Get delay delay = 1 # If non-overlapping if coarsegraining in ["rolling", "interpolate"]: delay = scale # Compute entropy return algorithm( coarse, delay=delay, dimension=dimension, tolerance=tolerance, **kwargs, )[0] # 2D coarse-graining (time-shifted, used in composite) else: # CMSE if refined is False: return _validmean( [ algorithm( coarse[i], delay=1, dimension=dimension, tolerance=tolerance, **kwargs, )[0] for i in range(len(coarse)) ] ) # RCMSE else: phis = np.array( [ _phi( coarse[i], delay=1, dimension=dimension, tolerance=tolerance, approximate=False, )[0] for i in range(len(coarse)) ] ) # Average all phi of the same dimension, then divide, then log return _phi_divide([_validmean(phis[:, 0]), _validmean(phis[:, 1])]) def _validmean(x): """Mean that is robust to NaN and Inf.""" x = np.array(x)[np.isfinite(x)] if len(x) == 0: return np.nan else: return np.mean(x)