pyhctsa.operations.symbolic.surprise

pyhctsa.operations.symbolic.surprise(y, what_prior='dist', memory=0.2, num_groups=3, coarse_grain_method='quantile', num_iters=500, random_seed=0)

Quantifies how surprised you would be of the next data point given recent memory.

Coarse-grains the time series, turning it into a sequence of symbols of a given alphabet size (num_groups), and quantifies measures of surprise of a process with local memory of the past memory values of the symbolic string. For each test point, the ‘information gained’ (log(1/p)) is estimated using expectations calculated from the previous memory samples. The test points are every point with a full memory before it, or, for long series, a fixed subsample of num_iters of them.

Parameters:
y : array-like

The input time series.

what_prior : {'dist', 'T1', 'T2'}, optional

The type of information to store in memory:

  • ’dist’: the values of the time series in the previous memory samples (default),

  • ’T1’: the one-point transition probabilities in the previous memory samples,

  • ’T2’: the two-point transition probabilities in the previous memory samples.

Default is 'dist'.

memory : float, optional

The memory length (either number of samples, or a proportion of the time-series length if between 0 and 1). Default is 0.2.

num_groups : int or str, optional

The number of groups to coarse-grain the time series into (2 for ‘updown’), or, for ‘embed2quadrants’/’embed2octants’, the time delay of the embedding: a number of samples, 'ac1e' (the floor of the first 1/e crossing of the autocorrelation function), 'mi' (the smaller of the first minimum of the Kraskov automutual information and the ‘ac1e’ delay; see pyhctsa.utils.get_tau()), or 'tau' (the first zero-crossing of the autocorrelation function, kept for backward compatibility). Default is 3.

coarse_grain_method : {'quantile', 'diff', 'updown', 'embed2quadrants', 'embed2octants'}, optional

The coarse-graining or symbolization method (see coarse_grain()):

  • ’quantile’: equiprobable alphabet by value of each time-series datapoint (default),

  • ’diff’: equiprobable alphabet by the value of the incremental changes in the time series (not a literal sign split; called ‘updown’ before it was renamed in hctsa),

  • ’updown’: a binary split by the sign of each increment (requires num_groups=2; not equiprobable),

  • ’embed2quadrants’: 4-letter alphabet of the quadrant each data point resides in a 2D embedding space,

  • ’embed2octants’: 8-letter alphabet of the octant each data point resides in.

Default is 'quantile'.

num_iters : int, optional

The number of test points to use. If there are at most 2 * num_iters points with a full memory before them, all of them are used; otherwise num_iters of them, spread evenly by a golden-ratio sequence (deterministic, and free of aliasing with periodic series). Default is 500.

random_seed : int, optional

Ignored: the test points are deterministic. Kept so that existing calls still run.

Returns:

Summaries of the series of information gains, with keys:

  • ’min’, ‘max’, ‘median’, ‘mean’, ‘sum’, ‘std’, ‘lq’, ‘uq’: the minimum (of the nonzero values), maximum, median, mean, sum, standard deviation, and lower and upper quartiles of the information gain over the test points,

  • ’propUnseen’: the proportion of test points whose antecedent pattern (the current symbol itself for ‘dist’; the preceding 1 or 2 symbols for ‘T1’/’T2’) was never observed in the memory window (always 0 for ‘dist’),

  • ’effectSize’: |mean - 1| / std, the standardized distance of the mean information gain from 1 nat,

  • ’tstat’: effectSize * sqrt(number of test points).

All NaN if there is no test point (the series is no longer than memory) or if the coarse-graining is undefined (the embedding delay for ‘embed2quadrants’/’embed2octants’ cannot be determined: a constant series, or 'ac1e' for a series whose autocorrelation function never falls to 1/e). effectSize and tstat are NaN if the information gain does not vary (its standard deviation at rounding level relative to its mean, e.g. for a perfectly periodic series).

Return type:

dict