pyhctsa.operations.entropy.distribution_entropy

pyhctsa.operations.entropy.distribution_entropy(y, hist_or_ks='hist', num_bins=10, olremp=0)

Distributional entropy.

Estimates entropy from the distribution of a data vector. The distribution is estimated either using a histogram (equal-width bins spanning the data, see bf_hist_edges()) with numBins bins, or as a kernel-smoothed distribution using a Gaussian kernel with a normal-reference bandwidth (see bf_ks_density()).

An optional additional parameter can be used to remove a proportion of the most extreme positive and negative deviations from the mean as an initial pre-processing step.

Parameters:
y : array-like

The input time series.

hist_or_ks : str

Whether to use a histogram (‘hist’) or kernel-smoothed (‘ks’) distribution. Default is 'hist'.

num_bins : int or str or float or None, optional

  • (for ‘hist’): an integer, the number of equal-width bins; or the name of a rule for the number of bins (‘sturges’, ‘fd’, ‘sqrt’, ‘auto’; written out as formulae in bf_hist_edges(), so not NumPy’s histogram rules of the same names, which round the bin width to a ‘nice’ value);

  • (for ‘ks’): a positive real number, the bandwidth (standard deviation of the Gaussian kernel) of the kernel density estimate; or empty ('' / None) for the default bandwidth, the normal-reference rule sigma * (4 / (3 N)) ** (1/5) with sigma = median(|y - median(y)|) / 0.6745 (see bf_ks_density()).

Default is 10.

olremp : float, optional

The proportion of outliers at both extremes to remove. (e.g., if olremp = 0.01; keeps only the middle 98% of data; 0 keeps all data. This parameter ought to be less than 0.5, which keeps none of the data). Default is 0.

Returns:

Estimate of entropy from the distribution (in nats), or, if olremp is nonzero, the entropy of the full time series minus that of the trimmed time series. NaN if everything is removed by the trimming, or if the data (after trimming) are constant, for which the differential entropy is not defined.

Return type:

float

Notes

The ‘ks’ density is evaluated on a 200-point grid spanning the 0.1% to 99.9% quantiles of y plus a 10% margin, converted to probability mass per grid cell and renormalized (NaN if those quantiles coincide). A fixed absolute bandwidth makes the estimate drift with the length of the series, so the automatic selection is preferable.