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.

ParameterTypeDescriptionExample
periodstr | NoneThe 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"
columnstrThe historical data column to measure. Defaults to “Close”, the traded close of the tickers and the series themselves with data=."Return"
spread_overstr | NoneThe name of a series to subtract from every other series, so the spreads over it are measured instead (named “ - "), e.g. producer price inflation over consumer price inflation. The spread exists on the dates both series have, so with period="daily" a weekly series minus a daily one is measured on the weekly dates. Defaults to None, which measures the series themselves.None, which measures the series themselves
ratioboolWhether to divide every other series by the spread_over series instead of subtracting it (named “ / "), e.g. exports over GDP or one country's yield over another's. Defaults to False.False
include_benchmarkboolWhether to include “Benchmark” among the assets. Defaults to False.True
levelfloat | NoneA 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"
roundingint | NoneThe number of decimals to round the results to. Defaults to None, which uses the rounding of the class (4 unless set otherwise).2
show_columnsstr | list[str] | NoneThe 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
Share