pyhctsa.operations.nonlinearity.fnn¶

pyhctsa.operations.nonlinearity.fnn(y, tau=1, maxm=10, theiler_win=('ac', 1), just_best=True, bestp=0.05, escape_factor=None)¶

How the fraction of false nearest neighbors falls as the embedding dimension increases.

Uses TISEAN’s false_nearest (run in process; see pyhctsa.toolboxes.Tisean_3_0_1.tisean.false_nearest()). For each embedding dimension m = 1, ..., maxm, every point’s nearest neighbor (maximum norm, outside the Theiler window in time) is found; the neighbor is false if, when one more coordinate is added, the two points move apart by more than escape_factor times their distance. For a deterministic system the fraction of false neighbors falls toward zero once the embedding dimension is large enough; for noise it stays high. Neighbors farther apart than the standard deviation of the data divided by the escape factor are skipped, so the fraction rests only on the points that found a neighbor within that range; at high dimensions these can be few.

Exact ties (repeated values, e.g. quantized data or periodic orbits) are resolved so that the result does not depend on rounding or on the order in which neighbors are searched: distances (in the data rescaled to [0, 1]) within 1e-12 of each other count as equal, a pair closer than that is a repeated point and not a neighbor, a neighbor is false if the extra coordinate separates the pair by more than escape_factor times their distance plus 1e-12, and when several neighbors are equally near, a point contributes the fraction of them that are false (the expected outcome of choosing one at random). Where the nearest neighbor is unique this is the published test (Hegger, Kantz & Schreiber 1999, Chaos 9, 413, https://doi.org/10.1063/1.166424).

A dimension is ruled out when its fraction is at least the threshold and rests on at least ceil(3 / threshold) points (pyhctsa.toolboxes.Tisean_3_0_1.tisean.fnn_min_count(); 60 at 0.05): with fewer points, even a fraction of zero does not show at the 95% level that the true fraction is below the threshold (if none of n points has a false neighbor, the upper confidence bound on the true fraction is about 3/n), so such a dimension is neither accepted nor ruled out.

The series is embedded with delay tau: the point at time t is (y[t], y[t + tau], ..., y[t + (m - 1) * tau]).

Parameters:¶

y : array-like¶

Input time series.

tau : int or str, optional¶

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

maxm : int, optional¶

The maximum embedding dimension. Default is 10.

theiler_win=('ac', 1)¶

The Theiler window (see pyhctsa.utils.theiler_window()). Default is ['ac', 1].

just_best : bool, optional¶

If True, return only an embedding dimension: the smallest dimension not ruled out by the test (see Returns). Default is True.

bestp : float, optional¶

The fraction of false neighbors defining the embedding dimension when just_best. Default is 0.05.

escape_factor : float, optional¶

TISEAN’s -f: a neighbor is false if its distance grows by more than this factor when a dimension is added. None (the default) is TISEAN’s own default, 2. (BF_Embed’s false-nearest-neighbors choice of dimension uses 5.)

Returns:¶

If just_best, the embedding dimension: the smallest dimension not ruled out by the test. This is the first dimension at which the fraction of false nearest neighbors is below bestp on enough points, or at which too few points found a neighbor for the fraction to decide; if neither happens, one more than the largest dimension TISEAN computed (maxm + 1 when every dimension up to maxm was computed; one more than the last when TISEAN stopped early, having no neighbors left within its search range). Unless the fraction fell below bestp, the value is a lower bound: every smaller dimension was tested and ruled out. It is not limited by the length of the series (the 'fnn' choice of dimension for another algorithm, _embedding_params(), is). Otherwise a dict with, for i = 1, ..., maxm, pfnn_i (the fraction of false nearest neighbors) and nHood2_i (the typical, root-mean-square, distance from a point to its nearest neighbor; NaN at a dimension for which TISEAN found too few neighbors); minpfnn, meanpfnn, stdpfnn, maxnHood2, meannHood2; dim09, dim08, …, dim01, dim005 (the embedding-dimension estimate at a threshold p of 0.9, 0.8, …, 0.1, 0.05: the smallest dimension not ruled out, where a dimension is ruled out if its fraction of false nearest neighbors is at least p and rests on at least ceil(3 / 0.05) = 60 points (one minimum count for all ten, so they use the same dimensions and never decrease as p falls); if no dimension up to maxm qualifies, one more than the last dimension tested, a lower bound; not limited by the length of the series); max1stepchange (the largest absolute change in the fraction between consecutive dimensions), mdrop (the mean change per added dimension) and pdrop (the fraction of decreasing steps minus the fraction of increasing steps). NaN if the series is too short (N < 10), the time delay or Theiler window cannot be set, or TISEAN gives no output (constant series, or a delay too long for the series).

Return type:¶

float or dict