openseries 1.9.2__py3-none-any.whl → 1.9.4__py3-none-any.whl

openseries/_common_model.py

@@ -17,7 +17,7 @@ from math import ceil
 from pathlib import Path
 from secrets import choice
 from string import ascii_letters
-from typing import TYPE_CHECKING, Any, SupportsFloat, cast
+from typing import TYPE_CHECKING, Any, Literal, SupportsFloat, cast
 
 from numpy import float64, inf, isnan, log, maximum, sqrt
 
@@ -25,7 +25,9 @@ from .owntypes import (
     DateAlignmentError,
     InitialValueZeroError,
     NumberOfItemsAndLabelsNotSameError,
+    ResampleDataLossError,
     Self,
+    ValueType,
 )
 
 if TYPE_CHECKING:  # pragma: no cover
@@ -47,7 +49,6 @@ if TYPE_CHECKING:  # pragma: no cover
         LiteralPlotlyJSlib,
         LiteralPlotlyOutput,
         LiteralQuantileInterp,
-        ValueType,
     )
 from openpyxl.utils.dataframe import dataframe_to_rows
 from openpyxl.workbook.workbook import Workbook
@@ -263,7 +264,10 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
 
         """
         min_accepted_return: float = 0.0
-        return self.downside_deviation_func(min_accepted_return=min_accepted_return)
+        order: Literal[2, 3] = 2
+        return self.lower_partial_moment_func(
+            min_accepted_return=min_accepted_return, order=order
+        )
 
     @property
     def ret_vol_ratio(self: Self) -> float | Series[float]:
@@ -298,6 +302,32 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
             min_accepted_return=minimum_accepted_return,
         )
 
+    @property
+    def kappa3_ratio(self: Self) -> float | Series[float]:
+        """Kappa-3 ratio.
+
+        The Kappa-3 ratio is a generalized downside-risk ratio defined as
+        annualized arithmetic return divided by the cubic-root of the
+        lower partial moment of order 3 (with respect to a minimum acceptable
+        return, MAR). It penalizes larger downside outcomes more heavily than
+        the Sortino ratio (which uses order 2).
+
+        Returns:
+        -------
+        float | Pandas.Series[float]
+            Kappa-3 ratio calculation with the riskfree rate and
+            Minimum Acceptable Return (MAR) both set to zero.
+
+        """
+        riskfree_rate: float = 0.0
+        minimum_accepted_return: float = 0.0
+        order: Literal[2, 3] = 3
+        return self.sortino_ratio_func(
+            riskfree_rate=riskfree_rate,
+            min_accepted_return=minimum_accepted_return,
+            order=order,
+        )
+
     @property
     def omega_ratio(self: Self) -> float | Series[float]:
         """https://en.wikipedia.org/wiki/Omega_ratio.
@@ -403,6 +433,16 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
 
         wmdf = wmdf.reindex(index=[deyt.date() for deyt in dates], method=method)
         wmdf.index = DatetimeIndex(wmdf.index)
+
+        vtypes = [x == ValueType.RTRN for x in wmdf.columns.get_level_values(1)]
+        if any(vtypes):
+            msg = (
+                "Do not run worst_month on return series. The operation will "
+                "pick the last data point in the sparser series. It will not sum "
+                "returns and therefore data will be lost and result will be wrong."
+            )
+            raise ResampleDataLossError(msg)
+
         result = wmdf.ffill().pct_change().min()
 
         if self.tsdf.shape[1] == 1:
@@ -559,6 +599,7 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
         countries: CountriesType | None = None,
         markets: list[str] | str | None = None,
         custom_holidays: list[str] | str | None = None,
+        method: LiteralPandasReindexMethod = "nearest",
     ) -> Self:
         """Align the index of .tsdf with local calendar business days.
 
@@ -570,6 +611,7 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
             (List of) markets code(s) according to pandas-market-calendars
         custom_holidays: list[str] | str, optional
             Argument where missing holidays can be added
+        method: LiteralPandasReindexMethod, default: "nearest"
 
         Returns:
         -------
@@ -620,7 +662,7 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
                 freq=CustomBusinessDay(calendar=calendar),
             )
         ]
-        self.tsdf = self.tsdf.reindex(d_range, method=None, copy=False)
+        self.tsdf = self.tsdf.reindex(labels=d_range, method=method, copy=False)
 
         return self
 
@@ -1016,7 +1058,7 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
             )
         figure.update_layout(yaxis={"tickformat": tick_fmt})
 
-        if show_last is True:
+        if show_last:
             txt = f"Last {{:{tick_fmt}}}" if tick_fmt else "Last {}"
 
             for item in range(self.tsdf.shape[1]):
@@ -1063,7 +1105,7 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
     def plot_histogram(
         self: Self,
         plot_type: LiteralPlotlyHistogramPlotType = "bars",
-        histnorm: LiteralPlotlyHistogramHistNorm = "percent",
+        histnorm: LiteralPlotlyHistogramHistNorm = "probability",
         barmode: LiteralPlotlyHistogramBarMode = "overlay",
         xbins_size: float | None = None,
         opacity: float = 0.75,
@@ -1167,6 +1209,7 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
                 figure.add_histogram(
                     x=self.tsdf.iloc[:, item],
                     cumulative={"enabled": cumulative},
+                    histfunc="count",
                     histnorm=histnorm,
                     name=labels[item],
                     xbins={"size": xbins_size},
@@ -1640,24 +1683,28 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
             dtype="float64",
         )
 
-    def downside_deviation_func(
+    def lower_partial_moment_func(
         self: Self,
         min_accepted_return: float = 0.0,
+        order: Literal[2, 3] = 2,
         months_from_last: int | None = None,
         from_date: dt.date | None = None,
         to_date: dt.date | None = None,
         periods_in_a_year_fixed: DaysInYearType | None = None,
     ) -> float | Series[float]:
-        """Downside Deviation.
+        """Downside Deviation if order set to 2.
 
-        The standard deviation of returns that are below a Minimum Accepted
-        Return of zero. It is used to calculate the Sortino Ratio.
-        https://www.investopedia.com/terms/d/downside-deviation.asp.
+        If order is set to 2 the function calculates the standard
+        deviation of returns that are below a Minimum Accepted
+        Return of zero. For general order p, it returns LPM_p^(1/p),
+        i.e., the rooted lower partial moment of order p.
 
         Parameters
         ----------
         min_accepted_return : float, optional
             The annualized Minimum Accepted Return (MAR)
+        order: int, default: 2
+            Order of partial moment
         months_from_last : int, optional
             number of months offset as positive integer. Overrides use of from_date
             and to_date
@@ -1672,15 +1719,20 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
         Returns:
         -------
         float | Pandas.Series[float]
-            Downside deviation
+            Downside deviation if order set to 2
 
         """
+        msg = f"'order' must be 2 or 3, got {order!r}."
+        if order not in (2, 3):
+            raise ValueError(msg)
+
         zero: float = 0.0
         earlier, later = self.calc_range(
             months_offset=months_from_last,
             from_dt=from_date,
             to_dt=to_date,
         )
+
         how_many = (
             self.tsdf.loc[cast("int", earlier) : cast("int", later)]
             .ffill()
@@ -1697,23 +1749,27 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
             fraction = (later - earlier).days / 365.25
             time_factor = how_many.div(fraction)
 
-        dddf = (
+        per_period_mar = min_accepted_return / time_factor
+        diff = (
             self.tsdf.loc[cast("int", earlier) : cast("int", later)]
             .ffill()
             .pct_change()
-            .sub(min_accepted_return / time_factor)
+            .sub(per_period_mar)
         )
 
-        result = sqrt((dddf[dddf < zero] ** 2).sum() / how_many) * sqrt(
-            time_factor,
-        )
+        shortfall = (-diff).clip(lower=zero)
+        base = shortfall.pow(order).sum() / how_many
+        result = base.pow(1.0 / float(order))
+        result *= sqrt(time_factor)
+
+        dd_order = 2
 
         if self.tsdf.shape[1] == 1:
             return float(result.iloc[0])
         return Series(
             data=result,
             index=self.tsdf.columns,
-            name="Downside deviation",
+            name="Downside deviation" if order == dd_order else f"LPM{order}",
             dtype="float64",
         )
 
@@ -2047,18 +2103,22 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
         self: Self,
         riskfree_rate: float = 0.0,
         min_accepted_return: float = 0.0,
+        order: Literal[2, 3] = 2,
         months_from_last: int | None = None,
         from_date: dt.date | None = None,
         to_date: dt.date | None = None,
         periods_in_a_year_fixed: DaysInYearType | None = None,
     ) -> float | Series[float]:
-        """Sortino Ratio.
+        """Sortino Ratio or Kappa3 Ratio.
 
         The Sortino ratio calculated as ( return - risk free return )
         / downside deviation. The ratio implies that the riskfree asset has zero
         volatility, and a minimum acceptable return of zero. The ratio is
         calculated using the annualized arithmetic mean of returns.
         https://www.investopedia.com/terms/s/sortinoratio.asp.
+        If order is set to 3 the ratio calculated becomes Kappa3 which
+        penalizes larger downside outcomes more heavily than the Sortino
+        ratio (which uses order 2).
 
         Parameters
         ----------
@@ -2066,6 +2126,8 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
             The return of the zero volatility asset
         min_accepted_return : float, optional
             The annualized Minimum Accepted Return (MAR)
+        order: int, default: 2
+            Order of partial moment
         months_from_last : int, optional
             number of months offset as positive integer. Overrides use of from_date
             and to_date
@@ -2092,20 +2154,22 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
                 periods_in_a_year_fixed=periods_in_a_year_fixed,
             )
             - riskfree_rate,
-        ) / self.downside_deviation_func(
+        ) / self.lower_partial_moment_func(
             min_accepted_return=min_accepted_return,
+            order=order,
             months_from_last=months_from_last,
             from_date=from_date,
             to_date=to_date,
             periods_in_a_year_fixed=periods_in_a_year_fixed,
         )
 
+        sortino_order = 2
         if self.tsdf.shape[1] == 1:
             return float(cast("float64", ratio.iloc[0]))
         return Series(
             data=ratio,
             index=self.tsdf.columns,
-            name="Sortino ratio",
+            name="Sortino ratio" if order == sortino_order else "Kappa-3 ratio",
             dtype="float64",
         )
 
@@ -2513,6 +2577,7 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
         column: int = 0,
         observations: int = 21,
         periods_in_a_year_fixed: DaysInYearType | None = None,
+        dlta_degr_freedms: int = 1,
     ) -> DataFrame:
         """Calculate rolling annualised volatilities.
 
@@ -2525,6 +2590,8 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
         periods_in_a_year_fixed : DaysInYearType, optional
             Allows locking the periods-in-a-year to simplify test cases and
             comparisons
+        dlta_degr_freedms: int, default: 1
+            Variance bias factor taking the value 0 or 1.
 
         Returns:
         -------
@@ -2536,15 +2603,16 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
             time_factor = float(periods_in_a_year_fixed)
         else:
             time_factor = self.periods_in_a_year
+
         vol_label = cast("tuple[str, ValueType]", self.tsdf.iloc[:, column].name)[0]
-        dframe = Series(self.tsdf.iloc[:, column]).ffill().pct_change()
-        volseries = dframe.rolling(
-            observations,
-            min_periods=observations,
-        ).std() * sqrt(
-            time_factor,
-        )
+
+        s = log(self.tsdf.iloc[:, column]).diff()
+        volseries = s.rolling(window=observations, min_periods=observations).std(
+            ddof=dlta_degr_freedms
+        ) * sqrt(time_factor)
+
         voldf = volseries.dropna().to_frame()
+
         voldf.columns = MultiIndex.from_arrays(
             [
                 [vol_label],