Level Significance
Calculate how unusual the latest value of every series is: its percentile in the series’ own history and the last dates the series was at least as high (“the highest since”) and at least as low (“the lowest since”), next to its change since the first observation and the highest and lowest values of the range with their dates and the change from them.
Where get_move_significance (Risk) measures how unusual a move is, this measures how unusual a level is, which is the question for rates and macroeconomic series: a 10-year yield of 5.13% is “the highest since May 2002” when no month since then was as high, and an unemployment rate can be the lowest in decades without any single large move. Through the Toolkit it measures the prices of the tickers (“the highest close since”); with Econometrics(data=...) any series, such as the interest rates, inflation or unemployment of Economics and the yield curves of FixedIncome.
The formula is as follows:
\[\text{Percentile} = (\operatorname{Count}(x(s) < x(T)) + 0.5 \cdot \operatorname{Count}(x(s) = x(T))) / \operatorname{Count}(s),\;\; \text{over s < T}\] \[\text{Rank} = 1 + \operatorname{Count}(x(s) > x(T)),\;\; \text{over s < T: 1 for the highest of the history}\] \[\text{Highest Since} = \text{the last date}\; s < T \;\text{with}\; x (s) \geq x(T)\] \[\text{Lowest Since} = \text{the last date}\; s < T \;\text{with}\; x (s) \leq x(T)\] \[\text{Change Since Start} = (x(T) - x(0)) / | x(0) |\] \[\text{Change From Highest} = (x(T) - \max(x)) / | \max(x) |\] \[\text{Change From Lowest} = (x(T) - \min(x)) / | \min(x) |\] \[\text{Multiple Since Start} = x(T) / x(0)\] \[\text{Annualised Change} = (x(T) / x(0)) ^{1 / \text{years}} - 1,\;\; \text{years between the two dates}\] \[\text{Largest Drawdown} = \text{min over}\; t \;\text{of} (x(t) - \max(x(s),\; s \leq t)) / | \max(x(s),\; s \leq t) |\] \[\text{Recovery Date} = \text{the first date after the trough with}\; x \geq \text{the peak before it}\]Where x(T) is the latest value of a series, x(0) its first observation and s runs over its earlier observations. An earlier value equal to the latest one counts as half (the percentile rank), so a policy rate that has not changed for years sits in the middle of its own ties. Highest Since is NaN when no earlier value was as high, which makes the latest value the highest of the history; Lowest Since likewise. The Change Since Start is the change between the first and the latest observation in the range, so the start and end date choose the two dates to compare (housing starts from January 2021 to their latest month with period=”monthly”); it is relative to the absolute first value, so a rise from a negative value is positive, and NaN when the first value is zero. The Highest and Lowest are the peak and trough of the range, the latest value included, with the first dates they were reached, so the start date works as the anchor of an event window: the rise from the start to the peak, the date of the peak and the fall from it to the latest value. The changes from them are relative to their absolute values, and NaN when they are zero. With Econometrics(data=..., changes="difference") every change, the Largest Drawdown included, is a difference in the unit of the series instead (percentage points for a rate: a 10-year yield from 5.29% to 4.94% is -0.0035), and the Multiple Since Start and Annualised Change are NaN.
Also known as: highest since, lowest since, record high, multi-year high, level percentile, historical percentile, how unusual is the latest value, change since, change between two dates, cumulative change, event window, peak, trough, drawdown from the peak, change from the high, change from the low, multiple, compound annual growth rate (CAGR), annualised change, peak to trough, time to recover the peak, change in percentage points.
Level Significance in Python
Install the Finance Toolkit with:
pip install financetoolkit -U
Then call get_level_significance as shown below.
from financetoolkit import Economics, Econometrics
economics = Economics(start_date='2000-01-01', end_date='2026-10-31')
long_term_rates = economics.get_long_term_interest_rate(
countries=['United States', 'Germany', 'Japan'], period='monthly'
)
econometrics = Econometrics(data=long_term_rates)
econometrics.get_level_significance().T
Which returns:
| United States | Germany | Japan | |
|---|---|---|---|
| Start Date | 2000-01-31 | 2000-01-31 | 2000-01-31 |
| Start Value | 0.0666 | 0.0554 | 0.0169 |
| Observations | 322 | 322 | 322 |
| Latest Date | 2026-10-31 | 2026-10-31 | 2026-10-31 |
| Latest Value | 0.0513 | 0.0342 | 0.0276 |
| Change Since Start | -0.2297 | -0.3827 | 0.6331 |
| Multiple Since Start | 0.7703 | 0.6173 | 1.6331 |
| Annualised Change | -0.0097 | -0.0179 | 0.0185 |
| Percentile | 0.9377 | 0.6854 | 0.9907 |
| Rank | 21 | 102 | 4 |
| Highest Since | 2002-05-31 | 2026-09-30 | 2026-09-30 |
| Lowest Since | 2026-09-30 | 2026-08-31 | 2026-06-30 |
| Highest | 0.0666 | 0.0554 | 0.0305 |
| Highest Date | 2000-01-31 | 2000-01-31 | 2026-09-30 |
| Change From Highest | -0.2297 | -0.3827 | -0.0951 |
| Lowest | 0.0062 | -0.0065 | -0.0028 |
| Lowest Date | 2020-07-31 | 2019-08-31 | 2019-08-31 |
| Change From Lowest | 7.2742 | 6.2615 | 10.8571 |
| Largest Drawdown | -0.9069 | -1.1173 | -1.1429 |
| Drawdown Peak Date | 2000-01-31 | 2000-01-31 | 2006-04-30 |
| Drawdown Trough Date | 2020-07-31 | 2019-08-31 | 2019-08-31 |
| Recovery Date | nan | nan | 2025-12-31 |
Using Your Own Data
get_level_significance runs on any data, not only prices: ratios, economic indicators, yield curves or your own dataset. Pass a DataFrame, a Series or a dictionary of them to Econometrics as data, with the dates in the rows or the columns, and set changes to how its changes are calculated: "percentage", "log", "difference" for rates and ratios, or None when the data are changes already. For example, for the monthly unemployment rates of the United States and Germany:
from financetoolkit import Economics, Econometrics
economics = Economics(start_date="2000-01-01")
unemployment = economics.get_unemployment_rate(
countries=["United States", "Germany"], period="monthly"
)
econometrics = Econometrics(data=unemployment, changes="difference")
econometrics.get_level_significance()
Parameters
get_level_significance accepts the following parameters.
| Parameter | Type | Description | Example |
|---|---|---|---|
period | str | None | The data frequency (daily, weekly, monthly, quarterly, or yearly); the weekly to yearly periods take the last value of each period. Defaults to None, which is “daily”: the series at the dates they are observed, so a monthly series is compared month by month. | "weekly" |
column | str | The historical data column to measure. Defaults to “Close”, the traded close of the tickers and the series themselves with data=. | "Return" |
spread_over | str | None | The name of a series to subtract from every other series, so the spreads over it are measured instead (named “ | None, which measures the series themselves |
ratio | bool | Whether to divide every other series by the spread_over series instead of subtracting it (named “ | False |
include_benchmark | bool | Whether to include “Benchmark” among the assets. Defaults to False. | True |
level | float | None | A level to compare every series with, such as an earlier peak, which adds the Level, the First Above Level (the first date the series exceeded it) and Above Level Since (the date it has been above it since without a break, empty when the latest value is not above it). Defaults to None, which leaves them out. | "general" |
rounding | int | None | The number of decimals to round the results to. Defaults to None, which uses the rounding of the class (4 unless set otherwise). | 2 |
show_columns | str | list[str] | None | The columns to keep, a name or a list of names, matched on every column level, or the rows when no column has those names (such as the line items of a financial statement). Names that do not exist are logged, and when none exist the result is returned in full. Defaults to None, which keeps every column. | None, which keeps every column |