Excess Return
Calculate the Excess Return of an investment portfolio or asset for a given period based on the daily historical returns.
The Excess Return is defined as the period Return minus the risk free rate earned over that period. If cumulative is set to True, the excess returns within the selected date range are compounded further into a cumulative excess return (growth of 1) instead.
The formula is as follows:
\[\text{Period Return} = ((1 + \text{Daily Return}\; 1) \cdot (1 + \text{Daily Return}\; 2) \cdot ... \cdot (1 + \text{Daily Return}\; N)) - 1\] \[\text{Period Risk Free Rate} = (1 + \text{Average Annual Risk Free Rate}) ^{1 / \text{Periods per Year}} - 1,\;\; \text{with the average taken over the daily Treasury yields within the period}\] \[\text{Excess Return} = \text{Period Return} - \text{Period Risk Free Rate}\] \[\text{Cumulative Excess Return} = (1 + \text{Excess Return}\; 1) \cdot (1 + \text{Excess Return}\; 2) \cdot ... \cdot (1 + \text{Excess Return}\; N)\]The compounding starts at 1 at the beginning of the date range, so the first value is 1 plus the excess return of the first period.
A period without any daily return for a ticker (before it listed, or a gap in its history) is NaN rather than 0, and the cumulative excess return carries the previous value past such a period.
Also known as: return minus the risk-free rate.
Excess Return in Python or via the MCP
Install the Finance Toolkit with:
pip install financetoolkit -U
Then call get_excess_return as shown below.
from financetoolkit import Toolkit
toolkit = Toolkit(
["MCD", "SBUX", "CMG"],
api_key="FINANCIAL_MODELING_PREP_KEY",
start_date="2021-01-01",
end_date="2025-12-31",
)
toolkit.performance.get_excess_return()
Or, after setting up the Finance Toolkit MCP, ask:
How much did McDonald's, Starbucks, Chipotle and the S&P 500 return above the risk-free rate in each year from 2021 to 2025?
Which returns:
| Date | MCD | SBUX | CMG | Benchmark |
|---|---|---|---|---|
| 2021 | 0.2901 | 0.1399 | 0.3099 | 0.2912 |
| 2022 | -0.0255 | -0.1604 | -0.2359 | -0.2112 |
| 2023 | 0.1112 | -0.0511 | 0.6093 | 0.222 |
| 2024 | -0.0405 | -0.0669 | 0.2772 | 0.2071 |
| 2025 | 0.0359 | -0.0956 | -0.4292 | 0.1347 |
Parameters
get_excess_return accepts the following parameters.
| Parameter | Type | Description | Example |
|---|---|---|---|
period | str | The data frequency for returns (weekly, monthly, quarterly, or yearly). Defaults to “quarterly” if the Toolkit is initialised with quarterly=True, otherwise “yearly”. | "quarterly" |
cumulative | bool | Whether to return the cumulative excess return over time instead of the discrete excess return per period. Defaults to False. | 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 Excess Return 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 |