openseries 1.9.5__py3-none-any.whl → 1.9.7__py3-none-any.whl

openseries/_common_model.py

@@ -16,22 +16,25 @@ from math import ceil
 from pathlib import Path
 from secrets import choice
 from string import ascii_letters
-from typing import TYPE_CHECKING, Any, Literal, SupportsFloat, cast
+from typing import TYPE_CHECKING, Any, Generic, Literal, cast
 
-from numpy import float64, inf, isnan, log, maximum, sqrt
+from numpy import asarray, float64, inf, isnan, log, maximum, sqrt
 
 from .owntypes import (
+    CaptorLogoType,
     DateAlignmentError,
     InitialValueZeroError,
     NumberOfItemsAndLabelsNotSameError,
+    PlotlyConfigType,
     ResampleDataLossError,
     Self,
+    SeriesOrFloat_co,
     ValueType,
 )
 
 if TYPE_CHECKING:  # pragma: no cover
-    from numpy.typing import NDArray
     from openpyxl.worksheet.worksheet import Worksheet
+    from pandas import Timestamp
 
     from .owntypes import (
         CountriesType,
@@ -84,8 +87,127 @@ from .datefixer import (
 from .load_plotly import load_plotly_dict
 
 
-# noinspection PyTypeChecker
-class _CommonModel(BaseModel):  # type: ignore[misc]
+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")
@@ -96,6 +218,22 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
         revalidate_instances="always",
     )
 
+    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("SeriesOrFloat_co", arr)  # type: ignore[redundant-cast]
+        return cast(
+            "SeriesOrFloat_co",
+            Series(
+                data=result,
+                index=self.tsdf.columns,
+                name=name,
+                dtype="float64",
+            ),
+        )
+
     @property
     def length(self: Self) -> int:
         """Number of observations.
@@ -170,17 +308,18 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
         return self.length / self.yearfrac
 
     @property
-    def max_drawdown_cal_year(self: Self) -> float | Series[float]:
+    def max_drawdown_cal_year(self: Self) -> SeriesOrFloat_co:
         """https://www.investopedia.com/terms/m/maximum-drawdown-mdd.asp.
 
         Returns:
         -------
-        float | Pandas.Series[float]
+        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)
-        mddc = (
+        result = (
             self.tsdf.groupby(years)
             .apply(
                 lambda prices: (prices / prices.expanding(min_periods=1).max()).min()
@@ -188,53 +327,52 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
             )
             .min()
         )
-        if self.tsdf.shape[1] == 1:
-            return float(mddc.iloc[0])
-        return Series(
-            data=mddc,
-            index=self.tsdf.columns,
-            name="Max drawdown in cal yr",
-            dtype="float64",
-        )
+        return self._coerce_result(result=result, name="Max drawdown in cal yr")
 
     @property
-    def geo_ret(self: Self) -> float | Series[float]:
+    def geo_ret(self: Self) -> SeriesOrFloat_co:
         """https://www.investopedia.com/terms/c/cagr.asp.
 
         Returns:
         -------
-        float | Pandas.Series[float]
-            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) -> float | Series[float]:
+    def arithmetic_ret(self: Self) -> SeriesOrFloat_co:
         """https://www.investopedia.com/terms/a/arithmeticmean.asp.
 
         Returns:
         -------
-        float | Pandas.Series[float]
-            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) -> float | Series[float]:
+    def value_ret(self: Self) -> SeriesOrFloat_co:
         """Simple return.
 
         Returns:
         -------
-        float | Pandas.Series[float]
-            Simple return
+        SeriesOrFloat_co
+            Simple return.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
+
 
         """
         return self.value_ret_func()
 
     @property
-    def vol(self: Self) -> float | Series[float]:
+    def vol(self: Self) -> SeriesOrFloat_co:
         """Annualized volatility.
 
         Based on Pandas .std() which is the equivalent of stdev.s([...]) in MS Excel.
@@ -242,14 +380,16 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
 
         Returns:
         -------
-        float | Pandas.Series[float]
-            Annualized volatility
+        SeriesOrFloat_co
+            Annualized volatility.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
+
 
         """
         return self.vol_func()
 
     @property
-    def downside_deviation(self: Self) -> float | Series[float]:
+    def downside_deviation(self: Self) -> SeriesOrFloat_co:
         """Downside Deviation.
 
         Standard deviation of returns that are below a Minimum Accepted Return
@@ -258,40 +398,47 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
 
         Returns:
         -------
-        float | Pandas.Series[float]
-            Downside deviation
+        SeriesOrFloat_co
+            Downside deviation.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
+
 
         """
         min_accepted_return: float = 0.0
         order: Literal[2, 3] = 2
         return self.lower_partial_moment_func(
-            min_accepted_return=min_accepted_return, order=order
+            min_accepted_return=min_accepted_return,
+            order=order,
         )
 
     @property
-    def ret_vol_ratio(self: Self) -> float | Series[float]:
+    def ret_vol_ratio(self: Self) -> SeriesOrFloat_co:
         """Ratio of annualized arithmetic mean of returns and annualized volatility.
 
         Returns:
         -------
-        float | Pandas.Series[float]
-            Ratio of the annualized arithmetic mean of returns and annualized
+        SeriesOrFloat_co
+            Ratio of the annualized arithmetic mean of returns and annualized.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
             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) -> float | Series[float]:
+    def sortino_ratio(self: Self) -> SeriesOrFloat_co:
         """https://www.investopedia.com/terms/s/sortinoratio.asp.
 
         Returns:
         -------
-        float | Pandas.Series[float]
-            Sortino ratio calculated as the annualized arithmetic mean of returns
+        SeriesOrFloat_co
+            Sortino ratio calculated as the annualized arithmetic mean of returns.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame
             / 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
@@ -302,7 +449,7 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
         )
 
     @property
-    def kappa3_ratio(self: Self) -> float | Series[float]:
+    def kappa3_ratio(self: Self) -> SeriesOrFloat_co:
         """Kappa-3 ratio.
 
         The Kappa-3 ratio is a generalized downside-risk ratio defined as
@@ -313,9 +460,11 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
 
         Returns:
         -------
-        float | Pandas.Series[float]
-            Kappa-3 ratio calculation with the riskfree rate and
+        SeriesOrFloat_co
+            Kappa-3 ratio calculation with the riskfree rate and.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame
             Minimum Acceptable Return (MAR) both set to zero.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
 
         """
         riskfree_rate: float = 0.0
@@ -328,38 +477,44 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
         )
 
     @property
-    def omega_ratio(self: Self) -> float | Series[float]:
+    def omega_ratio(self: Self) -> SeriesOrFloat_co:
         """https://en.wikipedia.org/wiki/Omega_ratio.
 
         Returns:
         -------
-        float | Pandas.Series[float]
-            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) -> float | Series[float]:
+    def z_score(self: Self) -> SeriesOrFloat_co:
         """https://www.investopedia.com/terms/z/zscore.asp.
 
         Returns:
         -------
-        float | Pandas.Series[float]
+        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) -> float | Series[float]:
+    def max_drawdown(self: Self) -> SeriesOrFloat_co:
         """https://www.investopedia.com/terms/m/maximum-drawdown-mdd.asp.
 
         Returns:
         -------
-        float | Pandas.Series[float]
-            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()
@@ -390,26 +545,30 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
         ).dt.date
 
     @property
-    def worst(self: Self) -> float | Series[float]:
+    def worst(self: Self) -> SeriesOrFloat_co:
         """Most negative percentage change.
 
         Returns:
         -------
-        float | Pandas.Series[float]
-            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) -> float | Series[float]:
+    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"
@@ -418,8 +577,8 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
             countries = self.countries
             markets = self.markets
         except AttributeError:
-            countries = self.constituents[0].countries
-            markets = self.constituents[0].markets
+            countries = self.constituents[0].countries  # type: ignore[attr-defined]
+            markets = self.constituents[0].markets  # type: ignore[attr-defined]
 
         wmdf = self.tsdf.copy()
 
@@ -444,66 +603,67 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
 
         result = wmdf.ffill().pct_change().min()
 
-        if self.tsdf.shape[1] == 1:
-            return float(result.iloc[0])
-        return Series(
-            data=result,
-            index=self.tsdf.columns,
-            name="Worst month",
-            dtype="float64",
-        )
+        return self._coerce_result(result=result, name="Worst month")
 
     @property
-    def positive_share(self: Self) -> float | Series[float]:
+    def positive_share(self: Self) -> SeriesOrFloat_co:
         """The share of percentage changes that are greater than zero.
 
         Returns:
         -------
-        float | Pandas.Series[float]
-            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) -> float | Series[float]:
+    def skew(self: Self) -> SeriesOrFloat_co:
         """https://www.investopedia.com/terms/s/skewness.asp.
 
         Returns:
         -------
-        float | Pandas.Series[float]
-            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) -> float | Series[float]:
+    def kurtosis(self: Self) -> SeriesOrFloat_co:
         """https://www.investopedia.com/terms/k/kurtosis.asp.
 
         Returns:
         -------
-        float | Pandas.Series[float]
-            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) -> float | Series[float]:
+    def cvar_down(self: Self) -> SeriesOrFloat_co:
         """https://www.investopedia.com/terms/c/conditional_value_at_risk.asp.
 
         Returns:
         -------
-        float | Pandas.Series[float]
-            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) -> float | Series[float]:
+    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.
@@ -511,8 +671,10 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
 
         Returns:
         -------
-        float | Pandas.Series[float]
-            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
@@ -520,16 +682,18 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
         return self.var_down_func(level=level, interpolation=interpolation)
 
     @property
-    def vol_from_var(self: Self) -> float | Series[float]:
+    def vol_from_var(self: Self) -> SeriesOrFloat_co:
         """Implied annualized volatility from Downside 95% Value at Risk.
 
         Assumes that returns are normally distributed.
 
         Returns:
         -------
-        float | Pandas.Series[float]
-            Implied annualized volatility from the Downside 95% VaR using the
+        SeriesOrFloat_co
+            Implied annualized volatility from the Downside 95% VaR using the.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
             assumption that returns are normally distributed.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
 
         """
         level: float = 0.95
@@ -625,30 +789,30 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
             try:
                 self.countries = countries
             except ValidationError:
-                for serie in self.constituents:
+                for serie in self.constituents:  # type: ignore[attr-defined]
                     serie.countries = countries
         else:
             try:
                 countries = self.countries
             except AttributeError:
-                countries = self.constituents[0].countries
+                countries = self.constituents[0].countries  # type: ignore[attr-defined]
 
         if markets:
             try:
                 self.markets = markets
             except ValidationError:
-                for serie in self.constituents:
+                for serie in self.constituents:  # type: ignore[attr-defined]
                     serie.markets = markets
         else:
             try:
                 markets = self.markets
             except AttributeError:
-                markets = self.constituents[0].markets
+                markets = self.constituents[0].markets  # type: ignore[attr-defined]
 
         calendar = holiday_calendar(
             startyear=startyear,
             endyear=endyear,
-            countries=countries,
+            countries=countries or "SE",
             markets=markets,
             custom_holidays=custom_holidays,
         )
@@ -658,7 +822,9 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
             for d in date_range(
                 start=cast("dt.date", self.tsdf.first_valid_index()),
                 end=cast("dt.date", self.tsdf.last_valid_index()),
-                freq=CustomBusinessDay(calendar=calendar),
+                freq=CustomBusinessDay(calendar=calendar)
+                if any([countries, markets, custom_holidays])
+                else None,
             )
         ]
         self.tsdf = self.tsdf.reindex(labels=d_range, method=method, copy=False)
@@ -859,9 +1025,103 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
 
         return str(sheetfile)
 
+    @staticmethod
+    def _ensure_labels(
+        ncols: int,
+        labels: list[str] | None,
+        default_labels: list[str],
+    ) -> list[str]:
+        """Validate or infer labels for plotting."""
+        if labels:
+            if len(labels) != ncols:
+                msg = "Must provide same number of labels as items in frame."
+                raise NumberOfItemsAndLabelsNotSameError(msg)
+            return labels
+        return default_labels
+
+    @staticmethod
+    def _resolve_dir(directory: DirectoryPath | None) -> Path:
+        """Resolve output directory for plot files."""
+        if directory:
+            return Path(directory).resolve()
+        if (Path.home() / "Documents").exists():
+            return Path.home() / "Documents"
+        return Path(stack()[2].filename).parent
+
+    @staticmethod
+    def _hover_xy(tick_fmt: str | None) -> str:
+        """Create hovertemplate for y-value and date x-axis."""
+        return (
+            f"%{{y:{tick_fmt}}}<br>%{{x|{'%Y-%m-%d'}}}"
+            if tick_fmt
+            else "%{y}<br>%{x|%Y-%m-%d}"
+        )
+
+    @staticmethod
+    def _hover_hist(x_fmt: str | None, y_fmt: str | None) -> str:
+        """Create hovertemplate for histogram plots."""
+        y = f"%{{y:{y_fmt}}}" if y_fmt else "%{y}"
+        x = f"%{{x:{x_fmt}}}" if x_fmt else "%{x}"
+        return f"Count: {y}<br>{x}"
+
+    @staticmethod
+    def _apply_title_logo(
+        figure: Figure,
+        logo: CaptorLogoType,
+        title: str | None,
+        *,
+        add_logo: bool,
+    ) -> None:
+        """Apply optional title and logo to a Plotly Figure."""
+        if add_logo:
+            figure.add_layout_image(logo)
+        if title:
+            figure.update_layout(
+                {"title": {"text": f"<b>{title}</b><br>", "font": {"size": 36}}},
+            )
+
+    @staticmethod
+    def _emit_output(
+        figure: Figure,
+        fig_config: PlotlyConfigType,
+        output_type: LiteralPlotlyOutput,
+        plotfile: Path,
+        filename: str,
+        *,
+        include_plotlyjs_bool: bool,
+        auto_open: bool,
+    ) -> str:
+        """Write a file or return inline HTML string from a Plotly Figure."""
+        if output_type == "file":
+            plot(
+                figure_or_data=figure,
+                filename=str(plotfile),
+                auto_open=auto_open,
+                auto_play=False,
+                link_text="",
+                include_plotlyjs=include_plotlyjs_bool,
+                config=fig_config,
+                output_type=output_type,
+            )
+            return str(plotfile)
+
+        div_id = filename.rsplit(".", 1)[0]
+        return cast(
+            "str",
+            to_html(
+                fig=figure,
+                config=fig_config,
+                auto_play=False,
+                include_plotlyjs=include_plotlyjs_bool,
+                full_html=False,
+                div_id=div_id,
+            ),
+        )
+
     def plot_bars(
         self: Self,
         mode: LiteralBarPlotMode = "group",
+        title: str | None = None,
         tick_fmt: str | None = None,
         filename: str | None = None,
         directory: DirectoryPath | None = None,
@@ -880,6 +1140,8 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
             The timeseries self.tsdf
         mode: LiteralBarPlotMode
             The type of bar to use
+        title: str, optional
+            A title above the plot
         tick_fmt: str, optional
             None, '%', '.1%' depending on number of decimals to show
         filename: str, optional
@@ -904,34 +1166,22 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
             Plotly Figure and a div section or a html filename with location
 
         """
-        if labels:
-            if len(labels) != self.tsdf.shape[1]:
-                msg = "Must provide same number of labels as items in frame."
-                raise NumberOfItemsAndLabelsNotSameError(msg)
-        else:
-            labels = list(self.tsdf.columns.get_level_values(0))
-
-        if directory:
-            dirpath = Path(directory).resolve()
-        elif Path.home().joinpath("Documents").exists():
-            dirpath = Path.home().joinpath("Documents")
-        else:
-            dirpath = Path(stack()[1].filename).parent
+        labels = self._ensure_labels(
+            ncols=self.tsdf.shape[1],
+            labels=labels,
+            default_labels=list(self.tsdf.columns.get_level_values(0)),
+        )
 
+        dirpath = self._resolve_dir(directory=directory)
         if not filename:
-            filename = "".join(choice(ascii_letters) for _ in range(6)) + ".html"
-        plotfile = dirpath.joinpath(filename)
+            filename = f"{''.join(choice(ascii_letters) for _ in range(6))}.html"
+        plotfile = dirpath / filename
 
         fig, logo = load_plotly_dict()
         figure = Figure(fig)
 
         opacity = 0.7 if mode == "overlay" else None
-
-        hovertemplate = (
-            f"%{{y:{tick_fmt}}}<br>%{{x|{'%Y-%m-%d'}}}"
-            if tick_fmt
-            else "%{y}<br>%{x|%Y-%m-%d}"
-        )
+        hovertemplate = self._hover_xy(tick_fmt=tick_fmt)
 
         for item in range(self.tsdf.shape[1]):
             figure.add_bar(
@@ -943,37 +1193,29 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
             )
         figure.update_layout(barmode=mode, yaxis={"tickformat": tick_fmt})
 
-        if add_logo:
-            figure.add_layout_image(logo)
+        self._apply_title_logo(
+            figure=figure,
+            title=title,
+            add_logo=add_logo,
+            logo=logo,
+        )
 
-        if output_type == "file":
-            plot(
-                figure_or_data=figure,
-                filename=str(plotfile),
-                auto_open=auto_open,
-                auto_play=False,
-                link_text="",
-                include_plotlyjs=cast("bool", include_plotlyjs),
-                config=fig["config"],
-                output_type=output_type,
-            )
-            string_output = str(plotfile)
-        else:
-            div_id = filename.split(sep=".")[0]
-            string_output = to_html(
-                fig=figure,
-                config=fig["config"],
-                auto_play=False,
-                include_plotlyjs=cast("bool", include_plotlyjs),
-                full_html=False,
-                div_id=div_id,
-            )
+        string_output = self._emit_output(
+            figure=figure,
+            fig_config=fig["config"],
+            include_plotlyjs_bool=cast("bool", include_plotlyjs),
+            output_type=output_type,
+            auto_open=auto_open,
+            plotfile=plotfile,
+            filename=filename,
+        )
 
         return figure, string_output
 
     def plot_series(
         self: Self,
         mode: LiteralLinePlotMode = "lines",
+        title: str | None = None,
         tick_fmt: str | None = None,
         filename: str | None = None,
         directory: DirectoryPath | None = None,
@@ -993,6 +1235,8 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
             The timeseries self.tsdf
         mode: LiteralLinePlotMode, default: "lines"
             The type of scatter to use
+        title: str, optional
+            A title above the plot
         tick_fmt: str, optional
             None, '%', '.1%' depending on number of decimals to show
         filename: str, optional
@@ -1019,32 +1263,21 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
             Plotly Figure and a div section or a html filename with location
 
         """
-        if labels:
-            if len(labels) != self.tsdf.shape[1]:
-                msg = "Must provide same number of labels as items in frame."
-                raise NumberOfItemsAndLabelsNotSameError(msg)
-        else:
-            labels = list(self.tsdf.columns.get_level_values(0))
-
-        if directory:
-            dirpath = Path(directory).resolve()
-        elif Path.home().joinpath("Documents").exists():
-            dirpath = Path.home().joinpath("Documents")
-        else:
-            dirpath = Path(stack()[1].filename).parent
+        labels = self._ensure_labels(
+            ncols=self.tsdf.shape[1],
+            labels=labels,
+            default_labels=list(self.tsdf.columns.get_level_values(0)),
+        )
 
+        dirpath = self._resolve_dir(directory=directory)
         if not filename:
-            filename = "".join(choice(ascii_letters) for _ in range(6)) + ".html"
-        plotfile = dirpath.joinpath(filename)
+            filename = f"{''.join(choice(ascii_letters) for _ in range(6))}.html"
+        plotfile = dirpath / filename
 
         fig, logo = load_plotly_dict()
         figure = Figure(fig)
 
-        hovertemplate = (
-            f"%{{y:{tick_fmt}}}<br>%{{x|{'%Y-%m-%d'}}}"
-            if tick_fmt
-            else "%{y}<br>%{x|%Y-%m-%d}"
-        )
+        hovertemplate = self._hover_xy(tick_fmt=tick_fmt)
 
         for item in range(self.tsdf.shape[1]):
             figure.add_scatter(
@@ -1059,7 +1292,6 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
 
         if show_last:
             txt = f"Last {{:{tick_fmt}}}" if tick_fmt else "Last {}"
-
             for item in range(self.tsdf.shape[1]):
                 figure.add_scatter(
                     x=[Series(self.tsdf.iloc[:, item]).index[-1]],
@@ -1073,31 +1305,22 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
                     textposition="top center",
                 )
 
-        if add_logo:
-            figure.add_layout_image(logo)
+        self._apply_title_logo(
+            figure=figure,
+            title=title,
+            add_logo=add_logo,
+            logo=logo,
+        )
 
-        if output_type == "file":
-            plot(
-                figure_or_data=figure,
-                filename=str(plotfile),
-                auto_open=auto_open,
-                auto_play=False,
-                link_text="",
-                include_plotlyjs=cast("bool", include_plotlyjs),
-                config=fig["config"],
-                output_type=output_type,
-            )
-            string_output = str(plotfile)
-        else:
-            div_id = filename.split(sep=".")[0]
-            string_output = to_html(
-                fig=figure,
-                config=fig["config"],
-                auto_play=False,
-                include_plotlyjs=cast("bool", include_plotlyjs),
-                full_html=False,
-                div_id=div_id,
-            )
+        string_output = self._emit_output(
+            figure=figure,
+            fig_config=fig["config"],
+            include_plotlyjs_bool=cast("bool", include_plotlyjs),
+            output_type=output_type,
+            auto_open=auto_open,
+            plotfile=plotfile,
+            filename=filename,
+        )
 
         return figure, string_output
 
@@ -1111,6 +1334,7 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
         bargap: float = 0.0,
         bargroupgap: float = 0.0,
         curve_type: LiteralPlotlyHistogramCurveType = "kde",
+        title: str | None = None,
         x_fmt: str | None = None,
         y_fmt: str | None = None,
         filename: str | None = None,
@@ -1144,6 +1368,8 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
             Sets the gap between bar “groups” at the same location coordinate
         curve_type: LiteralPlotlyHistogramCurveType, default: kde
             Specifies the type of distribution curve to overlay on the histogram
+        title: str, optional
+            A title above the plot
         y_fmt: str, optional
             None, '%', '.1%' depending on number of decimals to show on the y-axis
         x_fmt: str, optional
@@ -1174,32 +1400,19 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
             Plotly Figure and a div section or a html filename with location
 
         """
-        if labels:
-            if len(labels) != self.tsdf.shape[1]:
-                msg = "Must provide same number of labels as items in frame."
-                raise NumberOfItemsAndLabelsNotSameError(msg)
-        else:
-            labels = list(self.tsdf.columns.get_level_values(0))
-
-        if directory:
-            dirpath = Path(directory).resolve()
-        elif Path.home().joinpath("Documents").exists():
-            dirpath = Path.home().joinpath("Documents")
-        else:
-            dirpath = Path(stack()[1].filename).parent
+        labels = self._ensure_labels(
+            ncols=self.tsdf.shape[1],
+            labels=labels,
+            default_labels=list(self.tsdf.columns.get_level_values(0)),
+        )
 
+        dirpath = self._resolve_dir(directory=directory)
         if not filename:
-            filename = "".join(choice(ascii_letters) for _ in range(6)) + ".html"
-        plotfile = dirpath.joinpath(filename)
+            filename = f"{''.join(choice(ascii_letters) for _ in range(6))}.html"
+        plotfile = dirpath / filename
 
         fig_dict, logo = load_plotly_dict()
-
-        hovertemplate = f"Count: %{{y:{y_fmt}}}" if y_fmt else "Count: %{y}"
-
-        if x_fmt:
-            hovertemplate += f"<br>%{{x:{x_fmt}}}"
-        else:
-            hovertemplate += "<br>%{x}"
+        hovertemplate = self._hover_hist(x_fmt=x_fmt, y_fmt=y_fmt)
 
         msg = "plot_type must be 'bars' or 'lines'."
         if plot_type == "bars":
@@ -1221,10 +1434,7 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
                 bargroupgap=bargroupgap,
             )
         elif plot_type == "lines":
-            hist_data = [
-                cast("Series[float]", self.tsdf.loc[:, ds]).dropna().tolist()
-                for ds in self.tsdf
-            ]
+            hist_data = [self.tsdf[col] for col in self.tsdf.columns]
             figure = create_distplot(
                 hist_data=hist_data,
                 curve_type=curve_type,
@@ -1238,35 +1448,25 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
             raise TypeError(msg)
 
         figure.update_layout(xaxis={"tickformat": x_fmt}, yaxis={"tickformat": y_fmt})
-
         figure.update_xaxes(zeroline=True, zerolinewidth=2, zerolinecolor="lightgrey")
         figure.update_yaxes(zeroline=True, zerolinewidth=2, zerolinecolor="lightgrey")
 
-        if add_logo:
-            figure.add_layout_image(logo)
+        self._apply_title_logo(
+            figure=figure,
+            title=title,
+            add_logo=add_logo,
+            logo=logo,
+        )
 
-        if output_type == "file":
-            plot(
-                figure_or_data=figure,
-                filename=str(plotfile),
-                auto_open=auto_open,
-                auto_play=False,
-                link_text="",
-                include_plotlyjs=cast("bool", include_plotlyjs),
-                config=fig_dict["config"],
-                output_type=output_type,
-            )
-            string_output = str(plotfile)
-        else:
-            div_id = filename.rsplit(".", 1)[0]
-            string_output = to_html(
-                fig=figure,
-                config=fig_dict["config"],
-                auto_play=False,
-                include_plotlyjs=cast("bool", include_plotlyjs),
-                full_html=False,
-                div_id=div_id,
-            )
+        string_output = self._emit_output(
+            figure=figure,
+            fig_config=fig_dict["config"],
+            include_plotlyjs_bool=cast("bool", include_plotlyjs),
+            output_type=output_type,
+            auto_open=auto_open,
+            plotfile=plotfile,
+            filename=filename,
+        )
 
         return figure, string_output
 
@@ -1276,7 +1476,7 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
         from_date: dt.date | None = None,
         to_date: dt.date | None = None,
         periods_in_a_year_fixed: DaysInYearType | None = None,
-    ) -> float | Series[float]:
+    ) -> SeriesOrFloat_co:
         """https://www.investopedia.com/terms/a/arithmeticmean.asp.
 
         Parameters
@@ -1294,41 +1494,23 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
 
         Returns:
         -------
-        float | Pandas.Series[float]
-            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:
-            fraction = (later - earlier).days / 365.25
-            how_many = self.tsdf.loc[
-                cast("int", earlier) : cast("int", later),
-                self.tsdf.columns.to_numpy()[0],
-            ].count()
-            time_factor = cast("int", how_many) / fraction
 
-        result = (
-            self.tsdf.loc[cast("int", earlier) : cast("int", later)]
-            .ffill()
-            .pct_change()
-            .mean()
-            * time_factor
-        )
+        result = data.ffill().pct_change().mean() * time_factor
 
-        if self.tsdf.shape[1] == 1:
-            return float(result.iloc[0])
-        return Series(
-            data=result,
-            index=self.tsdf.columns,
-            name="Arithmetic return",
-            dtype="float64",
-        )
+        return self._coerce_result(result=result, name="Arithmetic return")
 
     def vol_func(
         self: Self,
@@ -1336,7 +1518,7 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
         from_date: dt.date | None = None,
         to_date: dt.date | None = None,
         periods_in_a_year_fixed: DaysInYearType | None = None,
-    ) -> float | Series[float]:
+    ) -> SeriesOrFloat_co:
         """Annualized volatility.
 
         Based on Pandas .std() which is the equivalent of stdev.s([...]) in MS Excel.
@@ -1356,37 +1538,22 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
 
         Returns:
         -------
-        float | Pandas.Series[float]
-            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:
-            fraction = (later - earlier).days / 365.25
-            how_many = (
-                self.tsdf.loc[cast("int", earlier) : cast("int", later)]
-                .count()
-                .iloc[0]
-            )
-            time_factor = how_many / fraction
 
-        data = self.tsdf.loc[cast("int", earlier) : cast("int", later)]
         result = data.ffill().pct_change().std().mul(sqrt(time_factor))
 
-        if self.tsdf.shape[1] == 1:
-            return float(cast("SupportsFloat", result.iloc[0]))
-        return Series(
-            data=result,
-            index=self.tsdf.columns,
-            name="Volatility",
-            dtype="float64",
-        )
+        return self._coerce_result(result=result, name="Volatility")
 
     def vol_from_var_func(
         self: Self,
@@ -1398,7 +1565,7 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
         periods_in_a_year_fixed: DaysInYearType | None = None,
         *,
         drift_adjust: bool = False,
-    ) -> float | Series[float]:
+    ) -> SeriesOrFloat_co:
         """Implied annualized volatility.
 
         Implied annualized volatility from the Downside VaR using the assumption
@@ -1425,8 +1592,9 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
 
         Returns:
         -------
-        float | Pandas.Series[float]
-            Implied annualized volatility from the Downside VaR using the
+        SeriesOrFloat_co
+            Implied annualized volatility from the Downside VaR using the.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
             assumption that returns are normally distributed.
 
         """
@@ -1453,7 +1621,7 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
         periods_in_a_year_fixed: DaysInYearType | None = None,
         *,
         drift_adjust: bool = False,
-    ) -> float | Series[float]:
+    ) -> SeriesOrFloat_co:
         """Target weight from VaR.
 
         A position weight multiplier from the ratio between a VaR implied
@@ -1486,8 +1654,9 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
 
         Returns:
         -------
-        float | Pandas.Series[float]
-            A position weight multiplier from the ratio between a VaR implied
+        SeriesOrFloat_co
+            A position weight multiplier from the ratio between a VaR implied.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
             volatility and a given target volatility. Multiplier = 1.0 -> target met
 
         """
@@ -1517,7 +1686,7 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
         periods_in_a_year_fixed: DaysInYearType | None = None,
         *,
         drift_adjust: bool = False,
-    ) -> float | Series[float]:
+    ) -> SeriesOrFloat_co:
         """Volatility implied from VaR or Target Weight.
 
         The function returns a position weight multiplier from the ratio between
@@ -1552,8 +1721,9 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
 
         Returns:
         -------
-        float | Pandas.Series[float]
-            Target volatility if target_vol is provided otherwise the VaR
+        SeriesOrFloat_co
+            Target volatility if target_vol is provided otherwise the VaR.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
             implied volatility.
 
         """
@@ -1567,23 +1737,25 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
         else:
             fraction = (later - earlier).days / 365.25
             how_many = (
-                self.tsdf.loc[cast("int", earlier) : cast("int", later)]
+                self.tsdf.loc[cast("Timestamp", earlier) : cast("Timestamp", later)]
                 .count()
                 .iloc[0]
             )
             time_factor = how_many / fraction
         if drift_adjust:
             imp_vol = (-sqrt(time_factor) / norm.ppf(level)) * (
-                self.tsdf.loc[cast("int", earlier) : cast("int", later)]
+                self.tsdf.loc[cast("Timestamp", earlier) : cast("Timestamp", later)]
                 .ffill()
                 .pct_change()
                 .quantile(1 - level, interpolation=interpolation)
-                - self.tsdf.loc[cast("int", earlier) : cast("int", later)]
+                - self.tsdf.loc[cast("Timestamp", earlier) : cast("Timestamp", later)]
                 .ffill()
                 .pct_change()
                 .sum()
                 / len(
-                    self.tsdf.loc[cast("int", earlier) : cast("int", later)]
+                    self.tsdf.loc[
+                        cast("Timestamp", earlier) : cast("Timestamp", later)
+                    ]
                     .ffill()
                     .pct_change(),
                 )
@@ -1591,7 +1763,7 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
         else:
             imp_vol = (
                 -sqrt(time_factor)
-                * self.tsdf.loc[cast("int", earlier) : cast("int", later)]
+                * self.tsdf.loc[cast("Timestamp", earlier) : cast("Timestamp", later)]
                 .ffill()
                 .pct_change()
                 .quantile(1 - level, interpolation=interpolation)
@@ -1610,14 +1782,7 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
             result = imp_vol
             label = f"Imp vol from VaR {level:.0%}"
 
-        if self.tsdf.shape[1] == 1:
-            return float(cast("SupportsFloat", result.iloc[0]))
-        return Series(
-            data=result,
-            index=self.tsdf.columns,
-            name=label,
-            dtype="float64",
-        )
+        return self._coerce_result(result=result, name=label)
 
     def cvar_down_func(
         self: Self,
@@ -1625,7 +1790,7 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
         months_from_last: int | None = None,
         from_date: dt.date | None = None,
         to_date: dt.date | None = None,
-    ) -> float | Series[float]:
+    ) -> SeriesOrFloat_co:
         """Downside Conditional Value At Risk "CVaR".
 
         https://www.investopedia.com/terms/c/conditional_value_at_risk.asp.
@@ -1644,8 +1809,9 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
 
         Returns:
         -------
-        float | Pandas.Series[float]
-            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(
@@ -1653,32 +1819,19 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
             from_dt=from_date,
             to_dt=to_date,
         )
-        cvar_df = self.tsdf.loc[cast("int", earlier) : cast("int", later)].copy(
-            deep=True
-        )
+        cvar_df = self.tsdf.loc[
+            cast("Timestamp", earlier) : cast("Timestamp", later)
+        ].copy(deep=True)
         result = [
-            cvar_df.loc[:, x]  # type: ignore[call-overload]
-            .ffill()
-            .pct_change()
-            .sort_values()
-            .iloc[
-                : ceil(
-                    cast(
-                        "int",
-                        (1 - level) * cvar_df.loc[:, x].ffill().pct_change().count(),
-                    )
-                ),
-            ]
-            .mean()
-            for x in self.tsdf
+            (r := cvar_df[col].ffill().pct_change().sort_values())[
+                : ceil((1 - level) * r.count())
+            ].mean()
+            for col in cvar_df.columns
         ]
-        if self.tsdf.shape[1] == 1:
-            return float(result[0])
-        return Series(
-            data=result,
-            index=self.tsdf.columns,
+
+        return self._coerce_result(
+            result=cast("Series[float]", result),
             name=f"CVaR {level:.1%}",
-            dtype="float64",
         )
 
     def lower_partial_moment_func(
@@ -1689,7 +1842,7 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
         from_date: dt.date | None = None,
         to_date: dt.date | None = None,
         periods_in_a_year_fixed: DaysInYearType | None = None,
-    ) -> float | Series[float]:
+    ) -> SeriesOrFloat_co:
         """Downside Deviation if order set to 2.
 
         If order is set to 2 the function calculates the standard
@@ -1716,8 +1869,9 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
 
         Returns:
         -------
-        float | Pandas.Series[float]
-            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}."
@@ -1732,7 +1886,7 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
         )
 
         how_many = (
-            self.tsdf.loc[cast("int", earlier) : cast("int", later)]
+            self.tsdf.loc[cast("Timestamp", earlier) : cast("Timestamp", later)]
             .ffill()
             .pct_change()
             .count(numeric_only=True)
@@ -1749,7 +1903,7 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
 
         per_period_mar = min_accepted_return / time_factor
         diff = (
-            self.tsdf.loc[cast("int", earlier) : cast("int", later)]
+            self.tsdf.loc[cast("Timestamp", earlier) : cast("Timestamp", later)]
             .ffill()
             .pct_change()
             .sub(per_period_mar)
@@ -1762,13 +1916,9 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
 
         dd_order = 2
 
-        if self.tsdf.shape[1] == 1:
-            return float(result.iloc[0])
-        return Series(
-            data=result,
-            index=self.tsdf.columns,
+        return self._coerce_result(
+            result=result,
             name="Downside deviation" if order == dd_order else f"LPM{order}",
-            dtype="float64",
         )
 
     def geo_ret_func(
@@ -1776,7 +1926,7 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
         months_from_last: int | None = None,
         from_date: dt.date | None = None,
         to_date: dt.date | None = None,
-    ) -> float | Series[float]:
+    ) -> SeriesOrFloat_co:
         """Compounded Annual Growth Rate (CAGR).
 
         https://www.investopedia.com/terms/c/cagr.asp.
@@ -1793,8 +1943,9 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
 
         Returns:
         -------
-        float | Pandas.Series[float]
-            Compounded Annual Growth Rate (CAGR)
+        SeriesOrFloat_co
+            Compounded Annual Growth Rate (CAGR).
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
 
         """
         zero = 0.0
@@ -1815,13 +1966,9 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
 
         result = (self.tsdf.loc[later] / self.tsdf.loc[earlier]) ** (1 / fraction) - 1
 
-        if self.tsdf.shape[1] == 1:
-            return float(result.iloc[0])
-        return Series(
-            data=result.to_numpy(),
-            index=self.tsdf.columns,
+        return self._coerce_result(
+            result=cast("Series[float]", result),
             name="Geometric return",
-            dtype="float64",
         )
 
     def skew_func(
@@ -1829,7 +1976,7 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
         months_from_last: int | None = None,
         from_date: dt.date | None = None,
         to_date: dt.date | None = None,
-    ) -> float | Series[float]:
+    ) -> SeriesOrFloat_co:
         """Skew of the return distribution.
 
         https://www.investopedia.com/terms/s/skewness.asp.
@@ -1846,8 +1993,9 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
 
         Returns:
         -------
-        float | Pandas.Series[float]
-            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(
@@ -1855,30 +2003,24 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
             from_dt=from_date,
             to_dt=to_date,
         )
-        result: NDArray[float64] = skew(
-            a=self.tsdf.loc[cast("int", earlier) : cast("int", later)]
-            .ffill()
-            .pct_change()
-            .to_numpy(),
+        result = skew(
+            a=(
+                self.tsdf.loc[cast("Timestamp", earlier) : cast("Timestamp", later)]
+                .ffill()
+                .pct_change()
+            ),
             bias=True,
             nan_policy="omit",
         )
 
-        if self.tsdf.shape[1] == 1:
-            return float(result[0])
-        return Series(
-            data=result,
-            index=self.tsdf.columns,
-            name="Skew",
-            dtype="float64",
-        )
+        return self._coerce_result(result=cast("Series[float]", result), name="Skew")
 
     def kurtosis_func(
         self: Self,
         months_from_last: int | None = None,
         from_date: dt.date | None = None,
         to_date: dt.date | None = None,
-    ) -> float | Series[float]:
+    ) -> SeriesOrFloat_co:
         """Kurtosis of the return distribution.
 
         https://www.investopedia.com/terms/k/kurtosis.asp.
@@ -1895,8 +2037,9 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
 
         Returns:
         -------
-        float | Pandas.Series[float]
-            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(
@@ -1904,9 +2047,9 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
             from_dt=from_date,
             to_dt=to_date,
         )
-        result: NDArray[float64] = kurtosis(
+        result = kurtosis(
             a=(
-                self.tsdf.loc[cast("int", earlier) : cast("int", later)]
+                self.tsdf.loc[cast("Timestamp", earlier) : cast("Timestamp", later)]
                 .ffill()
                 .pct_change()
             ),
@@ -1915,13 +2058,9 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
             nan_policy="omit",
         )
 
-        if self.tsdf.shape[1] == 1:
-            return float(result[0])
-        return Series(
-            data=result,
-            index=self.tsdf.columns,
+        return self._coerce_result(
+            result=cast("Series[float]", result),
             name="Kurtosis",
-            dtype="float64",
         )
 
     def max_drawdown_func(
@@ -1930,7 +2069,7 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
         from_date: dt.date | None = None,
         to_date: dt.date | None = None,
         min_periods: int = 1,
-    ) -> float | Series[float]:
+    ) -> SeriesOrFloat_co:
         """Maximum drawdown without any limit on date range.
 
         https://www.investopedia.com/terms/m/maximum-drawdown-mdd.asp.
@@ -1949,8 +2088,9 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
 
         Returns:
         -------
-        float | Pandas.Series[float]
-            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(
@@ -1959,26 +2099,20 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
             to_dt=to_date,
         )
         result = (
-            self.tsdf.loc[cast("int", earlier) : cast("int", later)]
-            / self.tsdf.loc[cast("int", earlier) : cast("int", later)]
+            self.tsdf.loc[cast("Timestamp", earlier) : cast("Timestamp", later)]
+            / self.tsdf.loc[cast("Timestamp", earlier) : cast("Timestamp", later)]
             .expanding(min_periods=min_periods)
             .max()
         ).min() - 1
-        if self.tsdf.shape[1] == 1:
-            return float(result.iloc[0])
-        return Series(
-            data=result,
-            index=self.tsdf.columns,
-            name="Max drawdown",
-            dtype="float64",
-        )
+
+        return self._coerce_result(result=result, name="Max drawdown")
 
     def positive_share_func(
         self: Self,
         months_from_last: int | None = None,
         from_date: dt.date | None = None,
         to_date: dt.date | None = None,
-    ) -> float | Series[float]:
+    ) -> SeriesOrFloat_co:
         """Calculate share of percentage changes that are greater than zero.
 
         Parameters
@@ -1993,8 +2127,9 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
 
         Returns:
         -------
-        float | Pandas.Series[float]
-            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
@@ -2004,10 +2139,10 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
             to_dt=to_date,
         )
         pos = (
-            self.tsdf.loc[cast("int", earlier) : cast("int", later)]
+            self.tsdf.loc[cast("Timestamp", earlier) : cast("Timestamp", later)]
             .ffill()
             .pct_change()[1:][
-                self.tsdf.loc[cast("int", earlier) : cast("int", later)]
+                self.tsdf.loc[cast("Timestamp", earlier) : cast("Timestamp", later)]
                 .ffill()
                 .pct_change()[1:]
                 > zero
@@ -2015,20 +2150,14 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
             .count()
         )
         tot = (
-            self.tsdf.loc[cast("int", earlier) : cast("int", later)]
+            self.tsdf.loc[cast("Timestamp", earlier) : cast("Timestamp", later)]
             .ffill()
             .pct_change()
             .count()
         )
-        share = pos / tot
-        if self.tsdf.shape[1] == 1:
-            return float(share.iloc[0])
-        return Series(
-            data=share,
-            index=self.tsdf.columns,
-            name="Positive share",
-            dtype="float64",
-        )
+        result = pos / tot
+
+        return self._coerce_result(result=result, name="Positive share")
 
     def ret_vol_ratio_func(
         self: Self,
@@ -2037,7 +2166,7 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
         from_date: dt.date | None = None,
         to_date: dt.date | None = None,
         periods_in_a_year_fixed: DaysInYearType | None = None,
-    ) -> float | Series[float]:
+    ) -> SeriesOrFloat_co:
         """Ratio between arithmetic mean of returns and annualized volatility.
 
         The ratio of annualized arithmetic mean of returns and annualized
@@ -2063,12 +2192,13 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
 
         Returns:
         -------
-        float | Pandas.Series[float]
-            Ratio of the annualized arithmetic mean of returns and annualized
+        SeriesOrFloat_co
+            Ratio of the annualized arithmetic mean of returns and annualized.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
             volatility or, if risk-free return provided, Sharpe ratio
 
         """
-        ratio = Series(
+        result = Series(
             self.arithmetic_ret_func(
                 months_from_last=months_from_last,
                 from_date=from_date,
@@ -2083,14 +2213,7 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
             periods_in_a_year_fixed=periods_in_a_year_fixed,
         )
 
-        if self.tsdf.shape[1] == 1:
-            return float(cast("float64", ratio.iloc[0]))
-        return Series(
-            data=ratio,
-            index=self.tsdf.columns,
-            name="Return vol ratio",
-            dtype="float64",
-        )
+        return self._coerce_result(result=result, name="Return vol ratio")
 
     def sortino_ratio_func(
         self: Self,
@@ -2101,7 +2224,7 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
         from_date: dt.date | None = None,
         to_date: dt.date | None = None,
         periods_in_a_year_fixed: DaysInYearType | None = None,
-    ) -> float | Series[float]:
+    ) -> SeriesOrFloat_co:
         """Sortino Ratio or Kappa3 Ratio.
 
         The Sortino ratio calculated as ( return - risk free return )
@@ -2134,12 +2257,13 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
 
         Returns:
         -------
-        float | Pandas.Series[float]
-            Sortino ratio calculated as ( return - riskfree return ) /
+        SeriesOrFloat_co
+            Sortino ratio calculated as ( return - riskfree return ) /.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
             downside deviation (std dev of returns below MAR)
 
         """
-        ratio = Series(
+        result = Series(
             self.arithmetic_ret_func(
                 months_from_last=months_from_last,
                 from_date=from_date,
@@ -2157,14 +2281,9 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
         )
 
         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" if order == sortino_order else "Kappa-3 ratio",
-            dtype="float64",
-        )
+        name = "Sortino ratio" if order == sortino_order else "Kappa-3 ratio"
+
+        return self._coerce_result(result=result, name=name)
 
     def omega_ratio_func(
         self: Self,
@@ -2172,7 +2291,7 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
         months_from_last: int | None = None,
         from_date: dt.date | None = None,
         to_date: dt.date | None = None,
-    ) -> float | Series[float]:
+    ) -> SeriesOrFloat_co:
         """Omega Ratio.
 
         The Omega Ratio compares returns above a certain target level
@@ -2194,8 +2313,9 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
 
         Returns:
         -------
-        float | Pandas.Series[float]
-            Omega ratio calculation
+        SeriesOrFloat_co
+            Omega ratio calculation.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
 
         """
         earlier, later = self.calc_range(
@@ -2204,29 +2324,22 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
             to_dt=to_date,
         )
         retdf = (
-            self.tsdf.loc[cast("int", earlier) : cast("int", later)]
+            self.tsdf.loc[cast("Timestamp", earlier) : cast("Timestamp", later)]
             .ffill()
             .pct_change()
         )
         pos = retdf[retdf > min_accepted_return].sub(min_accepted_return).sum()
         neg = retdf[retdf < min_accepted_return].sub(min_accepted_return).sum()
-        ratio = pos / -neg
+        result = pos / -neg
 
-        if self.tsdf.shape[1] == 1:
-            return float(cast("float64", ratio.iloc[0]))
-        return Series(
-            data=ratio,
-            index=self.tsdf.columns,
-            name="Omega ratio",
-            dtype="float64",
-        )
+        return self._coerce_result(result=result, name="Omega ratio")
 
     def value_ret_func(
         self: Self,
         months_from_last: int | None = None,
         from_date: dt.date | None = None,
         to_date: dt.date | None = None,
-    ) -> float | Series[float]:
+    ) -> SeriesOrFloat_co:
         """Calculate simple return.
 
         Parameters
@@ -2241,8 +2354,9 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
 
         Returns:
         -------
-        float | Pandas.Series[float]
-            Calculate simple return
+        SeriesOrFloat_co
+            Calculate simple return.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
 
         """
         zero: float = 0.0
@@ -2258,22 +2372,18 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
             )
             raise InitialValueZeroError(msg)
 
-        result = self.tsdf.loc[later] / self.tsdf.loc[earlier] - 1
-
-        if self.tsdf.shape[1] == 1:
-            return float(result.iloc[0])
-        return Series(
-            data=result.to_numpy(),
-            index=self.tsdf.columns,
-            name="Simple return",
-            dtype="float64",
+        result = cast(
+            "Series[float]",
+            self.tsdf.loc[later] / self.tsdf.loc[earlier] - 1,
         )
 
+        return self._coerce_result(result=result, name="Simple return")
+
     def value_ret_calendar_period(
         self: Self,
         year: int,
         month: int | None = None,
-    ) -> float | Series[float]:
+    ) -> SeriesOrFloat_co:
         """Calculate simple return for a specific calendar period.
 
         Parameters
@@ -2285,8 +2395,9 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
 
         Returns:
         -------
-        float | Pandas.Series[float]
-            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:
@@ -2296,16 +2407,10 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
         vrdf = self.tsdf.copy()
         vrdf.index = DatetimeIndex(vrdf.index)
         resultdf = DataFrame(vrdf.ffill().pct_change())
-        result = resultdf.loc[period] + 1
-        cal_period = result.cumprod(axis="index").iloc[-1] - 1
-        if self.tsdf.shape[1] == 1:
-            return float(cal_period.iloc[0])
-        return Series(
-            data=cal_period,
-            index=self.tsdf.columns,
-            name=period,
-            dtype="float64",
-        )
+        plus_one = resultdf.loc[period] + 1
+        result = plus_one.cumprod(axis="index").iloc[-1] - 1
+
+        return self._coerce_result(result=result, name=period)
 
     def var_down_func(
         self: Self,
@@ -2314,7 +2419,7 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
         from_date: dt.date | None = None,
         to_date: dt.date | None = None,
         interpolation: LiteralQuantileInterp = "lower",
-    ) -> float | Series[float]:
+    ) -> SeriesOrFloat_co:
         """Downside Value At Risk, "VaR".
 
         The equivalent of percentile.inc([...], 1-level) over returns in MS Excel.
@@ -2336,8 +2441,9 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
 
         Returns:
         -------
-        float | Pandas.Series[float]
-            Downside Value At Risk
+        SeriesOrFloat_co
+            Downside Value At Risk.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
 
         """
         earlier, later = self.calc_range(
@@ -2346,20 +2452,13 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
             to_dt=to_date,
         )
         result = (
-            self.tsdf.loc[cast("int", earlier) : cast("int", later)]
+            self.tsdf.loc[cast("Timestamp", earlier) : cast("Timestamp", later)]
             .ffill()
             .pct_change()
             .quantile(1 - level, interpolation=interpolation)
         )
 
-        if self.tsdf.shape[1] == 1:
-            return float(result.iloc[0])
-        return Series(
-            data=result,
-            index=self.tsdf.columns,
-            name=f"VaR {level:.1%}",
-            dtype="float64",
-        )
+        return self._coerce_result(result=result, name=f"VaR {level:.1%}")
 
     def worst_func(
         self: Self,
@@ -2367,7 +2466,7 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
         months_from_last: int | None = None,
         from_date: dt.date | None = None,
         to_date: dt.date | None = None,
-    ) -> float | Series[float]:
+    ) -> SeriesOrFloat_co:
         """Most negative percentage change over a rolling number of observations.
 
         Parameters
@@ -2384,8 +2483,9 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
 
         Returns:
         -------
-        float | Pandas.Series[float]
-            Most negative percentage change over a rolling number of observations
+        SeriesOrFloat_co
+            Most negative percentage change over a rolling number of observations.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
             within a chosen date range
 
         """
@@ -2395,7 +2495,7 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
             to_dt=to_date,
         )
         result = (
-            self.tsdf.loc[cast("int", earlier) : cast("int", later)]
+            self.tsdf.loc[cast("Timestamp", earlier) : cast("Timestamp", later)]
             .ffill()
             .pct_change()
             .rolling(observations, min_periods=observations)
@@ -2403,21 +2503,14 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
             .min()
         )
 
-        if self.tsdf.shape[1] == 1:
-            return float(result.iloc[0])
-        return Series(
-            data=result,
-            index=self.tsdf.columns,
-            name="Worst",
-            dtype="float64",
-        )
+        return self._coerce_result(result=result, name="Worst")
 
     def z_score_func(
         self: Self,
         months_from_last: int | None = None,
         from_date: dt.date | None = None,
         to_date: dt.date | None = None,
-    ) -> float | Series[float]:
+    ) -> SeriesOrFloat_co:
         """Z-score as (last return - mean return) / standard deviation of returns.
 
         https://www.investopedia.com/terms/z/zscore.asp.
@@ -2434,8 +2527,9 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
 
         Returns:
         -------
-        float | Pandas.Series[float]
-            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(
@@ -2444,20 +2538,13 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
             to_dt=to_date,
         )
         zscframe = (
-            self.tsdf.loc[cast("int", earlier) : cast("int", later)]
+            self.tsdf.loc[cast("Timestamp", earlier) : cast("Timestamp", later)]
             .ffill()
             .pct_change()
         )
         result = (zscframe.iloc[-1] - zscframe.mean()) / zscframe.std()
 
-        if self.tsdf.shape[1] == 1:
-            return float(result.iloc[0])
-        return Series(
-            data=result,
-            index=self.tsdf.columns,
-            name="Z-score",
-            dtype="float64",
-        )
+        return self._coerce_result(result=result, name="Z-score")
 
     def rolling_cvar_down(
         self: Self,
@@ -2601,7 +2688,7 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
 
         s = log(self.tsdf.iloc[:, column]).diff()
         volseries = s.rolling(window=observations, min_periods=observations).std(
-            ddof=dlta_degr_freedms
+            ddof=dlta_degr_freedms,
         ) * sqrt(time_factor)
 
         voldf = volseries.dropna().to_frame()