> 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/incremental-differences.md).
# Incremental differences
Properties of the 1-point incremental differences of the time series.
*catch22* contains **2** features which are each based on the properties of the 1-point incremental differences of the time series. Select one of the cards below to discover more information:
***
## 1. `high_fluctuation`
### What it does
[`high_fluctuation`](#user-content-fn-1)[^1] computes the proportion of difference magnitudes that are greater than 4% of the standard deviation of the time series.
This feature will give low values to series that have periods in which the series stays approximately constant (within $$0.04\sigma$$), and high values to series that do not (e.g., they 'jump around a lot' from point to point). Note that the threshold of $$0.04\sigma$$ is small: most noisy or irregular time series have values close to 1 (e.g., about 0.98 for uncorrelated Gaussian noise), so this feature mainly distinguishes smooth or finely sampled time series (which have lower values) from everything else.
This is a common statistic to measure about heart rate time series, cf. "[*The pNNx files: re-examining a widely used heart rate variability measure*](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC1767394/)*"*, J.E. Mietus et al., Heart 88(4) 378 (2002).
In *hctsa*, this feature is the `pnn40` output of `MD_pNN(x_z)`. For a constant time series, which cannot be *z*-scored, it returns 0 by default (with masking; earlier versions returned `NaN`).
{% hint style="info" %}
**Changes in v1.0**: The values are unchanged, but the long name changed from `MD_hrv_classic_pnn40` to `MD_pNN_pnn40`. *hctsa*'s `MD_hrv_classic` no longer computes pnn40 on the *z*-scored series (it now uses thresholds relative to the spread of the increments), so the earlier name no longer gives this feature in *hctsa*.
{% endhint %}
{% tabs %}
{% tab title="Example 1: Rossler Attractor" %}
The[ Rossler attractor](https://en.wikipedia.org/wiki/R%C3%B6ssler_attractor) time series below has many near-constant stretches (Just 14.5% of all step increments are larger than $$0.04\sigma$$), yielding a **low value** for this statistic:
### **Feature output:** `high_fluctuation`**`=`****`0.145`**
{% endtab %}
{% tab title="Example 2: Stock opening prices" %}
These log returns of opening prices of a stock, on the other hand, fluctuate a lot more: 95% of successive increments exceed the $$0.04\sigma$$ threshold, yielding a **high value** for this statistic:
### **Feature output:** `high_fluctuation`**`=`****`0.952`**
{% endtab %}
{% endtabs %}
***
## 2. **`whiten_timescale`**
### What it does
[`whiten_timescale`](#user-content-fn-2)[^2] computes:
1. The set of incremental differences between successive pairs of time-series values (imagining this as the set of residuals from a naive 1-point forecast).
2. Computes the first zero-crossing of the autocorrelation function for the residuals, `tau_resid`, and for the original time series, `tau`. Each crossing is linearly interpolated between the two lags either side of it (as for [`acf_timescale`](https://time-series-features.gitbook.io/catch22/information-about-catch22/feature-descriptions/pages/vlmWggwIfUzwmDZ4wS4V#id-1.-acf_timescale)), so it is generally not an integer.
3. Returns the ratio of these two values, `tau_resid/tau`.
In *hctsa*, this feature is the `taurat` output of `FC_LocalSimple(x_z,'mean',1)`. For a constant time series, which cannot be *z*-scored, it returns 0 by default (with masking).
{% hint style="info" %}
**Changes in v1.0**: The long name changed from `FC_LocalSimple_mean1_tauresrat` to `FC_LocalSimple_mean1_taurat`, following *hctsa*. Before v1.0, each zero-crossing was the integer lag at which the autocorrelation function first became non-positive (not interpolated), so the feature was a ratio of two integers. Values therefore change for all time series, and the example outputs below were computed with an earlier version of *catch22* (e.g., Example 1 is the integer ratio 1/15). Earlier versions returned `NaN` for a constant time series.
{% endhint %}
{% tabs %}
{% tab title="Example 1" %}
Here's an example of a time series, where the autocorrelation function (black, lower plot) decays slowly due to slower trends in the time series (black, upper plot), whereas the incremental differences (blue in the upper plot) are much noisier, leading to a rapid drop of the autocorrelation function, and reduction in the first zero-crossing from 15 -> 1:
### **Feature output: `whiten_timescale =`****`0.0667`**
{% endtab %}
{% tab title="Example 2" %}
By contrast, in this [AR(2)](https://en.wikipedia.org/wiki/Autoregressive_model) time series, the increments are still highly autocorrelated, and we end up with a value of the feature near 1:
### **Feature output: `whiten_timescale =`****`0.833`**
{% endtab %}
{% endtabs %}
***
[^1]: **Naming info:** Short name `high_fluctuation`; long name `MD_pNN_pnn40` (before v1.0: `MD_hrv_classic_pnn40`). Reproduced in *hctsa* by `MD_pNN(x_z).pnn40`; it is not a registered *hctsa* feature, so its long name is the one that *hctsa*'s naming convention gives this call.
[^2]: **Naming info:** Short name `whiten_timescale`; long name `FC_LocalSimple_mean1_taurat` (before v1.0: `FC_LocalSimple_mean1_tauresrat`), matching the *hctsa* feature of the same name. It is the `taurat` output of running the code `FC_LocalSimple(x_z,'mean',1)` in *hctsa.*
---
# 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/incremental-differences.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.
