Performance

The Performance module calculates important performance metrics such as the Sharpe Ratio, Sortino Ratio, Treynor Ratio, Information Ratio, Jensen’s Alpha, Beta, Capital Asset Pricing Model (CAPM), R-Squared and more.

To install the FinanceToolkit it simply requires the following:

pip install financetoolkit -U

collect_all_metrics

Calculates and collects all performance metrics.

Args:

• period (str, optional): The period to use for the calculation. Defaults to “quarterly” if the Toolkit is initialised with quarterly=True, otherwise “yearly”.
• rounding (int, optional): The number of decimals to round the results to. Defaults to 4.
• growth (bool, optional): Whether to calculate the growth of the ratios. Defaults to False.
• lag (int \| str, optional): The lag to use for the growth calculation. Defaults to 1.
• standardize (bool, optional): Whether to standardize (Z-Score) the result. When combined with growth=True, standardizes the growth values instead of the raw values. Defaults to False.

Returns:

pd.DataFrame: Performance metrics calculated based on the specified parameters, with a Multi Index of (metric, ticker) as the columns. For a single-ticker Toolkit the ticker level is dropped. Returns and Excess Return are only included when period is not “daily”.

Notes:

• The method calculates various performance metrics for each asset in the Toolkit instance.
• If growth is set to True, the method calculates the growth of the ratio values using the specified lag.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.performance.collect_all_metrics().xs("AAPL", level=1, axis=1)

Which returns:

get_beta

Calculate the Beta, a measurement that assess the systematic risk of a stock or investment.

Beta is a financial metric used to assess the systematic risk of a stock or investment in relation to the overall market. It provides valuable insights into how a particular asset’s returns tend to move in response to fluctuations in the broader market. A stock’s Beta is calculated by analyzing its historical price movements and their correlation with the movements of a market index, typically the benchmark index like the S&P 500.

The formula is as follows:

For a given period, for example monthly, this translates into the following:

See definition: https://en.wikipedia.org/wiki/Beta_(finance)

Also known as: market sensitivity, systematic risk.

Args:

• period (str, optional): The period to use for the calculation. Defaults to “quarterly” if the Toolkit is initialised with quarterly=True, otherwise “yearly”.
• rolling (int, optional): The rolling period to use for the calculation. If you select period = ‘monthly’ and set rolling to 12 you obtain the rolling 12-month Sharpe Ratio.
• rounding (int, optional): The number of decimals to round the results to. Defaults to 4.
• growth (bool, optional): Whether to calculate the growth of the ratios. Defaults to False.
• lag (int \| str, optional): The lag to use for the growth calculation. Defaults to 1.
• standardize (bool, optional): Whether to standardize (Z-Score) the result. When combined with growth=True, standardizes the growth values instead of the raw values. Defaults to False.

Returns:

pd.DataFrame: Beta values.

Notes:

• Daily Beta is not an option as the standard deviation for 1 day is close to zero. Therefore, it does not give any useful insights.
• The method retrieves historical data and calculates the Beta for each asset in the Toolkit instance.
• The risk-free rate is often represented by the return of a risk-free investment, such as a Treasury bond.
• If growth is set to True, the method calculates the growth of the ratio values using the specified lag.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "AMZN"], api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.performance.get_beta()

Which returns:

get_capital_asset_pricing_model

CAPM, or the Capital Asset Pricing Model, is a financial model used to estimate the expected return on an investment, such as a stock or portfolio of stocks. It provides a framework for evaluating the risk and return trade-off of an asset or portfolio in relation to the overall market. CAPM is based on the following key components:

• Risk-Free Rate (Rf): This is the theoretical return an investor could earn from an investment with no risk of financial loss. It is typically based on the yield of a government bond.
• Market Risk Premium (Rm - Rf): This represents the additional return that investors expect to earn for taking on the risk of investing in the overall market as opposed to a risk-free asset. It is calculated as the difference between the expected return of the market (Rm) and the risk-free rate (Rf).
• Beta (β): Beta is a measure of an asset’s or portfolio’s sensitivity to market movements. It quantifies how much an asset’s returns are expected to move in relation to changes in the overall market. A beta of 1 indicates that the asset moves in line with the market, while a beta greater than 1 suggests higher volatility, and a beta less than 1 indicates lower volatility.

The Capital Asset Pricing Model (CAPM) is a widely used financial model that helps in determining the expected return of an asset or portfolio based on its systematic risk and the prevailing risk-free rate in the market. CAPM provides insights into how an asset or investment should be priced in order to offer an appropriate rate of return, given its level of risk compared to the overall market.

The formula is as follows:

See definition: https://en.wikipedia.org/wiki/Capital_asset_pricing_model

Also known as: CAPM, expected return model.

Args:

• period (str, optional): The period to use for the calculation. Defaults to “quarterly” if the Toolkit is initialised with quarterly=True, otherwise “yearly”.
• rolling (int, optional): The rolling window size to use for the Beta component of the calculation. If set, Beta is estimated over a rolling window of this many periods across the full return history instead of per period. Defaults to None.
• rounding (int, optional): The number of decimals to round the results to. Defaults to 4.
• growth (bool, optional): Whether to calculate the growth of the ratios. Defaults to False.
• lag (int \| str, optional): The lag to use for the growth calculation. Defaults to 1.
• standardize (bool, optional): Whether to standardize (Z-Score) the result. When combined with growth=True, standardizes the growth values instead of the raw values. Defaults to False.

Returns:

pd.DataFrame: CAPM values.

Notes:

• Daily CAPM is not an option as the standard deviation for 1 day is close to zero. Therefore, it does not give any useful insights.
• The method retrieves historical data and calculates the CAPM for each asset in the Toolkit instance.
• The risk-free rate is often represented by the return of a risk-free investment, such as a Treasury bond.
• If growth is set to True, the method calculates the growth of the ratio values using the specified lag.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.performance.get_capital_asset_pricing_model()

Which returns:

get_factor_asset_correlations

Calculates factor exposures for each asset.

The major difference between the Fama and French Model here is that the correlation is taken as opposed to a Linear Regression in which the R-squared or Slope can be used to understand the exposure to each factor.

For assessing the exposure or influence of a stock to external factors, it’s often preferable to use R-squared (R²) or Beta because it explicitly measures how well the factors explain the stock’s returns. A higher R² indicates that the stock’s returns are more closely related to the factors, and thus, the factors have a greater influence on the stock’s performance.

However, since the results are closely related and tend to point into the same direction it could be fine to use correlations as well depending on the level of accuracy required.

Also known as: factor exposure, asset correlations.

Args:

• period (str, optional): The period to use for the calculation. Defaults to “quarterly” if the Toolkit is initialised with quarterly=True, otherwise “yearly”.
• factors_to_calculate (list of str, optional): List of factors to calculate scores and residuals for. Defaults to [“Mkt-RF”, “SMB”, “HML”, “RMW”, “CMA”].
• rounding (int, optional): The number of decimals to round the results to. Defaults to 4.
• show_columns (list of str, optional): Restrict the result to these top level columns. Defaults to None, which returns every column.

Returns:

pd.DataFrame: Factor Asset Correlations, with a Multi Index of (ticker, factor) as the columns and one row per period.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.performance.get_factor_asset_correlations()["AAPL"]

Which returns:

get_factor_correlations

Calculates factor correlations between each factor. This is useful to understand how correlated each factor is to each other. This is based off the Fama and French 5 Factor model which includes:

• Market Risk Premium (Mkt-RF): Represents the additional return that investors expect to earn for taking on the risk of investing in the overall market as opposed to a risk-free asset.
• Size Premium (SMB): Reflects the historical excess return of small-cap stocks over large-cap stocks.
• Value Premium (HML): Captures the historical excess return of value stocks over growth stocks.
• Profitability (RMW): Measures the historical excess return of high profitability stocks over low profitability stocks.
• Investment (CMA): Quantifies the historical excess return of low investment stocks over high investment stocks.

Optionally, it is also possible to see the correlation between the risk-free rate and each factor.

Also known as: factor model correlations.

Args:

• period (str, optional): The period to use for the calculation. Defaults to “quarterly” if the Toolkit is initialised with quarterly=True, otherwise “yearly”.
• factors_to_calculate (list of str, optional): List of factors to calculate scores and residuals for. Defaults to [“Mkt-RF”, “SMB”, “HML”, “RMW”, “CMA”].
• exclude_risk_free (bool, optional): Whether to exclude the risk-free rate from the results. Defaults to True.
• rounding (int, optional): The number of decimals to round the results to. Defaults to 4.

Returns:

pd.DataFrame: Factor Correlations. One correlation matrix per period, stacked into a Multi Index of (period, factor) rows with the factors as the columns and restricted to the Toolkit’s date range.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY", start_date="2023-01-01")

toolkit.performance.get_factor_correlations()

Which returns:

get_fama_and_french_model

Calculate Fama and French 5 Factor model scores and residuals for a set of financial assets.

The Fama and French 5 Factor model is a widely used financial model that helps estimate the expected return of financial assets, such as stocks or portfolios, based on five key factors:

• Market Risk Premium (Mkt-RF): Represents the additional return that investors expect to earn for taking on the risk of investing in the overall market as opposed to a risk-free asset.
• Size Premium (SMB): Reflects the historical excess return of small-cap stocks over large-cap stocks.
• Value Premium (HML): Captures the historical excess return of value stocks over growth stocks.
• Profitability (RMW): Measures the historical excess return of high profitability stocks over low profitability stocks.
• Investment (CMA): Quantifies the historical excess return of low investment stocks over high investment stocks.

The model can perform both a Simple Linear Regression on each factor as well as a Multi Linear Regression which includes all factors. Generally, a multi linear regression is applied but if you wish to see individual R-squared values for each factor you can select the simple linear regression method.

The model performs a Linear Regression on each factor and defines the regression parameters and residuals for each asset over time based on its exposure to these factors.

The regression formula is as follows for the Multi Linear Regression:

And the following for the Simple Linear Regression:

• Excess Return = Intercept + Slope * Factor Value + Residuals

So for a given factor, it should hold that the Excess Return equals the entire regression. Note that in this calculation the Excess Return refers to the Asset Return minus the Risk Free Rate as reported in the Fama and French dataset and will not be the same as the defined Excess Return in the historical data given that this is based on the Risk Free Rate defined in the initialization.

The regression is estimated on the daily observations falling inside each period, so its Intercept, Slope and Residuals are all on a daily scale. The Factor Value and Residuals columns reported by the Simple Linear Regression therefore describe the last daily observation within the period, which is the only reading for which the identity above holds - they are not period-aggregated quantities.

What is relevant to look at is the influence these factors have on each stock and how much each factor explains the stock return. E.g. you will generally see a pretty high influence (Beta or Slope) for the Market Risk Premium (Mkt-RF) factor as this is the main factor that explains the stock return (as also prevalent in the CAPM). The other factors can fluctuate greatly between stocks depending on which stocks you look at.

Also known as: Fama-French model, three-factor model, five-factor model, FF3, FF5.

Args:

• period (str, optional): The period for the calculation (e.g., “weekly”, “monthly”, “quarterly”, “yearly”). Defaults to “quarterly” if the Toolkit is initialised with quarterly=True, otherwise “yearly”.
• method (str, optional): The regression method to use for the calculation. Defaults to ‘multi’.
• factors_to_calculate (list of str, optional): List of factors to calculate scores and residuals for. Defaults to [“Mkt-RF”, “SMB”, “HML”, “RMW”, “CMA”].
• include_daily_residuals (bool, optional): Whether to also return the pointwise (daily) regression residuals as a second DataFrame. Defaults to False.
• rounding (int, optional): The number of decimals to round the results to. Defaults to 4.
• growth (bool, optional): Whether to calculate the growth of the ratio values. Defaults to False.
• lag (int or list of int, optional): The lag to use for the growth calculation. Defaults to 1.
• standardize (bool, optional): Whether to standardize (Z-Score) the result. When combined with growth=True, standardizes the growth values instead of the raw values. Defaults to False.
• show_columns (list of str, optional): Restrict the result to these top level columns. Defaults to None, which returns every column.

Returns:

pd.DataFrame: Fama and French 5 Factor model scores for the specified assets, with a Multi Index of (ticker, parameter) as the columns and one row per period. When include_daily_residuals is True a tuple of (scores, residuals) is returned instead.

Notes:

• The dataset from Fama and French is not always fully up to date. Therefore, some periods could be excluded.
• Daily Fama and French results is not an option as it would attempt to do a linear regression on a single data point which will not give any meaningful results.
• The method retrieves historical data and calculates regression parameters and residuals for each asset.
• The risk-free rate is typically represented by the return of a risk-free investment, such as a Treasury bond. In this case, the Risk Free Rate from the Fama and French dataset is used.
• If growth is set to True, the method calculates the growth of the ratio values using the specified lag.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

# Calculate Fama and French 5 Factor model scores
toolkit.performance.get_fama_and_french_model()["AAPL"]

get_carhart_four_factor_model

Calculate Carhart Four Factor model scores for a set of financial assets.

The Carhart Four Factor model extends the Fama and French Three Factor model with a momentum factor, based on the observation that stocks with high prior returns (winners) tend to keep outperforming stocks with low prior returns (losers) over the medium term:

• Market Risk Premium (Mkt-RF): The excess return of the market over the risk-free rate.
• Size Premium (SMB): The historical excess return of small-cap stocks over large-cap stocks.
• Value Premium (HML): The historical excess return of value stocks over growth stocks.
• Momentum (MOM): The historical excess return of prior winner stocks over prior loser stocks.

The model performs a Multi Linear Regression on all four factors and defines the regression parameters for each asset over time based on its exposure to these factors:

• Excess Return = Intercept + Beta1 * Mkt-RF + Beta2 * SMB + Beta3 * HML + Beta4 * MOM + Residuals

For more information about the method, see the following paper:

• Carhart, M.M. (1997). “On Persistence in Mutual Fund Performance.” The Journal of Finance, 52(1), 57-82.

Also known as: Carhart model, four-factor model, momentum-augmented Fama-French model.

Args:

• period (str, optional): The period for the calculation (e.g., “weekly”, “monthly”, “quarterly”, “yearly”). Defaults to “quarterly” if the Toolkit is initialised with quarterly=True, otherwise “yearly”.
• rounding (int, optional): The number of decimals to round the results to. Defaults to 4.
• growth (bool, optional): Whether to calculate the growth of the ratio values. Defaults to False.
• lag (int or list of int, optional): The lag to use for the growth calculation. Defaults to 1.
• standardize (bool, optional): Whether to standardize (Z-Score) the result. When combined with growth=True, standardizes the growth values instead of the raw values. Defaults to False.
• show_columns (list of str, optional): Restrict the result to these top level columns. Defaults to None, which returns every column.

Returns:

pd.DataFrame: Carhart Four Factor model scores for the specified assets, with a Multi Index of (ticker, parameter) as the columns and one row per period.

Notes:

• The dataset from Ken French is not always fully up to date. Therefore, some periods could be excluded.
• Daily Carhart results is not an option as it would attempt to do a linear regression on a single data point which will not give any meaningful results.
• The factors come from the Fama and French three factor file rather than the five factor file used by get_fama_and_french_model. The two files agree on Mkt-RF, HML and RF but not on SMB: the five factor SMB averages three separate size legs, while Carhart (1997) extends the three factor model and therefore requires the three factor SMB.
• The risk-free rate is the Risk Free Rate reported in the Fama and French dataset (used here, rather than the Toolkit’s own risk-free rate, to stay consistent with the momentum factor’s construction).
• If growth is set to True, the method calculates the growth of the ratio values using the specified lag.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AMZN", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.performance.get_carhart_four_factor_model(period="quarterly")["AMZN"]

get_alpha

Alpha, in a general sense, represents the excess return an investment generates relative to a benchmark or a risk-adjusted return. It can be positive (indicating the investment outperformed the benchmark) or negative (indicating underperformance).

The formula is as follows:

See definition: https://en.wikipedia.org/wiki/Alpha_(finance)

Also known as: excess return, outperformance, active return.

Args:

• period (str, optional): The period to use for the calculation. Defaults to “quarterly” if the Toolkit is initialised with quarterly=True, otherwise “yearly”.
• rolling (int, optional): The rolling window size to use for the calculation. If set, Alpha is calculated as the rolling mean excess return over this many periods across the full return history instead of per period. Defaults to None.
• rounding (int, optional): The number of decimals to round the results to. Defaults to 4.
• growth (bool, optional): Whether to calculate the growth of the ratios. Defaults to False.
• lag (int \| str, optional): The lag to use for the growth calculation. Defaults to 1.
• standardize (bool, optional): Whether to standardize (Z-Score) the result. When combined with growth=True, standardizes the growth values instead of the raw values. Defaults to False.

Returns:

pd.DataFrame: Alpha values.

Notes:

• The method retrieves historical data and calculates the Alpha for each asset in the Toolkit instance.
• If growth is set to True, the method calculates the growth of the ratio values using the specified lag.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.performance.get_alpha()

Which returns:

get_jensens_alpha

Calculate Jensen’s Alpha, a measure of an asset’s performance relative to its expected return based on the Capital Asset Pricing Model (CAPM).

Jensen’s Alpha is used to assess whether an investment has outperformed or underperformed its expected return given its systematic risk, as represented by the asset’s Beta.

The formula is as follows:

See definition: https://en.wikipedia.org/wiki/Jensen%27s_alpha

Also known as: Jensen alpha, risk-adjusted excess return.

Args:

• period (str, optional): The period to use for the calculation. Defaults to “quarterly” if the Toolkit is initialised with quarterly=True, otherwise “yearly”.
• rolling (int, optional): The rolling window size to use for the Beta component of the calculation. If set, Beta is estimated over a rolling window of this many periods across the full return history instead of per period. Defaults to None.
• rounding (int, optional): The number of decimals to round the results to. Defaults to 4.
• growth (bool, optional): Whether to calculate the growth of the ratios. Defaults to False.
• lag (int \| str, optional): The lag to use for the growth calculation. Defaults to 1.
• standardize (bool, optional): Whether to standardize (Z-Score) the result. When combined with growth=True, standardizes the growth values instead of the raw values. Defaults to False.

Returns:

pd.DataFrame: Jensen’s Alpha values.

Notes:

• Daily Jensen’s Alpha is not an option as the standard deviation for 1 day is close to zero. Therefore, it does not give any useful insights.
• The method retrieves historical data and calculates the CAPM for each asset in the Toolkit instance.
• The risk-free rate is often represented by the return of a risk-free investment, such as a Treasury bond.
• If growth is set to True, the method calculates the growth of the ratio values using the specified lag.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.performance.get_jensens_alpha()

Which returns:

get_treynor_ratio

The Treynor Ratio, also known as Treynor’s Measure or the Reward-to-Variability Ratio, is a financial metric used to assess the risk-adjusted performance of an investment portfolio or asset. It measures the excess return generated by the portfolio per unit of systematic or market risk, often represented by Beta. The Treynor Ratio is a valuable tool for evaluating the performance of investments in relation to their market risk exposure.

The formula is as follows:

See definition: https://en.wikipedia.org/wiki/Treynor_ratio

Also known as: reward-to-volatility ratio.

Args:

• period (str, optional): The period to use for the calculation. Defaults to “quarterly” if the Toolkit is initialised with quarterly=True, otherwise “yearly”.
• rolling (int, optional): The rolling window size to use for the Beta component of the calculation. If set, Beta is estimated over a rolling window of this many periods across the full return history instead of per period. Defaults to None.
• rounding (int, optional): The number of decimals to round the results to. Defaults to 4.
• growth (bool, optional): Whether to calculate the growth of the ratios. Defaults to False.
• lag (int \| str, optional): The lag to use for the growth calculation. Defaults to 1.
• standardize (bool, optional): Whether to standardize (Z-Score) the result. When combined with growth=True, standardizes the growth values instead of the raw values. Defaults to False.

Returns:

pd.DataFrame: Treynor Ratio values.

Notes:

• Daily Treynor Ratio is not an option as the standard deviation for 1 day is close to zero. Therefore, it does not give any useful insights.
• The method retrieves historical data and calculates the TR for each asset in the Toolkit instance.
• The risk-free rate is often represented by the return of a risk-free investment, such as a Treasury bond.
• If growth is set to True, the method calculates the growth of the ratio values using the specified lag.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.performance.get_treynor_ratio()

Which returns:

get_sharpe_ratio

Calculate the Sharpe ratio, a measure of risk-adjusted return that evaluates the excess return of an investment portfolio or asset per unit of risk taken.

The Sharpe ratio is calculated as the difference between the expected return of the asset or portfolio and the risk-free rate of return, divided by the standard deviation of the asset or portfolio’s excess return. It quantifies the amount of return generated for each unit of risk assumed, providing insights into the investment’s performance relative to the risk taken.

The formula is as follows:

By default one Sharpe ratio is reported per period, computed from the daily excess returns falling inside that period. For a given period, for example monthly, this translates into the following:

For a rolling period, period instead sets the frequency of the returns themselves and the ratio is computed over a rolling window of rolling such returns:

Note that this is explicitly already subtracts the Risk Free Rate.

The result is not annualized: it is a per-observation Sharpe ratio, so a value computed from daily returns is roughly SQRT(252) smaller than the annualized figure usually quoted in the literature (SQRT(52), SQRT(12) and SQRT(4) for weekly, monthly and quarterly returns respectively). Multiply by that factor before comparing against published annualized Sharpe ratios.

The plain Sharpe ratio only looks at the mean and standard deviation of returns, implicitly assuming Gaussian, i.i.d. returns and ignoring how much uncertainty surrounds the estimate itself. The method parameter selects one of three corrections for that, each keeping the same excess returns and therefore the same underlying Sharpe ratio as its starting point:

• "adjusted" - the Adjusted Sharpe Ratio (ASR, Pezier & White, 2006) penalizes (or rewards) the Sharpe ratio for negative skewness and excess kurtosis using a Cornish-Fisher-style expansion, so that two strategies with the same Sharpe ratio but different tail shapes are no longer scored identically:
• ASR = SR * [1 + (S / 6) * SR − ((K − 3) / 24) * SR^2]
• "probabilistic" - the Probabilistic Sharpe Ratio (PSR) is the probability that the true (population) Sharpe ratio exceeds benchmark_sharpe_ratio, folding the skewness and (non-excess) kurtosis of the underlying returns into the standard error of the Sharpe ratio so that a short, lumpy sample no longer looks more convincing than it is:
• PSR(SR) = Φ( (SR̂ − SR) · sqrt(n − 1) / sqrt(1 − γ₃·SR̂ + ((γ₄ − 1) / 4)·SR̂²) )
• "deflated" - the Deflated Sharpe Ratio (DSR) is the Probabilistic Sharpe Ratio corrected for the fact that a reported Sharpe ratio is often the best of many strategy variations, parameter combinations, or lookback windows tried during a backtest (multiple testing / selection bias / “backtest overfitting”). It estimates the Sharpe ratio one would expect to observe purely by chance as the maximum of n_trials independent trials under the null hypothesis of no skill, and uses that expected maximum as the benchmark SR* in the Probabilistic Sharpe Ratio formula instead of a naive benchmark such as 0:

Where SR̂ is the observed Sharpe ratio, S (γ₃) is the skewness and K (γ₄) the non-excess (raw) kurtosis of the same returns, n is the number of return observations, N is n_trials, Var[SR_trials] is the variance of the Sharpe ratios observed across those N trials, γ ≈ 0.5772 is the Euler-Mascheroni constant and Φ is the standard normal CDF. Since DSR = PSR(SR*), it is always less than or equal to the Probabilistic Sharpe Ratio computed against a benchmark of 0.

This codebase does not track “N literal strategy trials” - there is no record of how many parameter combinations were tried before arriving at the current Toolkit configuration. As a documented approximation, Var[SR_trials] is estimated from the variance of an auxiliary rolling Sharpe ratio series (see get_rolling_sharpe_ratio) computed over a trials_window-sized window across the full return history, and n_trials defaults to the number of valid (non-NaN) values in that same rolling series. This treats each rolling window as if it were one “trial” - a reasonable proxy for how dispersed the Sharpe ratio could plausibly have been under different choices, but not a substitute for passing the actual number of variations tried (via n_trials) when that is known, since the quality of the correction depends directly on it.

See definition: https://en.wikipedia.org/wiki/Sharpe_ratio

Also known as: risk-adjusted return, reward-to-variability ratio. The variants are also known as the Pezier and White Adjusted Sharpe Ratio (ASR), the Sharpe ratio significance probability (PSR) and the backtest overfitting or selection-bias-adjusted Sharpe ratio (DSR).

Args:

• period (str, optional): The period to use for the calculation. Defaults to “quarterly” if the Toolkit is initialised with quarterly=True, otherwise “yearly”.
• rolling (int, optional): The rolling period to use for the calculation. If you select period = ‘monthly’ and set rolling to 12 you obtain the rolling 12-month Sharpe Ratio.
• method (str, optional): Which Sharpe ratio to calculate, one of “standard”, “adjusted”, “probabilistic” or “deflated”, as described above. Defaults to “standard”.
• benchmark_sharpe_ratio (float, optional): The hypothesized or benchmark Sharpe ratio (SR*) to test the observed Sharpe ratio against. Only used when method=”probabilistic”. Defaults to 0.0, i.e. testing whether the strategy has any skill at all above doing nothing.
• trials_window (int, optional): The window size (in units of period) used for the auxiliary rolling Sharpe ratio series that approximates Var[SR_trials] and the default n_trials, see above. Only used when method=”deflated”. Defaults to None, which uses half of the available return history so that enough overlapping windows exist regardless of period or date range.
• n_trials (int, optional): The number of independent (or effectively independent) strategy variations, parameter combinations, or lookback windows tried before arriving at the reported Sharpe ratio. Only used when method=”deflated”. Defaults to None, which falls back to the number of valid values in the auxiliary rolling Sharpe ratio series described above. Pass this explicitly whenever the actual number of trials is known.
• rounding (int, optional): The number of decimals to round the results to. Defaults to 4.
• growth (bool, optional): Whether to calculate the growth of the ratios. Defaults to False.
• lag (int \| str, optional): The lag to use for the growth calculation. Defaults to 1.
• standardize (bool, optional): Whether to standardize (Z-Score) the result. When combined with growth=True, standardizes the growth values instead of the raw values. Defaults to False.

Returns:

pd.DataFrame: Sharpe ratio values. For method=”probabilistic” and method=”deflated” these are probabilities between 0 and 1 rather than ratios.

Notes:

• Daily Sharpe Ratio is not an option as the standard deviation for 1 day is close to zero. Therefore, it does not give any useful insights.
• The method retrieves historical data and calculates the Sharpe ratio for each asset in the Toolkit instance.
• The risk-free rate is often represented by the return of a risk-free investment, such as a Treasury bond.
• The “adjusted”, “probabilistic” and “deflated” variants use the non-excess (raw) kurtosis convention, i.e. a Normal distribution has a kurtosis of 3, not 0. Internally this calls risk_model.get_kurtosis(..., fisher=False).
• If growth is set to True, the method calculates the growth of the ratio values using the specified lag.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.performance.get_sharpe_ratio()

Which returns:

And, asking for the probability that these Sharpe ratios are genuine instead:

toolkit.performance.get_sharpe_ratio(method="probabilistic")

get_sortino_ratio

The Sortino Ratio is a financial metric used to assess the risk-adjusted performance of an investment portfolio or asset by considering only the downside risk. It measures the excess return generated by the portfolio per unit of downside risk, specifically, the standard deviation of negative returns. The Sortino Ratio is particularly useful for investors who are primarily concerned with minimizing the downside risk of their investments.

The formula is as follows:

Where N is the total number of observations, not just the negative ones, following Sortino & Price (1994). By default one Sortino ratio is reported per period, computed from the daily excess returns falling inside that period. For a given period, for example monthly, this translates into the following:

For a rolling period, period instead sets the frequency of the returns themselves and the ratio is computed over a rolling window of rolling such returns:

Note that this is explicitly already subtracts the Risk Free Rate.

As with the Sharpe Ratio, the result is not annualized: it is a per-observation ratio, so multiply by SQRT(252), SQRT(52), SQRT(12) or SQRT(4) for daily, weekly, monthly or quarterly returns respectively before comparing against published annualized figures.

See definition: https://en.wikipedia.org/wiki/Sortino_ratio

Args:

• period (str, optional): The period to use for the calculation. Defaults to “quarterly” if the Toolkit is initialised with quarterly=True, otherwise “yearly”.
• rolling (int, optional): The rolling window size to use for the calculation. If set, the Sortino ratio is calculated over a rolling window of this many periods across the full return history instead of per period. Defaults to None.
• rounding (int, optional): The number of decimals to round the results to. Defaults to 4.
• growth (bool, optional): Whether to calculate the growth of the ratios. Defaults to False.
• lag (int \| str, optional): The lag to use for the growth calculation. Defaults to 1.
• standardize (bool, optional): Whether to standardize (Z-Score) the result. When combined with growth=True, standardizes the growth values instead of the raw values. Defaults to False.

Returns:

pd.DataFrame: Sortino ratio values.

Notes:

• Daily Sortino Ratio is not an option as the standard deviation for 1 day is close to zero. Therefore, it does not give any useful insights.
• The method retrieves historical data and calculates the Sortino ratio for each asset in the Toolkit instance.
• The risk-free rate is often represented by the return of a risk-free investment, such as a Treasury bond.
• If growth is set to True, the method calculates the growth of the ratio values using the specified lag.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.performance.get_sortino_ratio()

Which returns:

get_ulcer_performance_index

Calculate the Ulcer Performance Index (UPI), alternatively called Martin ratio, a measure of risk-adjusted return that evaluates the excess return of an investment portfolio or asset per unit of risk taken.

It can be used to compare volatilities in different stocks or show stocks go into Ulcer territory. Similar to the Sharpe Ratio, a higher UPI is better than a lower one (since investors prefer more return for less risk).

Also known as: UPI, Martin ratio.

Args:

• period (str, optional): The period to use for the calculation. Defaults to “quarterly” if the Toolkit is initialised with quarterly=True, otherwise “yearly”.
• rolling (int): The rolling period to use to calculate the Ulcer Index. Defaults to 14.
• rounding (int, optional): The number of decimals to round the results to. Defaults to 4.
• growth (bool, optional): Whether to calculate the growth of the ratios. Defaults to False.
• lag (int \| str, optional): The lag to use for the growth calculation. Defaults to 1.
• standardize (bool, optional): Whether to standardize (Z-Score) the result. When combined with growth=True, standardizes the growth values instead of the raw values. Defaults to False.

Returns:

pd.DataFrame: Ulcer Performance Index values.

Notes:

• The method retrieves historical data and calculates the UPI for each asset in the Toolkit instance.
• The risk-free rate is often represented by the return of a risk-free investment, such as a Treasury bond.
• If growth is set to True, the method calculates the growth of the ratio values using the specified lag.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.performance.get_ulcer_performance_index()

Which returns:

get_calmar_ratio

Calculate the Calmar Ratio of an investment portfolio or asset’s returns.

The Calmar Ratio is a risk-adjusted return metric that divides the (annualized) return of an investment portfolio or asset by its Maximum Drawdown, providing insight into the return achieved per unit of the worst historical loss of value.

The formula is as follows:

See definition: https://en.wikipedia.org/wiki/Calmar_ratio

Also known as: Drawdown ratio.

Args:

• period (str, optional): The period to use for the calculation. Defaults to “quarterly” if the Toolkit is initialised with quarterly=True, otherwise “yearly”.
• within_period (bool, optional): Whether to calculate the Maximum Drawdown within the specified period or for the entire period. Thus whether to look at the Maximum Drawdown within a specific year (if period = ‘yearly’) or look at the entirety of all years. Defaults to True.
• rounding (int, optional): The number of decimals to round the results to. Defaults to 4.
• growth (bool, optional): Whether to calculate the growth of the ratios. Defaults to False.
• lag (int \| str, optional): The lag to use for the growth calculation. Defaults to 1.
• standardize (bool, optional): Whether to standardize (Z-Score) the result. When combined with growth=True, standardizes the growth values instead of the raw values. Defaults to False.

Returns:

pd.DataFrame: Calmar Ratio values.

Notes:

• The method retrieves historical data and calculates the Calmar Ratio for each asset in the Toolkit instance.
• If growth is set to True, the method calculates the growth of the ratio values using the specified lag.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.performance.get_calmar_ratio()

Which returns:

get_sterling_ratio

Calculate the Sterling Ratio of an investment portfolio or asset’s returns.

The Sterling Ratio is a risk-adjusted return metric that divides the (annualized) return of an investment portfolio or asset by its Average Drawdown plus a fixed adjustment (conventionally 10%), providing insight into the return achieved relative to the typical depth of its drawdowns rather than only the single worst one (as with the Calmar Ratio).

The formula is as follows:

Also known as: Sterling-Calmar ratio.

Args:

• period (str, optional): The period to use for the calculation. Defaults to “quarterly” if the Toolkit is initialised with quarterly=True, otherwise “yearly”.
• within_period (bool, optional): Whether to calculate the Average Drawdown within the specified period or for the entire period. Thus whether to look at the Average Drawdown within a specific year (if period = ‘yearly’) or look at the entirety of all years. Defaults to True.
• adjustment (float, optional): The fixed adjustment added to the Average Drawdown, conventionally 0.1 (10%). Defaults to 0.1.
• rounding (int, optional): The number of decimals to round the results to. Defaults to 4.
• growth (bool, optional): Whether to calculate the growth of the ratios. Defaults to False.
• lag (int \| str, optional): The lag to use for the growth calculation. Defaults to 1.
• standardize (bool, optional): Whether to standardize (Z-Score) the result. When combined with growth=True, standardizes the growth values instead of the raw values. Defaults to False.

Returns:

pd.DataFrame: Sterling Ratio values.

Notes:

• The method retrieves historical data and calculates the Sterling Ratio for each asset in the Toolkit instance.
• If growth is set to True, the method calculates the growth of the ratio values using the specified lag.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.performance.get_sterling_ratio()

Which returns:

get_burke_ratio

Calculate the Burke Ratio of an investment portfolio or asset’s returns.

The Burke Ratio is a risk-adjusted return metric that divides the excess return (return minus the risk-free rate) of an investment portfolio or asset by the square root of the sum of its squared drawdowns, penalizing both the frequency and depth of drawdowns more heavily than the Calmar or Sterling Ratios.

The formula is as follows:

Args:

• period (str, optional): The period to use for the calculation. Defaults to “quarterly” if the Toolkit is initialised with quarterly=True, otherwise “yearly”.
• within_period (bool, optional): Whether to calculate the drawdowns within the specified period or for the entire period. Thus whether to look at the drawdowns within a specific year (if period = ‘yearly’) or look at the entirety of all years. Defaults to True.
• rounding (int, optional): The number of decimals to round the results to. Defaults to 4.
• growth (bool, optional): Whether to calculate the growth of the ratios. Defaults to False.
• lag (int \| str, optional): The lag to use for the growth calculation. Defaults to 1.
• standardize (bool, optional): Whether to standardize (Z-Score) the result. When combined with growth=True, standardizes the growth values instead of the raw values. Defaults to False.

Returns:

pd.DataFrame: Burke Ratio values.

Notes:

• The method retrieves historical data and calculates the Burke Ratio for each asset in the Toolkit instance.
• The risk-free rate is often represented by the return of a risk-free investment, such as a Treasury bond.
• If growth is set to True, the method calculates the growth of the ratio values using the specified lag.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.performance.get_burke_ratio()

Which returns:

get_m2_ratio

The M2 Ratio, also known as the Modigliani-Modigliani Measure, is a financial metric used to evaluate the risk-adjusted performance of an investment portfolio or strategy. It assesses the excess return generated by the portfolio relative to a risk-free investment, taking into account the portfolio’s volatility or risk. The M2 Ratio helps investors and portfolio managers determine whether the portfolio is delivering returns that justify its level of risk.

The formula is as follows:

This rescales the (dimensionless) Sharpe ratio back into return-space by asking what return the portfolio would have earned had it been leveraged or de-leveraged, via risk-free borrowing or lending, to match the benchmark’s volatility exactly – producing a number directly comparable to the benchmark’s actual return. Requires a benchmark_ticker to be set on the Toolkit instance, since the benchmark’s standard deviation is part of the formula.

See definition: https://en.wikipedia.org/wiki/Modigliani_risk-adjusted_performance

Also known as: Modigliani-Modigliani measure, M2, risk-adjusted performance.

Args:

• period (str, optional): The period to use for the calculation. Defaults to “quarterly” if the Toolkit is initialised with quarterly=True, otherwise “yearly”.
• rolling (int, optional): The rolling window size to use for the calculation. If set, the M2 ratio is calculated over a rolling window of this many periods across the full return history instead of per period. Defaults to None.
• rounding (int, optional): The number of decimals to round the results to. Defaults to 4.
• growth (bool, optional): Whether to calculate the growth of the ratios. Defaults to False.
• lag (int \| str, optional): The lag to use for the growth calculation. Defaults to 1.
• standardize (bool, optional): Whether to standardize (Z-Score) the result. When combined with growth=True, standardizes the growth values instead of the raw values. Defaults to False.

Returns:

pd.DataFrame: M2 ratio values.

Notes:

• Daily M2 is not an option as the standard deviation for 1 day is close to zero. Therefore, it does not give any useful insights.
• The method retrieves historical data and calculates the M2 for each asset in the Toolkit instance.
• The risk-free rate is often represented by the return of a risk-free investment, such as a Treasury bond.
• If growth is set to True, the method calculates the growth of the ratio values using the specified lag.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.performance.get_m2_ratio()

Which returns:

get_tracking_error

Tracking Error is a financial metric that quantifies the volatility or dispersion of the difference between the returns of an investment portfolio or asset and the returns of a benchmark index. It measures how closely the portfolio tracks its benchmark and provides insights into the consistency of the portfolio’s performance relative to the benchmark. A higher Tracking Error indicates greater divergence from the benchmark, while a lower Tracking Error suggests that the portfolio closely follows the benchmark.

The formula is as follows:

See definition: https://en.wikipedia.org/wiki/Tracking_error

Also known as: active risk, benchmark deviation.

Args:

• period (str, optional): The period to use for the calculation. Defaults to “quarterly” if the Toolkit is initialised with quarterly=True, otherwise “yearly”.
• rolling (int, optional): The rolling window size to use for the calculation. If set, Tracking Error is calculated over a rolling window of this many periods across the full return history instead of per period. Defaults to None.
• rounding (int, optional): The number of decimals to round the results to. Defaults to 4.
• growth (bool, optional): Whether to calculate the growth of the ratios. Defaults to False.
• lag (int \| str, optional): The lag to use for the growth calculation. Defaults to 1.
• standardize (bool, optional): Whether to standardize (Z-Score) the result. When combined with growth=True, standardizes the growth values instead of the raw values. Defaults to False.

Returns:

pd.DataFrame: Tracking error values.

Notes:

• Daily Tracking Error is not an option as the standard deviation for 1 day is close to zero. Therefore, it does not give any useful insights.
• The method retrieves historical data and calculates the TE for each asset in the Toolkit instance.
• The risk-free rate is often represented by the return of a risk-free investment, such as a Treasury bond.
• If growth is set to True, the method calculates the growth of the ratio values using the specified lag.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.performance.get_tracking_error()

Which returns:

get_information_ratio

The Information Ratio (IR), also known as the Information Coefficient, is a financial metric that assesses the risk-adjusted performance of a portfolio or investment strategy relative to a benchmark index. It quantifies how much excess return the portfolio generates for each unit of tracking error (volatility of tracking error). The Information Ratio is commonly used by portfolio managers, financial analysts, and investors to evaluate the skill of a portfolio manager in generating returns beyond what would be expected based on the risk taken.

• IR > 0: A positive Information Ratio indicates that the portfolio has generated excess returns compared to the benchmark, suggesting that the portfolio manager has added value.
• IR = 0: An Information Ratio of zero implies that the portfolio’s excess return is in line with the benchmark, meaning the portfolio manager has not added or lost value relative to the benchmark.
• IR < 0: A negative Information Ratio suggests that the portfolio has underperformed the benchmark, potentially indicating that the portfolio manager has detracted value.

The formula is as follows:

See definition: https://en.wikipedia.org/wiki/Information_ratio

Also known as: active return per risk.

Args:

• period (str, optional): The period to use for the calculation. Defaults to “quarterly” if the Toolkit is initialised with quarterly=True, otherwise “yearly”.
• rolling (int, optional): The rolling window size to use for the calculation. If set, the Information Ratio is calculated over a rolling window of this many periods across the full return history instead of per period. Defaults to None.
• rounding (int, optional): The number of decimals to round the results to. Defaults to 4.
• growth (bool, optional): Whether to calculate the growth of the ratios. Defaults to False.
• lag (int \| str, optional): The lag to use for the growth calculation. Defaults to 1.
• standardize (bool, optional): Whether to standardize (Z-Score) the result. When combined with growth=True, standardizes the growth values instead of the raw values. Defaults to False.

Returns:

pd.DataFrame: Information ratio values.

Notes:

• Daily Information Ratio is not an option as the standard deviation for 1 day is close to zero. Therefore, it does not give any useful insights.
• The method retrieves historical data and calculates the IR for each asset in the Toolkit instance.
• The risk-free rate is often represented by the return of a risk-free investment, such as a Treasury bond.
• If growth is set to True, the method calculates the growth of the ratio values using the specified lag.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.performance.get_information_ratio()

Which returns:

get_upside_capture_ratio

Calculate the Upside Capture Ratio of an investment portfolio or asset’s returns.

The Upside Capture Ratio measures how well an investment portfolio or asset performs relative to a benchmark during periods in which the benchmark’s return is positive. A ratio above 1 (or 100%) indicates the asset captured more of the benchmark’s gains than the benchmark itself.

The formula is as follows:

Args:

• period (str, optional): The period to use for the calculation. Defaults to “quarterly” if the Toolkit is initialised with quarterly=True, otherwise “yearly”.
• rounding (int, optional): The number of decimals to round the results to. Defaults to 4.
• growth (bool, optional): Whether to calculate the growth of the ratios. Defaults to False.
• lag (int \| str, optional): The lag to use for the growth calculation. Defaults to 1.
• standardize (bool, optional): Whether to standardize (Z-Score) the result. When combined with growth=True, standardizes the growth values instead of the raw values. Defaults to False.

Returns:

pd.DataFrame: Upside Capture Ratio values.

Notes:

• The method retrieves historical data and calculates the Upside Capture Ratio for each asset in the Toolkit instance.
• If growth is set to True, the method calculates the growth of the ratio values using the specified lag.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.performance.get_upside_capture_ratio()

Which returns:

get_downside_capture_ratio

Calculate the Downside Capture Ratio of an investment portfolio or asset’s returns.

The Downside Capture Ratio measures how well an investment portfolio or asset performs relative to a benchmark during periods in which the benchmark’s return is negative. A ratio below 1 (or 100%) indicates the asset lost less than the benchmark during those periods.

The formula is as follows:

Args:

• period (str, optional): The period to use for the calculation. Defaults to “quarterly” if the Toolkit is initialised with quarterly=True, otherwise “yearly”.
• rounding (int, optional): The number of decimals to round the results to. Defaults to 4.
• growth (bool, optional): Whether to calculate the growth of the ratios. Defaults to False.
• lag (int \| str, optional): The lag to use for the growth calculation. Defaults to 1.
• standardize (bool, optional): Whether to standardize (Z-Score) the result. When combined with growth=True, standardizes the growth values instead of the raw values. Defaults to False.

Returns:

pd.DataFrame: Downside Capture Ratio values.

Notes:

• The method retrieves historical data and calculates the Downside Capture Ratio for each asset in the Toolkit instance.
• If growth is set to True, the method calculates the growth of the ratio values using the specified lag.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.performance.get_downside_capture_ratio()

Which returns:

get_win_rate

Calculate the Win Rate of an investment portfolio or asset’s returns.

The Win Rate is the percentage of periods in which the asset’s return exceeds the benchmark’s return.

Also known as: batting average.

Args:

• period (str, optional): The period to use for the calculation. Defaults to “quarterly” if the Toolkit is initialised with quarterly=True, otherwise “yearly”.
• rounding (int, optional): The number of decimals to round the results to. Defaults to 4.
• growth (bool, optional): Whether to calculate the growth of the ratios. Defaults to False.
• lag (int \| str, optional): The lag to use for the growth calculation. Defaults to 1.
• standardize (bool, optional): Whether to standardize (Z-Score) the result. When combined with growth=True, standardizes the growth values instead of the raw values. Defaults to False.

Returns:

pd.DataFrame: Win Rate values.

Notes:

• The method retrieves historical data and calculates the Win Rate for each asset in the Toolkit instance.
• If growth is set to True, the method calculates the growth of the ratio values using the specified lag.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.performance.get_win_rate()

Which returns:

get_kappa_ratio

Calculate the Kappa Ratio of an investment portfolio or asset’s returns.

The Kappa Ratio is a generalization of the Sortino Ratio that penalizes downside risk using a higher-order lower partial moment. The Sortino Ratio is the special case of the Kappa Ratio with order=2.

Note that this already subtracts the Risk Free Rate.

Args:

• period (str, optional): The period to use for the calculation. Defaults to “quarterly” if the Toolkit is initialised with quarterly=True, otherwise “yearly”.
• order (int, optional): The order of the lower partial moment used in the denominator. Defaults to 3.
• rounding (int, optional): The number of decimals to round the results to. Defaults to 4.
• growth (bool, optional): Whether to calculate the growth of the ratios. Defaults to False.
• lag (int \| str, optional): The lag to use for the growth calculation. Defaults to 1.
• standardize (bool, optional): Whether to standardize (Z-Score) the result. When combined with growth=True, standardizes the growth values instead of the raw values. Defaults to False.

Returns:

pd.DataFrame: Kappa Ratio values.

Notes:

• Daily Kappa Ratio is not an option as the standard deviation for 1 day is close to zero. Therefore, it does not give any useful insights.
• The method retrieves historical data and calculates the Kappa Ratio for each asset in the Toolkit instance.
• The risk-free rate is often represented by the return of a risk-free investment, such as a Treasury bond.
• If growth is set to True, the method calculates the growth of the ratio values using the specified lag.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.performance.get_kappa_ratio()

Which returns:

get_omega_ratio

Calculate the Omega Ratio of an investment portfolio or asset’s returns.

The Omega Ratio is a risk-return measure that divides the sum of gains above a minimum acceptable return (MAR) by the sum of losses below it, capturing the full shape of the return distribution rather than only its first two moments (unlike the Sharpe Ratio).

The formula is as follows:

See definition: https://en.wikipedia.org/wiki/Omega_ratio

Args:

• period (str, optional): The period to use for the calculation. Defaults to “quarterly” if the Toolkit is initialised with quarterly=True, otherwise “yearly”.
• within_period (bool, optional): Whether to calculate the Omega Ratio within the specified period or for the entire period. Thus whether to look at the Omega Ratio within a specific year (if period = ‘yearly’) or look at the entirety of all years. Defaults to True.
• rolling (int, optional): The rolling window size to use for the calculation. If set, the Omega Ratio is calculated over a rolling window of this many periods across the full return history instead of per period. Defaults to None.
• minimum_acceptable_return (float, optional): The minimum acceptable return (MAR) used as the threshold between gains and losses. Defaults to 0.0.
• rounding (int, optional): The number of decimals to round the results to. Defaults to 4.
• growth (bool, optional): Whether to calculate the growth of the ratios. Defaults to False.
• lag (int \| str, optional): The lag to use for the growth calculation. Defaults to 1.
• standardize (bool, optional): Whether to standardize (Z-Score) the result. When combined with growth=True, standardizes the growth values instead of the raw values. Defaults to False.

Returns:

pd.DataFrame: Omega Ratio values.

Notes:

• The method retrieves historical data and calculates the Omega Ratio for each asset in the Toolkit instance.
• If growth is set to True, the method calculates the growth of the ratio values using the specified lag.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.performance.get_omega_ratio()

Which returns:

get_gain_to_pain_ratio

Calculate the Gain-to-Pain Ratio of an investment portfolio or asset’s returns.

The Gain-to-Pain Ratio, popularized by Jack Schwager, divides the sum of all returns by the sum of the absolute value of all losses, summarizing the entire return history into a single measure of return earned per unit of pain endured.

The formula is as follows:

Args:

• period (str, optional): The period to use for the calculation. Defaults to “quarterly” if the Toolkit is initialised with quarterly=True, otherwise “yearly”.
• within_period (bool, optional): Whether to calculate the Gain-to-Pain Ratio within the specified period or for the entire period. Thus whether to look at the Gain-to-Pain Ratio within a specific year (if period = ‘yearly’) or look at the entirety of all years. Defaults to True.
• rounding (int, optional): The number of decimals to round the results to. Defaults to 4.
• growth (bool, optional): Whether to calculate the growth of the ratios. Defaults to False.
• lag (int \| str, optional): The lag to use for the growth calculation. Defaults to 1.
• standardize (bool, optional): Whether to standardize (Z-Score) the result. When combined with growth=True, standardizes the growth values instead of the raw values. Defaults to False.

Returns:

pd.DataFrame: Gain-to-Pain Ratio values.

Notes:

• The method retrieves historical data and calculates the Gain-to-Pain Ratio for each asset in the Toolkit instance.
• If growth is set to True, the method calculates the growth of the ratio values using the specified lag.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.performance.get_gain_to_pain_ratio()

Which returns:

get_compound_growth_rate

This function calculates the Compound Growth Rate (CGR) for different periods: yearly, quarterly, monthly, weekly, and daily.

The CGR is a measure that provides the mean growth rate of an investment over a specified period of time. It is a useful measure for comparing the performance of investments over different time periods or across different asset classes. The CGR is calculated by taking the ratio of the final value to the initial value, raising it to the inverse of the number of periods, and then subtracting one.

The formula is as follows:

Also known as: CAGR, compound annual growth rate, annualized return.

Args:

• rounding (int, optional): The number of decimals to round the results to. If not provided, the function will use the default rounding value set in the class instance.

Returns:

pd.DataFrame: A DataFrame containing the CGR for each period. The DataFrame has the periods as the index and the CGR values as the column.

Notes:

• When verifying the calculation, note that rounding applies and it could be slightly off because of that This is mostly noticeable when looking at the Compound Daily Growth Rate. Adjust the rounding with the rounding parameter accordingly to get a more precise figure.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.performance.get_compound_growth_rate()

Which returns:

get_returns

Calculate the Return of an investment portfolio or asset for a given period based on the daily historical returns.

The period Return is obtained by compounding the daily returns within each period, following the formula:

If cumulative is set to True, the period returns are compounded further into a cumulative return over time instead. The cumulative return is always rebased to start at 1 at the beginning of the selected date range.

Also known as: periodic return.

Args:

• period (str, optional): The data frequency for returns (weekly, monthly, quarterly, or yearly). Defaults to “quarterly” if the Toolkit is initialised with quarterly=True, otherwise “yearly”.
• cumulative (bool, optional): Whether to return the cumulative return over time instead of the discrete return per period. Defaults to False.
• rounding (int \| None, optional): The number of decimals to round the results to. Defaults to 4.
• growth (bool, optional): Whether to calculate the growth of the Return values over time. Defaults to False.
• lag (int \| list[int], optional): The lag to use for the growth calculation. Defaults to 1.
• standardize (bool, optional): Whether to standardize (Z-Score) the result. When combined with growth=True, standardizes the growth values instead of the raw values. Defaults to False.

Returns:

pd.Series: Return values with time as the index.

Notes:

• The method retrieves the daily historical return data and calculates the Return for the specified period for each asset in the Toolkit instance.
• If growth is set to True, the method calculates the growth of Return values using the specified lag.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AMZN", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.performance.get_returns(period="yearly")

Which returns:

get_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.

If cumulative is set to True, the excess returns are compounded further into a cumulative excess return over time instead. The cumulative excess return is always rebased to start at 1 at the beginning of the selected date range.

Also known as: return minus the risk-free rate.

Args:

• period (str, optional): The data frequency for returns (weekly, monthly, quarterly, or yearly). Defaults to “quarterly” if the Toolkit is initialised with quarterly=True, otherwise “yearly”.
• cumulative (bool, optional): Whether to return the cumulative excess return over time instead of the discrete excess return per period. Defaults to False.
• rounding (int \| None, optional): The number of decimals to round the results to. Defaults to 4.
• growth (bool, optional): Whether to calculate the growth of the Excess Return values over time. Defaults to False.
• lag (int \| list[int], optional): The lag to use for the growth calculation. Defaults to 1.
• standardize (bool, optional): Whether to standardize (Z-Score) the result. When combined with growth=True, standardizes the growth values instead of the raw values. Defaults to False.

Returns:

pd.Series: Excess Return values with time as the index.

Notes:

• The method retrieves the daily historical return data and calculates the Excess Return for the specified period for each asset in the Toolkit instance.
• The risk-free rate is often represented by the return of a risk-free investment, such as a Treasury bond.
• If growth is set to True, the method calculates the growth of Excess Return values using the specified lag.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AMZN", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.performance.get_excess_return(period="yearly")

Which returns:

get_correlation_matrix

Calculate the full pairwise Correlation Matrix across all assets (and the benchmark) in the Toolkit instance, based on the returns at the frequency given by period.

Unlike get_beta, which relates a single asset to the benchmark, this computes the correlation between every pair of assets at once. This is a prerequisite for portfolio variance calculations and any mean-variance optimization work.

Args:

• period (str, optional): The data frequency for returns (weekly, monthly, quarterly, or yearly). Defaults to “quarterly” if the Toolkit is initialised with quarterly=True, otherwise “yearly”.
• rounding (int \| None, optional): The number of decimals to round the results to. Defaults to 4.

Returns:

pd.DataFrame: The N x N Correlation Matrix, with assets as both the index and the columns.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AMZN", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.performance.get_correlation_matrix()

Which returns:

get_covariance_matrix

Calculate the full pairwise Covariance Matrix across all assets (and the benchmark) in the Toolkit instance, based on the returns at the frequency given by period.

Unlike get_covariance, which relates a single asset to the benchmark, this computes the covariance between every pair of assets at once. This is a prerequisite for portfolio variance calculations and any mean-variance optimization work.

Args:

• period (str, optional): The data frequency for returns (weekly, monthly, quarterly, or yearly). Defaults to “quarterly” if the Toolkit is initialised with quarterly=True, otherwise “yearly”.
• rounding (int \| None, optional): The number of decimals to round the results to. Defaults to 4.

Returns:

pd.DataFrame: The N x N Covariance Matrix, with assets as both the index and the columns.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AMZN", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.performance.get_covariance_matrix()

Which returns:

get_appraisal_ratio

Calculate the Appraisal Ratio, i.e. Jensen’s Alpha divided by the idiosyncratic (residual, unsystematic) standard deviation left over from the CAPM regression that produced that Alpha.

Jensen’s Alpha (see get_jensens_alpha) measures how much return a manager generated above what CAPM would predict given the asset’s Beta. However, a large Alpha achieved with wildly noisy, unpredictable residual returns is far less attractive than the same Alpha achieved consistently. The Appraisal Ratio normalizes Alpha by that noise (the “specific risk” not explained by market exposure), giving a Sharpe-ratio-like measure of stock-picking or timing skill per unit of idiosyncratic risk taken.

The formula is as follows:

Where the residual standard deviation is the standard deviation of the pointwise CAPM regression residuals (Asset Excess Return − Beta * Benchmark Excess Return), reusing the exact same CAPM regression formula as get_jensens_alpha.

See definition: https://en.wikipedia.org/wiki/Information_ratio

Also known as: Treynor-Black Appraisal Ratio.

Args:

• period (str, optional): The period to use for the calculation. Defaults to “quarterly” if the Toolkit is initialised with quarterly=True, otherwise “yearly”.
• rolling (int, optional): The rolling window size to use for the Beta component of the calculation. If set, Beta is estimated over a rolling window of this many periods across the full return history instead of per period. Defaults to None.
• rounding (int, optional): The number of decimals to round the results to. Defaults to 4.
• growth (bool, optional): Whether to calculate the growth of the ratios. Defaults to False.
• lag (int \| str, optional): The lag to use for the growth calculation. Defaults to 1.
• standardize (bool, optional): Whether to standardize (Z-Score) the result. When combined with growth=True, standardizes the growth values instead of the raw values. Defaults to False.

Returns:

pd.DataFrame: Appraisal Ratio values.

Notes:

• Daily Appraisal Ratio is not an option as the standard deviation for 1 day is close to zero. Therefore, it does not give any useful insights.
• The method retrieves historical data and calculates Jensen’s Alpha and the CAPM regression residuals for each asset in the Toolkit instance, reusing the same Beta and CAPM formula as get_jensens_alpha.
• If growth is set to True, the method calculates the growth of the ratio values using the specified lag.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.performance.get_appraisal_ratio()

Which returns:

get_fama_decomposition

Calculate the Fama (1972) decomposition of total excess return into Selectivity and Diversification.

Jensen’s Alpha alone conflates two very different sources of excess return: genuine stock/timing selection skill, and simply carrying more total risk than the market by holding an under-diversified portfolio (which, in a CAPM world, should be compensated with extra return even absent any skill). Fama’s decomposition separates the two by comparing the portfolio’s actual return against two different CAPM-implied return benchmarks: one using the portfolio’s actual Beta (systematic risk only), and one using the portfolio’s actual total risk ratio (Sigma_Portfolio / Sigma_Market) in place of Beta.

The formulas are as follows:

Selectivity is the return earned above what would be required for a fully diversified portfolio carrying the same total risk, i.e. genuine security selection or timing skill. Diversification is the extra return the manager left on the table (if positive, it is a cost) by taking on unsystematic risk that a fully diversified portfolio of the same total risk would not have. Selectivity plus Diversification equals Jensen’s Alpha (see get_jensens_alpha).

Also known as: Fama’s Net Selectivity, Fama performance decomposition.

Args:

• period (str, optional): The period to use for the calculation. Defaults to “quarterly” if the Toolkit is initialised with quarterly=True, otherwise “yearly”.
• rolling (int, optional): The rolling window size to use for the Beta component of the calculation. If set, Beta is estimated over a rolling window of this many periods across the full return history instead of per period. Defaults to None.
• rounding (int, optional): The number of decimals to round the results to. Defaults to 4.
• growth (bool, optional): Whether to calculate the growth of the ratios. Defaults to False.
• lag (int \| str, optional): The lag to use for the growth calculation. Defaults to 1.
• standardize (bool, optional): Whether to standardize (Z-Score) the result. When combined with growth=True, standardizes the growth values instead of the raw values. Defaults to False.

Returns:

pd.DataFrame: Selectivity and Diversification values, with a Multi Index of (ticker, component) as the columns.

Notes:

• Daily Fama Decomposition is not an option as the standard deviation for 1 day is close to zero. Therefore, it does not give any useful insights.
• The method retrieves historical data and calculates Beta, the asset’s and benchmark’s standard deviation, and the Selectivity and Diversification components for each asset in the Toolkit instance.
• If growth is set to True, the method calculates the growth of the ratio values using the specified lag.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.performance.get_fama_decomposition().xs("AAPL", level=0, axis=1)

Which returns:

get_starr_ratio

Calculate the STARR (Stable Tail Adjusted Return Ratio) of an investment portfolio or asset’s returns.

The Sharpe ratio penalizes upside and downside volatility equally via the standard deviation. The STARR ratio instead scales the mean excess return by the Conditional Value at Risk (CVaR / Expected Shortfall), a coherent tail-risk measure that only looks at the average magnitude of losses beyond the alpha quantile. This makes STARR more appropriate than the Sharpe ratio for return distributions with fat left tails.

The formula is as follows:

See definition: https://en.wikipedia.org/wiki/Expected_shortfall

Also known as: Stable Tail Adjusted Return Ratio, Conditional Sharpe Ratio.

Args:

• period (str, optional): The period to use for the calculation. Defaults to “quarterly” if the Toolkit is initialised with quarterly=True, otherwise “yearly”.
• within_period (bool, optional): Whether to calculate the CVaR within the specified period or for the entire period. Thus whether to look at the CVaR within a specific year (if period = ‘yearly’) or look at the entirety of all years. Defaults to True.
• alpha (float, optional): The confidence level used for the CVaR calculation (e.g. 0.05 for the worst 5% of outcomes). Defaults to 0.05.
• rounding (int, optional): The number of decimals to round the results to. Defaults to 4.
• growth (bool, optional): Whether to calculate the growth of the ratios. Defaults to False.
• lag (int \| str, optional): The lag to use for the growth calculation. Defaults to 1.
• standardize (bool, optional): Whether to standardize (Z-Score) the result. When combined with growth=True, standardizes the growth values instead of the raw values. Defaults to False.

Returns:

pd.DataFrame: STARR Ratio values.

Notes:

• The method retrieves historical data and calculates the STARR Ratio for each asset in the Toolkit instance.
• Periods with very few return observations (e.g. a partial period at the very start of the selected date range) can produce a degenerate (e.g. zero or ±infinite) CVaR, since CVaR is not a meaningful statistic with only one or two data points. This mirrors the analogous caveat for the Sharpe Ratio needing enough observations for its standard deviation to be meaningful.
• If growth is set to True, the method calculates the growth of the ratio values using the specified lag.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.performance.get_starr_ratio()

Which returns:

get_rachev_ratio

Calculate the Rachev Ratio (R-Ratio) of an investment portfolio or asset’s returns.

The Rachev ratio compares the “quality” of the best outcomes to the “quality” of the worst outcomes by taking the ratio of the right-tail Expected Shortfall (the average of the best alpha fraction of returns) to the left-tail Expected Shortfall (the average magnitude of the worst alpha fraction of returns). A ratio above 1 indicates that the average size of extreme gains outweighs the average size of extreme losses.

The formula is as follows:

Also known as: R-Ratio.

Args:

• period (str, optional): The period to use for the calculation. Defaults to “quarterly” if the Toolkit is initialised with quarterly=True, otherwise “yearly”.
• within_period (bool, optional): Whether to calculate the Rachev Ratio within the specified period or for the entire period. Thus whether to look at the return distribution within a specific year (if period = ‘yearly’) or look at the entirety of all years. Defaults to True.
• alpha (float, optional): The confidence level used for both tails (e.g. 0.05 for the best/worst 5% of outcomes). Defaults to 0.05.
• rounding (int, optional): The number of decimals to round the results to. Defaults to 4.
• growth (bool, optional): Whether to calculate the growth of the ratios. Defaults to False.
• lag (int \| str, optional): The lag to use for the growth calculation. Defaults to 1.
• standardize (bool, optional): Whether to standardize (Z-Score) the result. When combined with growth=True, standardizes the growth values instead of the raw values. Defaults to False.

Returns:

pd.DataFrame: Rachev Ratio values.

Notes:

• The method retrieves historical data and calculates the Rachev Ratio for each asset in the Toolkit instance.
• If growth is set to True, the method calculates the growth of the ratio values using the specified lag.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.performance.get_rachev_ratio()

Which returns:

get_treynor_mazuy_model

Calculate the Treynor-Mazuy market timing model for each asset in the Toolkit instance.

Jensen’s Alpha and Beta from a plain CAPM regression cannot distinguish stock-picking skill (selectivity) from market-timing skill (shifting exposure ahead of market moves). The Treynor-Mazuy model adds a quadratic term in the benchmark excess return to the regression: a manager who successfully increases (decreases) market exposure ahead of up (down) markets will show a return profile that curves upward as a function of the benchmark return, captured by a positive quadratic coefficient (Gamma).

The formula is as follows:

Gamma > 0 indicates positive market-timing ability; Gamma <= 0 indicates no timing ability.

Also known as: Treynor-Mazuy quadratic timing model, TM model.

Args:

• period (str, optional): The period to use for the calculation. Defaults to “quarterly” if the Toolkit is initialised with quarterly=True, otherwise “yearly”.
• rounding (int, optional): The number of decimals to round the results to. Defaults to 4.
• growth (bool, optional): Whether to calculate the growth of the ratios. Defaults to False.
• lag (int \| str, optional): The lag to use for the growth calculation. Defaults to 1.
• standardize (bool, optional): Whether to standardize (Z-Score) the result. When combined with growth=True, standardizes the growth values instead of the raw values. Defaults to False.

Returns:

pd.DataFrame: Alpha, Beta, Gamma and R Squared values, with a Multi Index of (ticker, parameter) as the columns.

Notes:

• Daily and weekly Treynor-Mazuy results are not an option as there would be too few observations within each period to run a meaningful regression.
• The method retrieves historical data and performs a quadratic regression for each asset in the Toolkit instance, within each period.
• If growth is set to True, the method calculates the growth of the ratio values using the specified lag.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.performance.get_treynor_mazuy_model().xs("AAPL", level=0, axis=1)

Which returns:

get_henriksson_merton_model

Calculate the Henriksson-Merton market timing model for each asset in the Toolkit instance.

Like the Treynor-Mazuy model (see get_treynor_mazuy_model), this separates market-timing skill from selectivity, but models timing as a piecewise (rather than quadratic) change in Beta: a “down-market” Beta and an “up-market” Beta.

The formula is as follows:

Beta is the “down-market” Beta (the portfolio’s market exposure when the benchmark excess return is negative), and Beta + Up Market Beta is the “up-market” Beta. Up Market Beta > 0 indicates positive market-timing ability; Up Market Beta <= 0 indicates no timing ability.

Also known as: Henriksson-Merton piecewise timing model, HM model.

Args:

• period (str, optional): The period to use for the calculation. Defaults to “quarterly” if the Toolkit is initialised with quarterly=True, otherwise “yearly”.
• rounding (int, optional): The number of decimals to round the results to. Defaults to 4.
• growth (bool, optional): Whether to calculate the growth of the ratios. Defaults to False.
• lag (int \| str, optional): The lag to use for the growth calculation. Defaults to 1.
• standardize (bool, optional): Whether to standardize (Z-Score) the result. When combined with growth=True, standardizes the growth values instead of the raw values. Defaults to False.

Returns:

pd.DataFrame: Alpha, Beta, Up Market Beta and R Squared values, with a Multi Index of (ticker, parameter) as the columns.

Notes:

• Daily and weekly Henriksson-Merton results are not an option as there would be too few observations within each period to run a meaningful regression.
• The method retrieves historical data and performs a piecewise regression for each asset in the Toolkit instance, within each period.
• If growth is set to True, the method calculates the growth of the ratio values using the specified lag.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.performance.get_henriksson_merton_model().xs("AAPL", level=0, axis=1)

Which returns: