# Index Distribution Stats
**Level: Advanced** • Back to the [Features Overview](./features_overview.md.html)
Index Distribution Stats answers one question: **how do this index's returns really behave?** On demand, it downloads the index's price history and a matching volatility index, runs a battery of statistical tests, and writes a plain-text report: how fat the tails are, how much a down day moves volatility, how bad a bad day has been, and where the volatility index sits against its own history.
It is a **descriptive** tool. It describes the past; it does not forecast and it does not place or suggest trades.
---
## On this page
- [Opening it](#opening-it)
- [Choosing what to run](#choosing-what-to-run)
- [What the report contains](#what-the-report-contains)
- [Reading the numbers](#reading-the-numbers)
- [Saved reports and the same-day rule](#saved-reports-and-the-same-day-rule)
- [Using it with the AI assistant](#using-it-with-the-ai-assistant)
- [Limits and caveats](#limits-and-caveats)
- [If something goes wrong](#if-something-goes-wrong)
---
## Opening it
On the main toolbar, open the **Data Chart** dropdown and choose **Index Distribution Stats**. The window opens as a tool window; closing it only hides it, so reopening is instant.
- The entry is hidden in **Beginner's mode** (General Settings). Switch that off to see it.
- It does not need an Interactive Brokers connection: the data comes from Yahoo Finance, so it only needs an internet connection. It works while TWS is closed.
- In the current build it has no edition restriction.
## Choosing what to run
| Control | Choices | Notes |
|---|---|---|
| **Symbol** | SPX, NDX, RUT, SPY, QQQ, IWM | Each symbol is paired with a volatility index for the correlation and IV Rank figures: VIX for SPX and SPY, VXN for NDX, RUT, QQQ and IWM. |
| **Bar size** | 1 day, 1 hour | **1 day** uses about the last 5 years of daily bars. **1 hour** uses about the last 3 months of hourly bars. |
| **Run Analysis** | | Starts the run. The status line under the toolbar shows each step (fetching, computing, fitting, building the report). |
| **Copy to Clipboard** | | Copies the whole report text. |
| **Open Folder** | | Opens the folder where reports are saved. |
The daily and hourly reports are separate: they are saved separately and never overwrite each other.
## What the report contains
A run takes a few seconds; most of that is fitting the EGARCH model. The report is plain text with these blocks, in this order:
1. **Header**: symbol, bar size, how many bars were used, and the last bar's open, high, low and close.
2. **EGARCH interpretation**: a fitted EGARCH(1,1,1) volatility model, summarised in plain language.
- *Volatility persistence*: how long a volatility shock lasts, with an estimated half-life.
- *Leverage effect*: whether down days push volatility up more than up days do.
- *Tail heaviness*: how fat the tails are compared with a normal distribution.
- *Mean return*: the drift over the sample, annualised.
3. **Extreme Value Theory (EVT)**: a fit to the worst 8% of losses (the threshold is the 92nd percentile). It reports the **tail index ξ** and the daily loss at several confidence levels, as Value at Risk (VaR) and Expected Shortfall (ES).
4. **Summary, for the whole sample and for the last 100 bars**:
- the number of returns used,
- the **correlation** of the index with its volatility index,
- **skewness** and **kurtosis** (plus kurtosis with the extreme 1% trimmed, for the whole sample),
- **IV Rank** and **IV Percentile** of the volatility index,
- annualised return and annualised volatility.
5. **Key tests and metrics**: the Shapiro-Wilk normality test, VaR (5%) and CVaR, lag-1 autocorrelation of returns and of volatility, and a Student's t fit.
6. **Changes from previous run**: the difference in correlation, skewness, kurtosis, IV Rank and IV Percentile since the last saved run of the same symbol and bar size.
7. **EGARCH parameter tables**, at the very end, for readers who want the model's coefficients.
A few blocks are skipped when there is too little history: the EVT block needs at least 100 returns and 20 exceedances, and the EGARCH block needs at least 250 returns.
## Reading the numbers
These are the plain meanings of the main figures. The report prints its own ✓ and ⚠ flags next to the EGARCH results.
| Figure | What it tells you |
|---|---|
| **Skewness** | Negative means the big moves have been more often down than up. Zero is symmetric. |
| **Kurtosis** | A normal distribution scores 3. Higher means fatter tails: more extreme days than a bell curve predicts. |
| **Shapiro-Wilk p-value** | Below 0.05 means the returns are very unlikely to be normally distributed. For index returns this is the usual outcome. |
| **VaR (5%)** | The daily loss that was exceeded on only 5% of days in the sample. **CVaR / ES** is the average loss on those worst days. |
| **Tail index ξ** (EVT) | Above 0 means a heavy tail. The larger it is, the more extreme the worst days can be relative to normal ones. |
| **Correlation with the volatility index** | Usually negative for equity indexes: volatility rises when the index falls. A less negative value means the relationship has weakened. |
| **IV Rank** | Where the volatility index's latest close sits between the lowest and highest close in the window (0 to 100). |
| **IV Percentile** | The share of closes in the window that were at or below the latest close (0 to 100). It can differ a lot from IV Rank when there was one spike. |
| **Lag-1 autocorrelation of volatility** | Positive means volatile days tend to follow volatile days (volatility clustering). |
The **Total** block uses the full window and the **Last 100** block uses only the latest 100 bars. A big gap between the two says the recent behaviour differs from the long run, which is usually the interesting part.
## Saved reports and the same-day rule
Each report is saved as a text file in the **StatCalcs** folder inside your SOAP2 data folder, named `{Symbol} Stats {1d or 1h} {yyyy-MM-dd}.txt` (the date is the latest bar's date). **Open Folder** takes you there.
- The report is meant to be run **once per trading day**. If the file for the latest bar's date already exists, **Run Analysis shows the saved copy** instead of recomputing. To force a recalculation, delete that day's file first.
- A fresh run also saves a small summary of its headline figures for that symbol and bar size. The next run uses it for the **Changes from previous run** block.
## Using it with the AI assistant
If you have connected Claude (see the [AI Assistant guide](./ai_assistant_user_guide.md.html)), a market analysis request can run the same computation and read its result, so you do not have to open this window first. The window and the assistant share the same run, so they never compute the same report twice at once. If you press **Run Analysis** while the assistant is running it, the status line says it is already running.
## Limits and caveats
- **Yahoo Finance data, not Interactive Brokers.** Prices come from a free public source, so gaps, adjustments or a late last bar are possible. For today's figures the report reflects the latest bar Yahoo has published.
- **Hourly reports cover only about 3 months.** That is a short sample, so treat tail estimates (EVT, kurtosis) with extra caution. The hourly report labels its figures per bar (not per day) and annualises them with the number of bars per year, measured from the data (about 7 bars a day, so roughly 1,764 a year). Because the sample is only 3 months, the annualised figures are a rough guide.
- **It is a description of the past.** A fat tail or a negative skew in the sample does not tell you what tomorrow will do.
- **Minimum history:** at least 30 daily returns (20 hourly) are needed, otherwise the run stops with a message.
## If something goes wrong
| Message | Meaning and fix |
|---|---|
| *Failed to fetch ... data from Yahoo Finance* | No internet connection, or Yahoo did not answer. Check the connection and try again. |
| *Not enough ... history returned* | Yahoo returned too few bars to compute the statistics. Try again later or pick another bar size. |
| *Already running (started elsewhere, e.g. the AI assistant)* | A run is already in progress. Wait for it to finish. |
| *Done (report file could not be saved)* | The report is on screen and can be copied, but the file could not be written to the StatCalcs folder. Check the folder's permissions. |
| *Showing the saved copy* | Today's report already exists, so it was reused. Delete the file to recompute. |
Related: [Data Chart](./datachart_indicators_user_guide.md.html) (the dropdown that holds this entry), [Features Overview](./features_overview.md.html), [Troubleshooting & Support](./troubleshooting_support.md.html)