financial.sharpe_ratio
======================

.. py:module:: financial.sharpe_ratio

.. autoapi-nested-parse::

   Sharpe Ratio for measuring risk-adjusted returns in investment portfolios.

   The Sharpe Ratio is a measure of risk-adjusted return developed by Nobel laureate
   William F. Sharpe. It calculates the excess return per unit of risk (standard deviation)
   and is widely used to compare the performance of investment portfolios.

   Wikipedia Reference: https://en.wikipedia.org/wiki/Sharpe_ratio
   Investopedia: https://www.investopedia.com/terms/s/sharperatio.asp

   The Sharpe Ratio is used for:
   - Comparing performance of different investment strategies
   - Evaluating mutual funds and hedge funds
   - Portfolio optimization and risk management
   - Assessing risk-adjusted returns in trading strategies



Attributes
----------

.. autoapisummary::

   financial.sharpe_ratio.monthly_returns


Functions
---------

.. autoapisummary::

   financial.sharpe_ratio.annualized_sharpe_ratio
   financial.sharpe_ratio.sharpe_ratio


Module Contents
---------------

.. py:function:: annualized_sharpe_ratio(returns: list[float], risk_free_rate: float = 0.0, periods_per_year: int = 252) -> float

   Calculate the annualized Sharpe Ratio for a series of periodic returns.

   The annualized Sharpe Ratio accounts for the time period of returns:
   S_annual = S_periodic * sqrt(periods_per_year)

   Common periods_per_year values:
   - Daily returns: 252 (trading days)
   - Weekly returns: 52
   - Monthly returns: 12
   - Quarterly returns: 4

   :param returns: List of periodic returns
   :param risk_free_rate: Risk-free rate per period, default 0.0
   :param periods_per_year: Number of periods in a year, default 252 (daily)
   :return: Annualized Sharpe Ratio

   >>> round(annualized_sharpe_ratio(
   ...     [0.001, 0.002, 0.0015, 0.0005, 0.0012], 0.0, 252), 4)
   35.1844
   >>> round(annualized_sharpe_ratio([0.01, 0.02, 0.015, 0.005, 0.012], 0.0, 12), 4)
   7.6779
   >>> round(annualized_sharpe_ratio([0.05, 0.06, 0.055, 0.045, 0.052], 0.0, 4), 4)
   18.7322
   >>> round(annualized_sharpe_ratio([0.001, 0.002, 0.0015], 0.0001, 252), 4)
   44.4486
   >>> round(annualized_sharpe_ratio([0.001, 0.002], 0.0, 252), 4)
   33.6749
   >>> annualized_sharpe_ratio([0.001, 0.002, 0.0015], 0.0, 0)
   Traceback (most recent call last):
       ...
   ValueError: periods_per_year must be > 0
   >>> annualized_sharpe_ratio([0.001, 0.002, 0.0015], 0.0, -252)
   Traceback (most recent call last):
       ...
   ValueError: periods_per_year must be > 0


.. py:function:: sharpe_ratio(returns: list[float], risk_free_rate: float = 0.0) -> float

   Calculate the Sharpe Ratio for a series of returns.

   The Sharpe Ratio formula:
   S = (R - Rf) / std_dev

   Where:
   S = Sharpe Ratio
   R = Average return of the investment
   Rf = Risk-free rate of return
   std_dev = Standard deviation of returns (volatility)

   :param returns: List of periodic returns (e.g., daily, monthly)
   :param risk_free_rate: Risk-free rate of return per period, default 0.0
   :return: Sharpe Ratio

   >>> round(sharpe_ratio([0.1, 0.2, 0.15, 0.05, 0.12]), 4)
   2.2164
   >>> sharpe_ratio([0.05, 0.05, 0.05, 0.05, 0.05])
   inf
   >>> round(sharpe_ratio([0.1, 0.2, 0.15, 0.05, 0.12], 0.02), 4)
   1.8589
   >>> sharpe_ratio([0.0, 0.0, 0.0, 0.0, 0.0])
   0.0
   >>> round(sharpe_ratio([-0.05, -0.1, -0.08, -0.12, -0.15]), 4)
   -2.6261
   >>> sharpe_ratio([])
   Traceback (most recent call last):
       ...
   ValueError: returns list must not be empty
   >>> sharpe_ratio([0.1])
   Traceback (most recent call last):
       ...
   ValueError: returns list must contain at least 2 values


.. py:data:: monthly_returns