> For the complete documentation index, see [llms.txt](https://time-series-features.gitbook.io/catch22/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://time-series-features.gitbook.io/catch22/information-about-catch22/feature-descriptions/nonlinear-autocorrelation.md). # Nonlinear autocorrelation These features capture nonlinear autocorrelation properties of a time series. *catch22* contains **2** features which each capture some aspect of the nonlinear autocorrelation properties of a time series. Select one of the cards below to discover more information:


	`trev`		#id-1.-trev
	`ami2`		#id-2.-ami2

*** ## 1. `trev` ### What it does [`trev` ](#user-content-fn-1)[^1]computes the average across the time series of the cube of successive time-series differences. It will be close to zero for time series for which the distribution of successive decreases in the time series matches the distribution of successive increases, but will be positive if increases tend to be larger in magnitude and negative if decreases tend to be larger in magnitude. It is computed as: $$ \langle (x\_{i+1} - x\_i)^3\rangle\_t,, $$ for time-series values, *x*, averaged across all possible time points*, t* (i.e., from index 1 to N-1, for a time series of length *N*). It is based on a statistic used in nonlinear time-series analysis, cf. [Surrogate time series](https://doi.org/10.1016/S0167-2789$00$00043-9), Schreiber and Schmitz, *Physica D*, **142:** 346 (2000). The original *hctsa* implementation is the code `CO_trev(x_z,1)` , for a *z*-scored time series, `x_z` (the `num` output). This feature is unchanged in v1.0. For a constant time series, which cannot be *z*-scored, it returns 0 by default (with masking; earlier versions returned `NaN`). To give an intuition, below we plot some examples of the outputs of this feature for different scenarios: {% tabs %} {% tab title="Example 1: Chua Map" %} This [Chua map time series](https://www.comp-engine.org/#!visualize/d34839c1-3872-11e8-8680-0242ac120002) has increments that are approximately symmetric (blue histogram), as are the cubic increments (orange histogram), and so this statistic has a value (the mean of the orange distribution) of approximately zero:

### **Feature output: `trev =`**`-0.021` {% endtab %} {% tab title="Example 2: Simple Piecewise linear chaotic flow" %} This[ simple flow ](https://www.comp-engine.org/#!visualize/03552b98-3871-11e8-8680-0242ac120002)has a multi-modal distribution of successive increments (blue), with an asymmetry towards larger increases compared to smaller decreases. This is accentuated after taking a cube (orange), yielding a positive value of this statistic:

### **Feature output: `trev =`**`1.083` {% endtab %} {% tab title="Example 3: Lozi Map" %} This[ Lozi map](https://www.comp-engine.org/#!visualize/8d547ec4-3872-11e8-8680-0242ac120002) is an example of the opposite behaviour: time-series decreases can be sudden and large in magnitude, whereas increases are relatively gradual. This leads to an asymmetry towards large negative values, leading to a negative value for this statistic:

### **Feature output: `trev =`**`-3.497` {% endtab %} {% endtabs %} *** ## 2. `ami2` ### What it does [`ami2`](#user-content-fn-2)[^2] is a nonlinear version of the autocorrelation function: using a nonlinear correlation metric (mutual information) instead of a conventional linear correlation metric, evaluated using a histogram with 5 bins and at a time delay *τ* = 2 (the `ami2` output of the *hctsa* code `CO_HistogramAMI(x_z,1:5,'even',5)`). The 5 bins have equal widths and span the range of the time series, from its minimum to its maximum (with edges placed as for [`mode_5`](/catch22/information-about-catch22/feature-descriptions/distribution-shape.md), so that a value lying exactly on an edge always falls in the upper bin). The joint distribution of the $$n = N - 2$$ pairs $$(x\_t, x\_{t+2})$$ is estimated as a 5 × 5 histogram, and the marginal distributions are obtained by summing it across rows and columns. The mutual information is then estimated as $$\sum\_{ij} p\_{ij} \log\left\[p\_{ij} / (p\_i, p\_j)\right]$$, using the natural logarithm. As in *hctsa*, this estimate is corrected for its upward bias (the Panzeri–Treves, or Miller–Madow, correction) by subtracting $$(M\_{xy} - M\_x - M\_y + 1)/(2n)$$, where $$M\_{xy}$$ is the number of occupied cells of the joint histogram, and $$M\_x$$ and $$M\_y$$ are the numbers of occupied bins of the two marginal histograms. When it cannot be computed (for a constant time series, which cannot be *z*-scored, or a series too short to contain a pair two samples apart), the feature returns 0 by default (with masking). {% hint style="info" %} **Changes in v1.0**: The long name changed from `CO_HistogramAMI_even_2_5` to `CO_HistogramAMI_even_5bin_ami2`, and the estimate now matches the *hctsa* call above, with two differences from earlier versions: * Earlier versions widened the range by 0.1 beyond the minimum and the maximum, so the 5 equal-width bins spanned \[min − 0.1, max + 0.1]; the bins now span \[min, max]. * Earlier versions did not apply the bias correction. Values change for almost all time series (typically by a few percent). Earlier versions returned `NaN` for a constant time series. The example outputs below were computed with an earlier version of *catch22*. {% endhint %} Explore the tabs below to see examples of the typical outputs of this feature for various time series: {% tabs %} {% tab title="Example 1: Chaotic Web Map" %} This feature gives **high** values to time series like this [Chaotic Web map](https://www.comp-engine.org/#!visualize/23409069-3876-11e8-8680-0242ac120002):

which has clear dependence structure of the time-series value at the current point, $$x\_t$$, and the value two time points ahead, $$x\_{t+2}$$ *,* yielding a high value for this feature of 1.25:

### **Feature output: `ami2 =`**`1.250` {% endtab %} {% tab title="Example 2: Tent Map" %} This [Tent map](https://www.comp-engine.org/#!visualize/13df59a3-3873-11e8-8680-0242ac120002) also has a clear (nonlinear) dependence of present time-series value with that two-steps into the future (and a moderate value of this feature):

as seen in its embedding:

### **Feature output: `ami2 =`**`0.473` {% endtab %} {% tab title="Example 3: Heart Rhythm" %} This feature gives a moderate value for this heart rhythm ECG [time series](https://www.comp-engine.org/#!visualize/ab05d12c-3878-11e8-8680-0242ac120002):

and its embedding:

### **Feature output:** `ami2 =``0.25` {% endtab %} {% tab title="Example 4: Earthquake" %} We obtain a low value for this [earthquake time series](https://www.comp-engine.org/#!visualize/2df74240-3874-11e8-8680-0242ac120002):

and embedding:

### **Feature output:** `ami2 =``0.019` {% endtab %} {% endtabs %} *** [^1]: **Naming info**: Short name `trev`; long name `CO_trev_1_num` (unchanged in v1.0), matching the *hctsa* feature of the same name. Reproduced in *hctsa* by `CO_trev(x_z,1).num`. [^2]: **Naming info**: Short name `ami2`; long name `CO_HistogramAMI_even_5bin_ami2` (before v1.0: `CO_HistogramAMI_even_2_5`). Reproduced in *hctsa* by `CO_HistogramAMI(x_z,1:5,'even',5).ami2`; it is not a registered *hctsa* feature, so its long name is the one that *hctsa*'s naming convention gives this call. The earlier name followed an older *hctsa* naming scheme in which `CO_HistogramAMI_even_2_5` denoted a different feature (2 bins, at lag 5); *catch22* has always computed 5 bins at lag 2. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://time-series-features.gitbook.io/catch22/information-about-catch22/feature-descriptions/nonlinear-autocorrelation.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.