Maximum Drawdown Duration
Calculate the Maximum Drawdown Duration of an investment portfolio or asset’s returns.
The Maximum Drawdown Duration is the number of periods between the peak and the lowest point of the largest drawdown, giving insight into how long the worst loss of value took to unfold.
The formula is as follows:
\[\text{Maximum Drawdown Duration} = t(\text{trough}) - t(\text{peak})\]Where t(trough) is the period of the lowest Drawdown (see get_maximum_drawdown) and t(peak) the last period at or before it in which Wealth stood at the high that drawdown is measured from. When that high is the starting value of 1, t(peak) is the period before the first return.
Also known as: drawdown length.
Maximum Drawdown Duration in Python or via the MCP
Install the Finance Toolkit with:
pip install financetoolkit -U
Then call get_maximum_drawdown_duration as shown below.
from financetoolkit import Toolkit
toolkit = Toolkit(
["^GSPC", "^HSI", "^FTSE"],
api_key="FINANCIAL_MODELING_PREP_KEY",
start_date="2021-01-01",
end_date="2025-12-31",
)
toolkit.risk.get_maximum_drawdown_duration(period="yearly", within_period=True)
Or, after setting up the Finance Toolkit MCP, ask:
How many trading days did the maximum drawdown of the S&P 500, the Hang Seng and the FTSE 100 take from peak to trough in each year from 2021 to 2025?
Which returns:
| ^GSPC | ^HSI | ^FTSE | Benchmark | |
|---|---|---|---|---|
| 2021 | 22 | 217 | 15 | 22 |
| 2022 | 201 | 200 | 173 | 201 |
| 2023 | 64 | 225 | 98 | 64 |
| 2024 | 14 | 35 | 58 | 14 |
| 2025 | 34 | 13 | 27 | 34 |
Parameters
get_maximum_drawdown_duration accepts the following parameters.
| Parameter | Type | Description | Example |
|---|---|---|---|
period | str | The data frequency for returns (daily, weekly, monthly, quarterly, or yearly). Defaults to “daily”. | "weekly" |
within_period | bool | Whether to calculate the duration within the specified period or for the entire period. Thus whether to look at the duration within a specific year (if period = ‘yearly’) or look at the entirety of all years. Defaults to False. Note that this requires intraday data when period = ‘daily’, since a single day only nests observations when intraday data was fetched. | True |
rounding | int | None | The number of decimals to round the results to. Defaults to None, which uses the rounding of the Toolkit (4 unless set otherwise). | 2 |
growth | bool | Whether to calculate the growth of the duration values over time. Defaults to False. | True |
lag | int | list[int] | The lag to use for the growth calculation. Defaults to 1. | 4 |
standardize | bool | Whether to standardize (Z-Score) the result. When combined with growth=True, standardizes the growth values instead of the raw values. Defaults to False. | True |