pyhctsa.operations.information.multivariate_ami

pyhctsa.operations.information.multivariate_ami(y, tau_method='ac', est_method='gaussian', extra_param=None)

Multivariate automutual information, I(x_t; x_{t-tau}, x_{t-2tau}).

Port of hctsa’s IN_MultivariateAMI. Measures how much information the past two points (spaced tau apart, with tau estimated from the series’ own autocorrelation structure) jointly carry about the present, and, via the synergy output, whether that joint information exceeds or falls short of the sum of the pairwise automutual informations at tau and 2*tau individually. Positive synergy means the two lagged points are jointly more informative than either alone would suggest (interaction structure); negative synergy means x_{t-2tau} is mostly redundant with x_{t-tau} once you already know it.

References

Parameters:
y : array-like

The input time series (expected z-scored).

tau_method : int or {'ac', 'ac1e', 'mi'}, optional

How to select the time delay, tau (see get_tau()):

  • 'ac' (default): the first zero-crossing of the autocorrelation function;

  • '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;

  • a fixed positive integer.

est_method : {'gaussian', 'kraskov1', 'kraskov2'}, optional

The estimator of the mutual information: 'gaussian' (default), the closed form via the multiple correlation coefficient, -0.5*log(1 - R^2) (fast, but blind to nonlinear/non-Gaussian structure), or the nonparametric Kraskov-Stoegbauer-Grassberger estimators 'kraskov1' and 'kraskov2'.

extra_param : int or str, optional

The number of nearest neighbors for the Kraskov estimators (default 4).

Returns:

  • tau: the time delay used (in samples);

  • multiAMI: the information that x_{t-tau} and x_{t-2tau} jointly carry about x_t (in nats; for the Gaussian estimator NaN if the two lagged copies are numerically collinear, and 1 - R^2 is floored at 1e-12, so at most 13.8 nats);

  • ami_2tau: the automutual information between x_{t-2tau} and x_t (in nats);

  • ami_tau: the automutual information between x_{t-tau} and x_t (in nats);

  • synergy: multiAMI - ami_tau - ami_2tau.

NaN (instead of a dict) is returned if tau cannot be determined or fewer than 20 embedded points remain.

Return type:

dict or float

Notes

For the Kraskov estimators, a series with many repeated values gets tiny, reproducible tie-breaking jitter first (see automutual_info()).