openseries 1.9.6__py3-none-any.whl → 2.0.0__py3-none-any.whl

openseries/_common_model.py

@@ -1,10 +1,6 @@
-"""Defining the _CommonModel class.
+"""The _CommonModel class.
 
-Copyright (c) Captor Fund Management AB. This file is part of the openseries project.
-
-Licensed under the BSD 3-Clause License. You may obtain a copy of the License at:
-https://github.com/CaptorAB/openseries/blob/master/LICENSE.md
-SPDX-License-Identifier: BSD-3-Clause
+_CommonModel class which is the base class for OpenFrame and OpenTimeSeries.
 """
 
 from __future__ import annotations
@@ -22,13 +18,13 @@ from numpy import asarray, float64, inf, isnan, log, maximum, sqrt
 
 from .owntypes import (
     CaptorLogoType,
-    Combo_co,
     DateAlignmentError,
     InitialValueZeroError,
     NumberOfItemsAndLabelsNotSameError,
     PlotlyConfigType,
     ResampleDataLossError,
     Self,
+    SeriesOrFloat_co,
     ValueType,
 )
 
@@ -87,8 +83,127 @@ from .datefixer import (
 from .load_plotly import load_plotly_dict
 
 
-# noinspection PyTypeChecker
-class _CommonModel(BaseModel, Generic[Combo_co]):
+def _get_date_range_and_factor(
+    self: _CommonModel[SeriesOrFloat_co],
+    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,
+) -> tuple[dt.date, dt.date, float, DataFrame]:
+    """Common logic for date range and time factor calculation.
+
+    Parameters
+    ----------
+    months_from_last : int, optional
+        Number of months offset as positive integer. Overrides use of from_date
+        and to_date
+    from_date : datetime.date, optional
+        Specific from date
+    to_date : datetime.date, optional
+        Specific to date
+    periods_in_a_year_fixed : DaysInYearType, optional
+        Allows locking the periods-in-a-year to simplify test cases and
+        comparisons
+
+    Returns:
+    --------
+    tuple[dt.date, dt.date, float, DataFrame]
+        earlier, later, time_factor, data
+    """
+    earlier, later = self.calc_range(
+        months_offset=months_from_last,
+        from_dt=from_date,
+        to_dt=to_date,
+    )
+
+    if periods_in_a_year_fixed:
+        time_factor = float(periods_in_a_year_fixed)
+    else:
+        how_many = (
+            self.tsdf.loc[cast("Timestamp", earlier) : cast("Timestamp", later)]
+            .count()
+            .iloc[0]
+        )
+        fraction = (later - earlier).days / 365.25
+        time_factor = how_many / fraction
+
+    data = self.tsdf.loc[cast("Timestamp", earlier) : cast("Timestamp", later)]
+    return earlier, later, time_factor, data
+
+
+def _get_base_column_data(
+    self: _CommonModel[SeriesOrFloat_co],
+    base_column: tuple[str, ValueType] | int,
+    earlier: dt.date,
+    later: dt.date,
+) -> tuple[Series[float], tuple[str, ValueType], str]:
+    """Common logic for base column data extraction.
+
+    Parameters
+    ----------
+    base_column : tuple[str, ValueType] | int
+        Column reference
+    earlier : dt.date
+        Start date
+    later : dt.date
+        End date
+
+    Returns:
+    --------
+    tuple[Series[float], tuple[str, ValueType], str]
+        data, item, label
+    """
+    if isinstance(base_column, tuple):
+        data = self.tsdf.loc[cast("Timestamp", earlier) : cast("Timestamp", later)][
+            base_column
+        ]
+        item = base_column
+        label = cast("tuple[str, str]", self.tsdf[base_column].name)[0]
+    elif isinstance(base_column, int):
+        data = self.tsdf.loc[
+            cast("Timestamp", earlier) : cast("Timestamp", later)
+        ].iloc[:, base_column]
+        item = cast("tuple[str, ValueType]", self.tsdf.iloc[:, base_column].name)
+        label = cast("tuple[str, str]", self.tsdf.iloc[:, base_column].name)[0]
+    else:
+        msg = "base_column should be a tuple[str, ValueType] or an integer."
+        raise TypeError(msg)
+
+    return data, item, label
+
+
+def _calculate_time_factor(
+    data: Series[float],
+    earlier: dt.date,
+    later: dt.date,
+    periods_in_a_year_fixed: DaysInYearType | None = None,
+) -> float:
+    """Calculate time factor for annualization.
+
+    Parameters
+    ----------
+    data : Series[float]
+        Data series for counting observations
+    earlier : dt.date
+        Start date
+    later : dt.date
+        End date
+    periods_in_a_year_fixed : DaysInYearType, optional
+        Fixed periods in year
+
+    Returns:
+    --------
+    float
+        Time factor
+    """
+    if periods_in_a_year_fixed:
+        return float(periods_in_a_year_fixed)
+
+    fraction = (later - earlier).days / 365.25
+    return data.count() / fraction
+
+
+class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
     """Declare _CommonModel."""
 
     tsdf: DataFrame = DataFrame(dtype="float64")
@@ -99,12 +214,14 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         revalidate_instances="always",
     )
 
-    def _coerce_result(self: Self, result: Series[float], name: str) -> Combo_co:
+    def _coerce_result(
+        self: Self, result: Series[float], name: str
+    ) -> SeriesOrFloat_co:
         if self.tsdf.shape[1] == 1:
             arr = float(asarray(a=result, dtype=float64).squeeze())
-            return cast("Combo_co", arr)  # type: ignore[redundant-cast]
+            return cast("SeriesOrFloat_co", arr)  # type: ignore[redundant-cast]
         return cast(
-            "Combo_co",
+            "SeriesOrFloat_co",
             Series(
                 data=result,
                 index=self.tsdf.columns,
@@ -118,7 +235,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         """Number of observations.
 
         Returns:
-        -------
+        --------
         int
             Number of observations
 
@@ -130,7 +247,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         """The first date in the timeseries.
 
         Returns:
-        -------
+        --------
         datetime.date
             The first date in the timeseries
 
@@ -142,7 +259,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         """The last date in the timeseries.
 
         Returns:
-        -------
+        --------
         datetime.date
             The last date in the timeseries
 
@@ -154,7 +271,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         """Number of days from the first date to the last.
 
         Returns:
-        -------
+        --------
         int
             Number of days from the first date to the last
 
@@ -166,7 +283,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         """Length of series expressed in years assuming all years have 365.25 days.
 
         Returns:
-        -------
+        --------
         float
             Length of the timeseries expressed in years assuming all years
             have 365.25 days
@@ -179,7 +296,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         """The average number of observations per year.
 
         Returns:
-        -------
+        --------
         float
             The average number of observations per year
 
@@ -187,13 +304,14 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         return self.length / self.yearfrac
 
     @property
-    def max_drawdown_cal_year(self: Self) -> Combo_co:
+    def max_drawdown_cal_year(self: Self) -> SeriesOrFloat_co:
         """https://www.investopedia.com/terms/m/maximum-drawdown-mdd.asp.
 
         Returns:
-        -------
-        Combo_co
+        --------
+        SeriesOrFloat_co
             Maximum drawdown in a single calendar year.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
 
         """
         years = Index(d.year for d in self.tsdf.index)
@@ -208,58 +326,66 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         return self._coerce_result(result=result, name="Max drawdown in cal yr")
 
     @property
-    def geo_ret(self: Self) -> Combo_co:
+    def geo_ret(self: Self) -> SeriesOrFloat_co:
         """https://www.investopedia.com/terms/c/cagr.asp.
 
         Returns:
-        -------
-        Combo_co
-            Compounded Annual Growth Rate (CAGR)
+        --------
+        SeriesOrFloat_co
+            Compounded Annual Growth Rate (CAGR).
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
+
 
         """
         return self.geo_ret_func()
 
     @property
-    def arithmetic_ret(self: Self) -> Combo_co:
+    def arithmetic_ret(self: Self) -> SeriesOrFloat_co:
         """https://www.investopedia.com/terms/a/arithmeticmean.asp.
 
         Returns:
-        -------
-        Combo_co
-            Annualized arithmetic mean of returns
+        --------
+        SeriesOrFloat_co
+            Annualized arithmetic mean of returns.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
+
 
         """
         return self.arithmetic_ret_func()
 
     @property
-    def value_ret(self: Self) -> Combo_co:
+    def value_ret(self: Self) -> SeriesOrFloat_co:
         """Simple return.
 
         Returns:
-        -------
-        Combo_co
-            Simple return
+        --------
+        SeriesOrFloat_co
+            Simple return.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
+
 
         """
         return self.value_ret_func()
 
     @property
-    def vol(self: Self) -> Combo_co:
+    def vol(self: Self) -> SeriesOrFloat_co:
         """Annualized volatility.
 
         Based on Pandas .std() which is the equivalent of stdev.s([...]) in MS Excel.
         https://www.investopedia.com/terms/v/volatility.asp.
 
         Returns:
-        -------
-        Combo_co
-            Annualized volatility
+        --------
+        SeriesOrFloat_co
+            Annualized volatility.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
+
 
         """
         return self.vol_func()
 
     @property
-    def downside_deviation(self: Self) -> Combo_co:
+    def downside_deviation(self: Self) -> SeriesOrFloat_co:
         """Downside Deviation.
 
         Standard deviation of returns that are below a Minimum Accepted Return
@@ -267,9 +393,11 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         https://www.investopedia.com/terms/d/downside-deviation.asp.
 
         Returns:
-        -------
-        Combo_co
-            Downside deviation
+        --------
+        SeriesOrFloat_co
+            Downside deviation.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
+
 
         """
         min_accepted_return: float = 0.0
@@ -280,29 +408,31 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         )
 
     @property
-    def ret_vol_ratio(self: Self) -> Combo_co:
+    def ret_vol_ratio(self: Self) -> SeriesOrFloat_co:
         """Ratio of annualized arithmetic mean of returns and annualized volatility.
 
         Returns:
-        -------
-        Combo_co
+        --------
+        SeriesOrFloat_co
             Ratio of the annualized arithmetic mean of returns and annualized
             volatility.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
 
         """
         riskfree_rate: float = 0.0
         return self.ret_vol_ratio_func(riskfree_rate=riskfree_rate)
 
     @property
-    def sortino_ratio(self: Self) -> Combo_co:
+    def sortino_ratio(self: Self) -> SeriesOrFloat_co:
         """https://www.investopedia.com/terms/s/sortinoratio.asp.
 
         Returns:
-        -------
-        Combo_co
+        --------
+        SeriesOrFloat_co
             Sortino ratio calculated as the annualized arithmetic mean of returns
             / downside deviation. The ratio implies that the riskfree asset has zero
             volatility, and a minimum acceptable return of zero.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
 
         """
         riskfree_rate: float = 0.0
@@ -313,7 +443,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         )
 
     @property
-    def kappa3_ratio(self: Self) -> Combo_co:
+    def kappa3_ratio(self: Self) -> SeriesOrFloat_co:
         """Kappa-3 ratio.
 
         The Kappa-3 ratio is a generalized downside-risk ratio defined as
@@ -323,10 +453,11 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         the Sortino ratio (which uses order 2).
 
         Returns:
-        -------
-        Combo_co
-            Kappa-3 ratio calculation with the riskfree rate and
+        --------
+        SeriesOrFloat_co
+            Kappa-3 ratio calculation with the riskfree rate and.
             Minimum Acceptable Return (MAR) both set to zero.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
 
         """
         riskfree_rate: float = 0.0
@@ -339,38 +470,44 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         )
 
     @property
-    def omega_ratio(self: Self) -> Combo_co:
+    def omega_ratio(self: Self) -> SeriesOrFloat_co:
         """https://en.wikipedia.org/wiki/Omega_ratio.
 
         Returns:
-        -------
-        Combo_co
-            Omega ratio calculation
+        --------
+        SeriesOrFloat_co
+            Omega ratio calculation.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
+
 
         """
         minimum_accepted_return: float = 0.0
         return self.omega_ratio_func(min_accepted_return=minimum_accepted_return)
 
     @property
-    def z_score(self: Self) -> Combo_co:
+    def z_score(self: Self) -> SeriesOrFloat_co:
         """https://www.investopedia.com/terms/z/zscore.asp.
 
         Returns:
-        -------
-        Combo_co
+        --------
+        SeriesOrFloat_co
             Z-score as (last return - mean return) / standard deviation of returns.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
+
 
         """
         return self.z_score_func()
 
     @property
-    def max_drawdown(self: Self) -> Combo_co:
+    def max_drawdown(self: Self) -> SeriesOrFloat_co:
         """https://www.investopedia.com/terms/m/maximum-drawdown-mdd.asp.
 
         Returns:
-        -------
-        Combo_co
-            Maximum drawdown without any limit on date range
+        --------
+        SeriesOrFloat_co
+            Maximum drawdown without any limit on date range.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
+
 
         """
         return self.max_drawdown_func()
@@ -382,7 +519,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         https://www.investopedia.com/terms/m/maximum-drawdown-mdd.asp.
 
         Returns:
-        -------
+        --------
         datetime.date | pandas.Series[dt.date]
             Date when the maximum drawdown occurred
 
@@ -401,26 +538,30 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         ).dt.date
 
     @property
-    def worst(self: Self) -> Combo_co:
+    def worst(self: Self) -> SeriesOrFloat_co:
         """Most negative percentage change.
 
         Returns:
-        -------
-        Combo_co
-            Most negative percentage change
+        --------
+        SeriesOrFloat_co
+            Most negative percentage change.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
+
 
         """
         observations: int = 1
         return self.worst_func(observations=observations)
 
     @property
-    def worst_month(self: Self) -> Combo_co:
+    def worst_month(self: Self) -> SeriesOrFloat_co:
         """Most negative month.
 
         Returns:
-        -------
-        Pandas.Series[float]
-            Most negative month
+        --------
+        SeriesOrFloat_co
+            Most negative month.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
+
 
         """
         method: LiteralPandasReindexMethod = "nearest"
@@ -458,65 +599,75 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         return self._coerce_result(result=result, name="Worst month")
 
     @property
-    def positive_share(self: Self) -> Combo_co:
+    def positive_share(self: Self) -> SeriesOrFloat_co:
         """The share of percentage changes that are greater than zero.
 
         Returns:
-        -------
-        Combo_co
-            The share of percentage changes that are greater than zero
+        --------
+        SeriesOrFloat_co
+            The share of percentage changes that are greater than zero.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
+
 
         """
         return self.positive_share_func()
 
     @property
-    def skew(self: Self) -> Combo_co:
+    def skew(self: Self) -> SeriesOrFloat_co:
         """https://www.investopedia.com/terms/s/skewness.asp.
 
         Returns:
-        -------
-        Combo_co
-            Skew of the return distribution
+        --------
+        SeriesOrFloat_co
+            Skew of the return distribution.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
+
 
         """
         return self.skew_func()
 
     @property
-    def kurtosis(self: Self) -> Combo_co:
+    def kurtosis(self: Self) -> SeriesOrFloat_co:
         """https://www.investopedia.com/terms/k/kurtosis.asp.
 
         Returns:
-        -------
-        Combo_co
-            Kurtosis of the return distribution
+        --------
+        SeriesOrFloat_co
+            Kurtosis of the return distribution.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
+
 
         """
         return self.kurtosis_func()
 
     @property
-    def cvar_down(self: Self) -> Combo_co:
+    def cvar_down(self: Self) -> SeriesOrFloat_co:
         """https://www.investopedia.com/terms/c/conditional_value_at_risk.asp.
 
         Returns:
-        -------
-        Combo_co
-            Downside 95% Conditional Value At Risk "CVaR"
+        --------
+        SeriesOrFloat_co
+            Downside 95% Conditional Value At Risk "CVaR".
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
+
 
         """
         level: float = 0.95
         return self.cvar_down_func(level=level)
 
     @property
-    def var_down(self: Self) -> Combo_co:
+    def var_down(self: Self) -> SeriesOrFloat_co:
         """Downside 95% Value At Risk (VaR).
 
         The equivalent of percentile.inc([...], 1-level) over returns in MS Excel.
         https://www.investopedia.com/terms/v/var.asp.
 
         Returns:
-        -------
-        Combo_co
-            Downside 95% Value At Risk (VaR)
+        --------
+        SeriesOrFloat_co
+            Downside 95% Value At Risk (VaR).
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
+
 
         """
         level: float = 0.95
@@ -524,16 +675,17 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         return self.var_down_func(level=level, interpolation=interpolation)
 
     @property
-    def vol_from_var(self: Self) -> Combo_co:
+    def vol_from_var(self: Self) -> SeriesOrFloat_co:
         """Implied annualized volatility from Downside 95% Value at Risk.
 
         Assumes that returns are normally distributed.
 
         Returns:
-        -------
-        Combo_co
+        --------
+        SeriesOrFloat_co
             Implied annualized volatility from the Downside 95% VaR using the
             assumption that returns are normally distributed.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
 
         """
         level: float = 0.95
@@ -559,7 +711,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
             Specific from date
 
         Returns:
-        -------
+        --------
         tuple[datetime.date, datetime.date]
             Start and end date of the chosen date range
 
@@ -616,8 +768,9 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
             Argument where missing holidays can be added
         method: LiteralPandasReindexMethod, default: "nearest"
 
+
         Returns:
-        -------
+        --------
         OpenFrame
             An OpenFrame object
 
@@ -652,7 +805,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         calendar = holiday_calendar(
             startyear=startyear,
             endyear=endyear,
-            countries=countries,
+            countries=countries or "SE",
             markets=markets,
             custom_holidays=custom_holidays,
         )
@@ -677,7 +830,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         Equivalent to LN(value[t] / value[t=0]) in Excel.
 
         Returns:
-        -------
+        --------
         self
             An object of the same class
 
@@ -698,7 +851,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
             Method used to handle NaN. Either fill with last known or drop
 
         Returns:
-        -------
+        --------
         self
             An object of the same class
 
@@ -718,7 +871,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
             Method used to handle NaN. Either fill with zero or drop
 
         Returns:
-        -------
+        --------
         self
             An object of the same class
 
@@ -733,7 +886,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         """Convert timeseries into a drawdown series.
 
         Returns:
-        -------
+        --------
         self
             An object of the same class
 
@@ -763,7 +916,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
             File folder location
 
         Returns:
-        -------
+        --------
         list[dict[str, str | bool | ValueType | list[str] | list[float]]]
             A list of dictionaries with the data of the series
 
@@ -830,7 +983,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
             Flag whether to overwrite an existing file
 
         Returns:
-        -------
+        --------
         str
             The Excel file path
 
@@ -1001,7 +1154,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
             If True a Captor logo is added to the plot
 
         Returns:
-        -------
+        --------
         tuple[plotly.go.Figure, str]
             Plotly Figure and a div section or a html filename with location
 
@@ -1098,7 +1251,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
             If True the last self.tsdf point is highlighted as red dot with a label
 
         Returns:
-        -------
+        --------
         tuple[plotly.go.Figure, str]
             Plotly Figure and a div section or a html filename with location
 
@@ -1235,7 +1388,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
             If True a Captor logo is added to the plot
 
         Returns:
-        -------
+        --------
         tuple[plotly.go.Figure, str]
             Plotly Figure and a div section or a html filename with location
 
@@ -1316,7 +1469,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         from_date: dt.date | None = None,
         to_date: dt.date | None = None,
         periods_in_a_year_fixed: DaysInYearType | None = None,
-    ) -> Combo_co:
+    ) -> SeriesOrFloat_co:
         """https://www.investopedia.com/terms/a/arithmeticmean.asp.
 
         Parameters
@@ -1333,34 +1486,22 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
             comparisons
 
         Returns:
-        -------
-        Combo_co
-            Annualized arithmetic mean of returns
+        --------
+        SeriesOrFloat_co
+            Annualized arithmetic mean of returns.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
+
 
         """
-        earlier, later = self.calc_range(
-            months_offset=months_from_last,
-            from_dt=from_date,
-            to_dt=to_date,
+        _earlier, _later, time_factor, data = _get_date_range_and_factor(
+            self=self,
+            months_from_last=months_from_last,
+            from_date=from_date,
+            to_date=to_date,
+            periods_in_a_year_fixed=periods_in_a_year_fixed,
         )
-        if periods_in_a_year_fixed:
-            time_factor = float(periods_in_a_year_fixed)
-        else:
-            how_many = (
-                self.tsdf.loc[cast("Timestamp", earlier) : cast("Timestamp", later)]
-                .count()
-                .iloc[0]
-            )
-            fraction = (later - earlier).days / 365.25
-            time_factor = how_many / fraction
 
-        result = (
-            self.tsdf.loc[cast("Timestamp", earlier) : cast("Timestamp", later)]
-            .ffill()
-            .pct_change()
-            .mean()
-            * time_factor
-        )
+        result = data.ffill().pct_change().mean() * time_factor
 
         return self._coerce_result(result=result, name="Arithmetic return")
 
@@ -1370,7 +1511,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         from_date: dt.date | None = None,
         to_date: dt.date | None = None,
         periods_in_a_year_fixed: DaysInYearType | None = None,
-    ) -> Combo_co:
+    ) -> SeriesOrFloat_co:
         """Annualized volatility.
 
         Based on Pandas .std() which is the equivalent of stdev.s([...]) in MS Excel.
@@ -1389,28 +1530,20 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
             Allows locking the periods-in-a-year to simplify test cases and comparisons
 
         Returns:
-        -------
-        Combo_co
-            Annualized volatility
+        --------
+        SeriesOrFloat_co
+            Annualized volatility.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
 
         """
-        earlier, later = self.calc_range(
-            months_offset=months_from_last,
-            from_dt=from_date,
-            to_dt=to_date,
+        _earlier, _later, time_factor, data = _get_date_range_and_factor(
+            self=self,
+            months_from_last=months_from_last,
+            from_date=from_date,
+            to_date=to_date,
+            periods_in_a_year_fixed=periods_in_a_year_fixed,
         )
-        if periods_in_a_year_fixed:
-            time_factor = float(periods_in_a_year_fixed)
-        else:
-            how_many = (
-                self.tsdf.loc[cast("Timestamp", earlier) : cast("Timestamp", later)]
-                .count()
-                .iloc[0]
-            )
-            fraction = (later - earlier).days / 365.25
-            time_factor = how_many / fraction
 
-        data = self.tsdf.loc[cast("Timestamp", earlier) : cast("Timestamp", later)]
         result = data.ffill().pct_change().std().mul(sqrt(time_factor))
 
         return self._coerce_result(result=result, name="Volatility")
@@ -1425,7 +1558,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         periods_in_a_year_fixed: DaysInYearType | None = None,
         *,
         drift_adjust: bool = False,
-    ) -> Combo_co:
+    ) -> SeriesOrFloat_co:
         """Implied annualized volatility.
 
         Implied annualized volatility from the Downside VaR using the assumption
@@ -1451,10 +1584,11 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
             An adjustment to remove the bias implied by the average return
 
         Returns:
-        -------
-        Combo_co
+        --------
+        SeriesOrFloat_co
             Implied annualized volatility from the Downside VaR using the
             assumption that returns are normally distributed.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
 
         """
         return self._var_implied_vol_and_target_func(
@@ -1480,7 +1614,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         periods_in_a_year_fixed: DaysInYearType | None = None,
         *,
         drift_adjust: bool = False,
-    ) -> Combo_co:
+    ) -> SeriesOrFloat_co:
         """Target weight from VaR.
 
         A position weight multiplier from the ratio between a VaR implied
@@ -1512,10 +1646,11 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
             An adjustment to remove the bias implied by the average return
 
         Returns:
-        -------
-        Combo_co
+        --------
+        SeriesOrFloat_co
             A position weight multiplier from the ratio between a VaR implied
-            volatility and a given target volatility. Multiplier = 1.0 -> target met
+            volatility and a given target volatility. Multiplier = 1.0 -> target met.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
 
         """
         return self._var_implied_vol_and_target_func(
@@ -1544,7 +1679,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         periods_in_a_year_fixed: DaysInYearType | None = None,
         *,
         drift_adjust: bool = False,
-    ) -> Combo_co:
+    ) -> SeriesOrFloat_co:
         """Volatility implied from VaR or Target Weight.
 
         The function returns a position weight multiplier from the ratio between
@@ -1578,10 +1713,11 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
             An adjustment to remove the bias implied by the average return
 
         Returns:
-        -------
-        Combo_co
+        --------
+        SeriesOrFloat_co
             Target volatility if target_vol is provided otherwise the VaR
             implied volatility.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
 
         """
         earlier, later = self.calc_range(
@@ -1647,7 +1783,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         months_from_last: int | None = None,
         from_date: dt.date | None = None,
         to_date: dt.date | None = None,
-    ) -> Combo_co:
+    ) -> SeriesOrFloat_co:
         """Downside Conditional Value At Risk "CVaR".
 
         https://www.investopedia.com/terms/c/conditional_value_at_risk.asp.
@@ -1665,9 +1801,10 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
             Specific to date
 
         Returns:
-        -------
-        Combo_co
-            Downside Conditional Value At Risk "CVaR"
+        --------
+        SeriesOrFloat_co
+            Downside Conditional Value At Risk "CVaR".
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
 
         """
         earlier, later = self.calc_range(
@@ -1698,7 +1835,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         from_date: dt.date | None = None,
         to_date: dt.date | None = None,
         periods_in_a_year_fixed: DaysInYearType | None = None,
-    ) -> Combo_co:
+    ) -> SeriesOrFloat_co:
         """Downside Deviation if order set to 2.
 
         If order is set to 2 the function calculates the standard
@@ -1724,9 +1861,10 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
             comparisons
 
         Returns:
-        -------
-        Combo_co
-            Downside deviation if order set to 2
+        --------
+        SeriesOrFloat_co
+            Downside deviation if order set to 2.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
 
         """
         msg = f"'order' must be 2 or 3, got {order!r}."
@@ -1781,7 +1919,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         months_from_last: int | None = None,
         from_date: dt.date | None = None,
         to_date: dt.date | None = None,
-    ) -> Combo_co:
+    ) -> SeriesOrFloat_co:
         """Compounded Annual Growth Rate (CAGR).
 
         https://www.investopedia.com/terms/c/cagr.asp.
@@ -1797,9 +1935,10 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
             Specific to date
 
         Returns:
-        -------
-        Combo_co
-            Compounded Annual Growth Rate (CAGR)
+        --------
+        SeriesOrFloat_co
+            Compounded Annual Growth Rate (CAGR).
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
 
         """
         zero = 0.0
@@ -1830,7 +1969,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         months_from_last: int | None = None,
         from_date: dt.date | None = None,
         to_date: dt.date | None = None,
-    ) -> Combo_co:
+    ) -> SeriesOrFloat_co:
         """Skew of the return distribution.
 
         https://www.investopedia.com/terms/s/skewness.asp.
@@ -1846,9 +1985,10 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
             Specific to date
 
         Returns:
-        -------
-        Combo_co
-            Skew of the return distribution
+        --------
+        SeriesOrFloat_co
+            Skew of the return distribution.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
 
         """
         earlier, later = self.calc_range(
@@ -1873,7 +2013,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         months_from_last: int | None = None,
         from_date: dt.date | None = None,
         to_date: dt.date | None = None,
-    ) -> Combo_co:
+    ) -> SeriesOrFloat_co:
         """Kurtosis of the return distribution.
 
         https://www.investopedia.com/terms/k/kurtosis.asp.
@@ -1889,9 +2029,10 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
             Specific to date
 
         Returns:
-        -------
-        Combo_co
-            Kurtosis of the return distribution
+        --------
+        SeriesOrFloat_co
+            Kurtosis of the return distribution.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
 
         """
         earlier, later = self.calc_range(
@@ -1921,7 +2062,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         from_date: dt.date | None = None,
         to_date: dt.date | None = None,
         min_periods: int = 1,
-    ) -> Combo_co:
+    ) -> SeriesOrFloat_co:
         """Maximum drawdown without any limit on date range.
 
         https://www.investopedia.com/terms/m/maximum-drawdown-mdd.asp.
@@ -1939,9 +2080,10 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
             Smallest number of observations to use to find the maximum drawdown
 
         Returns:
-        -------
-        Combo_co
-            Maximum drawdown without any limit on date range
+        --------
+        SeriesOrFloat_co
+            Maximum drawdown without any limit on date range.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
 
         """
         earlier, later = self.calc_range(
@@ -1963,7 +2105,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         months_from_last: int | None = None,
         from_date: dt.date | None = None,
         to_date: dt.date | None = None,
-    ) -> Combo_co:
+    ) -> SeriesOrFloat_co:
         """Calculate share of percentage changes that are greater than zero.
 
         Parameters
@@ -1977,9 +2119,10 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
             Specific to date
 
         Returns:
-        -------
-        Combo_co
-            Calculate share of percentage changes that are greater than zero
+        --------
+        SeriesOrFloat_co
+            Calculate share of percentage changes that are greater than zero.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
 
         """
         zero: float = 0.0
@@ -2016,7 +2159,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         from_date: dt.date | None = None,
         to_date: dt.date | None = None,
         periods_in_a_year_fixed: DaysInYearType | None = None,
-    ) -> Combo_co:
+    ) -> SeriesOrFloat_co:
         """Ratio between arithmetic mean of returns and annualized volatility.
 
         The ratio of annualized arithmetic mean of returns and annualized
@@ -2041,10 +2184,11 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
             comparisons
 
         Returns:
-        -------
-        Combo_co
+        --------
+        SeriesOrFloat_co
             Ratio of the annualized arithmetic mean of returns and annualized
-            volatility or, if risk-free return provided, Sharpe ratio
+            volatility or, if risk-free return provided, Sharpe ratio.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
 
         """
         result = Series(
@@ -2073,7 +2217,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         from_date: dt.date | None = None,
         to_date: dt.date | None = None,
         periods_in_a_year_fixed: DaysInYearType | None = None,
-    ) -> Combo_co:
+    ) -> SeriesOrFloat_co:
         """Sortino Ratio or Kappa3 Ratio.
 
         The Sortino ratio calculated as ( return - risk free return )
@@ -2105,10 +2249,11 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
             comparisons
 
         Returns:
-        -------
-        Combo_co
+        --------
+        SeriesOrFloat_co
             Sortino ratio calculated as ( return - riskfree return ) /
-            downside deviation (std dev of returns below MAR)
+            downside deviation (std dev of returns below MAR).
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
 
         """
         result = Series(
@@ -2139,7 +2284,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         months_from_last: int | None = None,
         from_date: dt.date | None = None,
         to_date: dt.date | None = None,
-    ) -> Combo_co:
+    ) -> SeriesOrFloat_co:
         """Omega Ratio.
 
         The Omega Ratio compares returns above a certain target level
@@ -2160,9 +2305,10 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
             Specific to date
 
         Returns:
-        -------
-        Combo_co
-            Omega ratio calculation
+        --------
+        SeriesOrFloat_co
+            Omega ratio calculation.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
 
         """
         earlier, later = self.calc_range(
@@ -2186,7 +2332,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         months_from_last: int | None = None,
         from_date: dt.date | None = None,
         to_date: dt.date | None = None,
-    ) -> Combo_co:
+    ) -> SeriesOrFloat_co:
         """Calculate simple return.
 
         Parameters
@@ -2200,9 +2346,10 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
             Specific to date
 
         Returns:
-        -------
-        Combo_co
-            Calculate simple return
+        --------
+        SeriesOrFloat_co
+            Calculate simple return.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
 
         """
         zero: float = 0.0
@@ -2229,7 +2376,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         self: Self,
         year: int,
         month: int | None = None,
-    ) -> Combo_co:
+    ) -> SeriesOrFloat_co:
         """Calculate simple return for a specific calendar period.
 
         Parameters
@@ -2240,9 +2387,10 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
             Calendar month of the period to calculate.
 
         Returns:
-        -------
-        Combo_co
-            Calculate simple return for a specific calendar period
+        --------
+        SeriesOrFloat_co
+            Calculate simple return for a specific calendar period.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
 
         """
         if month is None:
@@ -2264,7 +2412,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         from_date: dt.date | None = None,
         to_date: dt.date | None = None,
         interpolation: LiteralQuantileInterp = "lower",
-    ) -> Combo_co:
+    ) -> SeriesOrFloat_co:
         """Downside Value At Risk, "VaR".
 
         The equivalent of percentile.inc([...], 1-level) over returns in MS Excel.
@@ -2285,9 +2433,10 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
             Type of interpolation in Pandas.DataFrame.quantile() function.
 
         Returns:
-        -------
-        Combo_co
-            Downside Value At Risk
+        --------
+        SeriesOrFloat_co
+            Downside Value At Risk.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
 
         """
         earlier, later = self.calc_range(
@@ -2310,7 +2459,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         months_from_last: int | None = None,
         from_date: dt.date | None = None,
         to_date: dt.date | None = None,
-    ) -> Combo_co:
+    ) -> SeriesOrFloat_co:
         """Most negative percentage change over a rolling number of observations.
 
         Parameters
@@ -2326,10 +2475,11 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
             Specific to date
 
         Returns:
-        -------
-        Combo_co
+        --------
+        SeriesOrFloat_co
             Most negative percentage change over a rolling number of observations
-            within a chosen date range
+            within a chosen date range.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
 
         """
         earlier, later = self.calc_range(
@@ -2353,7 +2503,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
         months_from_last: int | None = None,
         from_date: dt.date | None = None,
         to_date: dt.date | None = None,
-    ) -> Combo_co:
+    ) -> SeriesOrFloat_co:
         """Z-score as (last return - mean return) / standard deviation of returns.
 
         https://www.investopedia.com/terms/z/zscore.asp.
@@ -2369,9 +2519,10 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
             Specific to date
 
         Returns:
-        -------
-        Combo_co
-            Z-score as (last return - mean return) / standard deviation of returns
+        --------
+        SeriesOrFloat_co
+            Z-score as (last return - mean return) / standard deviation of returns.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
 
         """
         earlier, later = self.calc_range(
@@ -2406,7 +2557,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
             Number of observations in the overlapping window.
 
         Returns:
-        -------
+        --------
         Pandas.DataFrame
             Calculate rolling annualized downside CVaR
 
@@ -2437,7 +2588,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
             Number of observations in the overlapping window.
 
         Returns:
-        -------
+        --------
         Pandas.DataFrame
             Calculate rolling returns
 
@@ -2476,7 +2627,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
             Type of interpolation in Pandas.DataFrame.quantile() function.
 
         Returns:
-        -------
+        --------
         Pandas.DataFrame
            Calculate rolling annualized downside Value At Risk "VaR"
 
@@ -2516,7 +2667,7 @@ class _CommonModel(BaseModel, Generic[Combo_co]):
             Variance bias factor taking the value 0 or 1.
 
         Returns:
-        -------
+        --------
         Pandas.DataFrame
             Calculate rolling annualised volatilities