Return Statistics

Calculate the statistics traders report about the returns of an investment portfolio or asset: how often it wins, how large its wins and losses are, how long its winning and losing streaks run and how its gains relate to its drawdown and tails.

Unlike the Win Rate of get_win_rate, which counts the periods an asset beats its benchmark, these statistics are absolute: a win is a positive return.

The formulas are as follows:

\[\text{Win Rate} = \text{Number of Positive Returns} / \text{Number of Non-Zero Returns}\] \[\text{Average Win} = \text{Average of the Positive Returns}\] \[\text{Average Loss} = \text{Average of the Negative Returns}\] \[\text{Payoff Ratio} = \text{Average Win} / | \text{Average Loss} |\] \[\text{Profit Factor} = \text{Sum of the Positive Returns} / | \text{Sum of the Negative Returns} |\] \[\text{Expectancy} = \text{Win Rate}\; x \;\text{Average Win} + (1 - \text{Win Rate}) x \;\text{Average Loss}\] \[\text{Max Consecutive Wins} (\text{Losses}) = \text{The longest run of positive} (\text{negative}) \text{returns}\] \[\text{Recovery Factor} = \text{Cumulative Return} / | \text{Maximum Drawdown} |\] \[\text{Common Sense Ratio} = \text{Profit Factor}\; x \;\text{Tail Ratio} (\text{95th} / \text{5th} \;\text{percentile})\]

The definitions follow the QuantStats package, except that the Recovery Factor compounds the returns into the cumulative return and keeps its sign (QuantStats takes the absolute value of the summed returns), so a history that lost money does not appear to recover.

For more information, see the following sources:

Tharp, V.K. (2006). “Trade Your Way to Financial Freedom.” 2nd ed., McGraw-Hill.
Aroussi, R. “QuantStats: Portfolio analytics for quants.” https://github.com/ranaroussi/quantstats

Return Statistics in Python or via the MCP

Install the Finance Toolkit with:

pip install financetoolkit -U

Then call get_return_statistics as shown below.

from financetoolkit import Toolkit

toolkit = Toolkit(
    ["AAPL", "MSFT", "KO"],
    api_key="FINANCIAL_MODELING_PREP_KEY",
    start_date="2021-01-01",
    end_date="2025-12-31",
)

toolkit.performance.get_return_statistics()

Or, after setting up the Finance Toolkit MCP, ask:

What were the win rate, payoff ratio, profit factor and other return statistics of Apple, Microsoft and Coca-Cola from 2021 to 2025?

Which returns:

	AAPL	MSFT	KO
Win Rate	0.5316	0.524	0.5326
Average Win	0.0125	0.0121	0.0073
Average Loss	-0.0126	-0.0116	-0.0075
Payoff Ratio	0.9963	1.0407	0.9769
Profit Factor	1.1306	1.1458	1.1131
Expectancy	0.0008	0.0008	0.0004
Max Consecutive Wins	11	9	9
Max Consecutive Losses	8	8	7
Recovery Factor	3.4734	3.5343	3.1047
Common Sense Ratio	1.0549	1.0935	1.196

Parameters

get_return_statistics accepts the following parameters.

Parameter	Type	Description	Example
`period`	`str`	The period of the returns over the whole history, or with within_period=True the period the daily returns are grouped by. Defaults to “daily”, or with within_period=True to “quarterly” if the Toolkit is initialised with quarterly=True, otherwise “yearly”.	`"weekly"`
`within_period`	`bool`	Whether to calculate the statistics from the daily returns within each period (e.g. each year if period = ‘yearly’) instead of from the returns of `period` over the whole history. 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`

Return Statistics in Python or via the MCP

Parameters

Related Returns