pyhctsa.operations.entropy.dispersion_entropy

pyhctsa.operations.entropy.dispersion_entropy(y, m=2, c=6, tau=1, mapping_how='ncdf')

Dispersion entropy of a time series.

Maps the time series onto c amplitude classes, replaces each run of m values (spaced tau samples apart) by the sequence of classes it visits (a ‘dispersion pattern’), and returns the Shannon entropy of the resulting pattern distribution. Port of hctsa’s EN_DispEn.

Unlike permutation entropy (permutation_entropy()), which records only the rank ordering within each embedding vector and so discards amplitude information entirely ([1, 2, 3] and [1, 2, 300] are the same pattern), dispersion entropy assigns each point to an amplitude class first, so the size of an excursion, not just its direction, shapes the symbol sequence. It is also markedly cheaper than sample entropy and degrades more gracefully on short, noisy series.

The fluctuation-based variant is also returned. It symbolizes the differences between successive classes rather than the classes themselves, and so responds to the size of class-to-class changes rather than to absolute amplitude level.

References

Parameters:
y : array-like

The input time series.

m : int, optional

The embedding dimension. The number of possible patterns grows as c**m, so m must stay small for the pattern frequencies to be estimable. Default is 2.

c : int, optional

The number of amplitude classes (must be at least 2). Default is 6.

tau : int or str, optional

The time delay: an integer, or a rule understood by get_tau() ('ac', 'ac1e', 'mi'). Default is 1.

mapping_how : {'ncdf', 'linear'}, optional

How to map the time series onto (0, 1) before classifying:

  • 'ncdf': the normal cumulative distribution function with the series’ own mean and standard deviation (the mapping the method was introduced with; a linear mapping assigns most points to a few classes whenever the maximum or minimum is far from the median, so a single outlier can collapse the symbolization).

  • 'linear': a min-max rescaling onto [0, 1] (outlier-sensitive).

Default is 'ncdf'.

Returns:

A dictionary with:

  • ’dispEn’: the dispersion entropy (nats),

  • ’normDispEn’: ‘dispEn’ normalized by its maximum possible value, log(c**m),

  • ’fDispEn’: the fluctuation-based dispersion entropy (nats; NaN for m = 1),

  • ’normFDispEn’: ‘fDispEn’ normalized by log((2c-1)**(m-1)) (NaN for m = 1).

A constant series (all values equal, up to floating-point rounding at their own magnitude: a range of at most four units in the last place of max(abs(y))) has a single dispersion pattern, so all four values are 0 (the fluctuation-based ones are NaN for m = 1, as always). NaN (scalar) if the delay cannot be determined or the series is too short for the embedding (fewer than 5 embedding vectors).

Return type:

dict or float