pyhctsa.operations.entropy.sample_entropy

pyhctsa.operations.entropy.sample_entropy(y, m=2, r=None, pre_process_how=None, tau=1, theiler_win=0)

Compute Sample Entropy (SampEn) of a time series.

This function calculates SampEn for embedding dimensions from 0 to m. The implementation uses the PhysioNet C code (sampen.c by Doug Lake) [1] for efficiency and accuracy, extended to delay templates and a Theiler window. Can specify to first apply an incremental differencing of the time series thus yielding the ‘Control Entropy’ [2].

With the defaults (tau = 1, theiler_win = 0) this is standard SampEn: templates of m consecutive values, and every pair of distinct templates compared. A delay tau uses templates (y_t, y_{t+tau}, ..., y_{t+(m-1)tau}) at every start time t, which measures regularity over a span set by the series’ own timescale rather than the sampling interval (time-delayed SampEn; Kaffashi et al. [3]). A Theiler window W [4] leaves out the pairs of templates whose start times differ by W samples or fewer. With a delay, those pairs are near-copies of each other on an oversampled series (each coordinate has barely moved), so they match whatever the dynamics, and their share of the matches grows with the template length; this biases SampEn downwards, more so at finer sampling. Excluding pairs closer than the delay (theiler_win = ['ac1e', 1] with tau = 'ac1e') removes the bias. This exclusion is not part of published SampEn or time-delayed SampEn; it follows the practice for correlation sums [4], of which SampEn’s match counts are an instance.

References

Parameters:
y : array-like

Input time series.

m : int, optional

Maximum embedding dimension. Default is 2.

r : float, optional

Similarity threshold. If None, set to 0.1 * std(y). Default is None.

pre_process_how : str, optional

Preprocessing method:

  • ’diff1’: Use first differences

  • None: No pre-processing.

Default is None.

tau : int or str, optional

The template delay: an integer number of samples, or a rule for get_tau() (e.g. 'ac1e'), applied to the analysed series (after any differencing). Default 1 (consecutive values). All outputs are NaN when a rule cannot set the delay.

theiler_win : int, float or [str, number], optional

The Theiler window W: pairs of templates whose start times differ by W or fewer samples are not compared. Any specification theiler_window() accepts, resolved on the analysed series, e.g. ['ac1e', 1] (W = the 1/e autocorrelation time). Default 0 (only a template’s comparison with itself is left out, as in standard SampEn). All outputs are NaN when the window cannot be set.

Returns:

Dictionary containing:

  • ’sampen{m}’: Sample entropy for each m from 0 to M

  • ’quadSampEn{m}’: Quadratic sample entropy for each m

  • ’meanchsampen’: Mean change in sample entropy values

sampen{k} (and quadSampEn{k}) is NaN when templates of length k match but none of length k + 1 do (for sampen0, when no two values are within r): the estimate is then infinite, so the data cannot support it at this k, r and length. It is also NaN when no templates of length k match.

Return type:

dict

Notes

SampEn estimates an entropy rate at the resolution r, so it depends on the shape of the value distribution as well as on the dynamics. Two equally unpredictable iid processes can differ: discrete or heavy-tailed values put more pairs within r than Gaussian values do, so iid binary or Student-t noise gives a lower SampEn (reads as more regular) than iid Gaussian noise at the same r. This follows from the definition, not from the estimator; compare SampEn across series with similar value distributions, or use sample_entropy_ranked(), which computes it on ranks.