> 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/extreme-event-timing.md).
# Extreme event timing
The DN\_OutlierInclude features measure the timing of extreme events relative to the start and end of the time series.
*catch22* contains two features based on the `DN_OutlierInclude` function in hctsa*:*
* `outlier_timing_pos` (the *hctsa* feature `DN_OutlierInclude_p_001_mdrmd`) i.e, the `mdrmd` output from running `DN_OutlierInclude(x_z,'pos',0.01)` in *hctsa.*
* `outlier_timing_neg` (the *hctsa* feature `DN_OutlierInclude_n_001_mdrmd)` i.e., the `mdrmd` output from running`DN_OutlierInclude(x_z,'neg',0.01)` in *hctsa*).
## What these features do
These features involve the following steps:
1. *z*-score the input time series.
2. Initialise an equally spaced set of thresholds, in increments of 0.01 (i.e., 1% of the standard deviation, as the series is *z*-scored), from zero to the maximum value of the time series, in the case of `outlier_timing_pos` (or from 0 to the minimum value of the time series in the case of `outlier_timing_neg`). In this way, a set of increasingly \`extreme' deviations from the mean (either deviations above-the-mean or below-the-mean) are analysed across the loop in Step (3).
3. At each threshold set in Step (2):
1. Determine the time points in which the time series is \`over-threshold'.
2. Compute the median index of all such over-threshold time points, as `rmd` .
3. For interpretation, and to appropriately compare time series of different lengths, we then linearly re-scale `rmd` such that a median right in the middle of the time series, at index `N/2`, maps to 0, a value at the end of the time series, at index `N`, maps to 1, and a value at the start of the time series, index `1`, maps to a -1.
4. The final statistic is the median of the `rmd` values across thresholds. Only thresholds that are still exceeded by more than 2% of the time points on that side of the mean (and by at least two points) are included, so the most extreme thresholds, at which very few points are over threshold, are discarded.
These features are unchanged in v1.0. For a constant time series, which cannot be *z*-scored, both features return 0 by default (with masking; earlier versions returned `NaN`).
***
## What it measures
These statistics measure whether over-threshold events (either positive or negative deviations from the mean) tend to be positioned relatively near the start of the time series (output values near -1), approximately equally likely to be anywhere through the time series (output values near 0), or more likely to be near the end of the time series (output values near 1). These features thus capture something related to the stationarity of over-threshold events.
To give an intuition, below we plot some examples of how `rmd` at a fixed threshold (80% the maximum positive deviation) for the case of `outlier_timing_pos` ( note that the full statistic takes the median of `rmd` across a range of thresholds, as described above).
Consider these examples:
{% tabs %}
{% tab title="Example 1" %}
Time series, that have extreme events (red dots, relative to the threshold, shown as a dashed red line) distributed similarly across time, will yield values close to **zero** for this statistic (vertical blue line). For example these:
{% endtab %}
{% tab title="Example 2" %}
Time series like these, for which large deviations from the mean tend to occur nearer to the end of the time series, will have values closer to **1:**
{% endtab %}
{% tab title="Example 3" %}
Time series like these, for which large deviations from the mean tend to occur nearer the start of the time series, will have values nearer to **-1:**
{% endtab %}
{% endtabs %}
***
***
---
# 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/extreme-event-timing.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.
