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

openseries/frame.py

@@ -1,11 +1,4 @@
-"""Defining the OpenFrame 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
-"""
+"""The OpenFrame class."""
 
 from __future__ import annotations
 
@@ -18,11 +11,14 @@ from numpy import (
     array,
     asarray,
     concatenate,
+    corrcoef,
     cov,
     diff,
     divide,
     float64,
     isinf,
+    isnan,
+    linalg,
     log,
     nan,
     sqrt,
@@ -64,14 +60,19 @@ from .owntypes import (
     LiteralPandasReindexMethod,
     LiteralPortfolioWeightings,
     LiteralTrunc,
+    MaxDiversificationNaNError,
+    MaxDiversificationNegativeWeightsError,
     MergingResultedInEmptyError,
     MixedValuetypesError,
+    MultipleCurrenciesError,
     NoWeightsError,
     OpenFramePropertiesList,
+    PortfolioItemsNotWithinFrameError,
     RatioInputError,
     ResampleDataLossError,
     Self,
     ValueType,
+    WeightsNotProvidedError,
 )
 from .series import OpenTimeSeries
 
@@ -93,7 +94,7 @@ class OpenFrame(_CommonModel[SeriesFloat]):
         List of weights in float format.
 
     Returns:
-    -------
+    --------
     OpenFrame
         Object of the class OpenFrame
 
@@ -132,7 +133,7 @@ class OpenFrame(_CommonModel[SeriesFloat]):
             List of weights in float format.
 
         Returns:
-        -------
+        --------
         OpenFrame
             Object of the class OpenFrame
 
@@ -164,7 +165,7 @@ class OpenFrame(_CommonModel[SeriesFloat]):
         """Create copy of the OpenFrame object.
 
         Returns:
-        -------
+        --------
         OpenFrame
             An OpenFrame object
 
@@ -183,7 +184,7 @@ class OpenFrame(_CommonModel[SeriesFloat]):
             The Pandas merge method.
 
         Returns:
-        -------
+        --------
         OpenFrame
             An OpenFrame object
 
@@ -227,7 +228,7 @@ class OpenFrame(_CommonModel[SeriesFloat]):
             The properties to calculate. Defaults to calculating all available.
 
         Returns:
-        -------
+        --------
         pandas.DataFrame
             Properties of the contituent OpenTimeSeries
 
@@ -246,7 +247,7 @@ class OpenFrame(_CommonModel[SeriesFloat]):
         """Number of observations of all constituents.
 
         Returns:
-        -------
+        --------
         Pandas.Series[int]
             Number of observations of all constituents
 
@@ -262,7 +263,7 @@ class OpenFrame(_CommonModel[SeriesFloat]):
         """Number of constituents.
 
         Returns:
-        -------
+        --------
         int
             Number of constituents
 
@@ -274,7 +275,7 @@ class OpenFrame(_CommonModel[SeriesFloat]):
         """Level 0 values of the MultiIndex columns in the .tsdf DataFrame.
 
         Returns:
-        -------
+        --------
         list[str]
             Level 0 values of the MultiIndex columns in the .tsdf DataFrame
 
@@ -286,7 +287,7 @@ class OpenFrame(_CommonModel[SeriesFloat]):
         """Level 1 values of the MultiIndex columns in the .tsdf DataFrame.
 
         Returns:
-        -------
+        --------
         list[ValueType]
             Level 1 values of the MultiIndex columns in the .tsdf DataFrame
 
@@ -298,7 +299,7 @@ class OpenFrame(_CommonModel[SeriesFloat]):
         """The first dates in the timeseries of all constituents.
 
         Returns:
-        -------
+        --------
         Pandas.Series[dt.date]
             The first dates in the timeseries of all constituents
 
@@ -315,7 +316,7 @@ class OpenFrame(_CommonModel[SeriesFloat]):
         """The last dates in the timeseries of all constituents.
 
         Returns:
-        -------
+        --------
         Pandas.Series[dt.date]
             The last dates in the timeseries of all constituents
 
@@ -332,7 +333,7 @@ class OpenFrame(_CommonModel[SeriesFloat]):
         """Number of days from the first date to the last for all items in the frame.
 
         Returns:
-        -------
+        --------
         Pandas.Series[int]
             Number of days from the first date to the last for all
             items in the frame.
@@ -348,7 +349,7 @@ class OpenFrame(_CommonModel[SeriesFloat]):
         """Convert series of values into series of returns.
 
         Returns:
-        -------
+        --------
         OpenFrame
             The returns of the values in the series
 
@@ -374,7 +375,7 @@ class OpenFrame(_CommonModel[SeriesFloat]):
             is calculated
 
         Returns:
-        -------
+        --------
         OpenFrame
             An OpenFrame object
 
@@ -393,7 +394,7 @@ class OpenFrame(_CommonModel[SeriesFloat]):
         """Convert series of returns into cumulative series of values.
 
         Returns:
-        -------
+        --------
         OpenFrame
             An OpenFrame object
 
@@ -432,7 +433,7 @@ class OpenFrame(_CommonModel[SeriesFloat]):
             The date offset string that sets the resampled frequency
 
         Returns:
-        -------
+        --------
         OpenFrame
             An OpenFrame object
 
@@ -481,7 +482,7 @@ class OpenFrame(_CommonModel[SeriesFloat]):
             Controls the method used to align values across columns
 
         Returns:
-        -------
+        --------
         OpenFrame
             An OpenFrame object
 
@@ -562,7 +563,7 @@ class OpenFrame(_CommonModel[SeriesFloat]):
             comparisons
 
         Returns:
-        -------
+        --------
         Pandas.DataFrame
             Series volatilities and correlation
 
@@ -658,10 +659,13 @@ class OpenFrame(_CommonModel[SeriesFloat]):
     def correl_matrix(self: Self) -> DataFrame:
         """Correlation matrix.
 
+        This property returns the correlation matrix of the time series
+        in the frame.
+
         Returns:
-        -------
-        Pandas.DataFrame
-            Correlation matrix
+        --------
+        pandas.DataFrame
+            Correlation matrix of the time series in the frame.
 
         """
         corr_matrix = (
@@ -689,7 +693,7 @@ class OpenFrame(_CommonModel[SeriesFloat]):
             The timeseries to add
 
         Returns:
-        -------
+        --------
         OpenFrame
             An OpenFrame object
 
@@ -707,7 +711,7 @@ class OpenFrame(_CommonModel[SeriesFloat]):
             The .tsdf column level 0 value of the timeseries to delete
 
         Returns:
-        -------
+        --------
         OpenFrame
             An OpenFrame object
 
@@ -746,7 +750,7 @@ class OpenFrame(_CommonModel[SeriesFloat]):
             or end_cut is None.
 
         Returns:
-        -------
+        --------
         OpenFrame
             An OpenFrame object
 
@@ -847,7 +851,7 @@ class OpenFrame(_CommonModel[SeriesFloat]):
             comparisons
 
         Returns:
-        -------
+        --------
         Pandas.Series[float]
             Tracking Errors
 
@@ -922,7 +926,7 @@ class OpenFrame(_CommonModel[SeriesFloat]):
             comparisons
 
         Returns:
-        -------
+        --------
         Pandas.Series[float]
             Information Ratios
 
@@ -1005,7 +1009,7 @@ class OpenFrame(_CommonModel[SeriesFloat]):
             comparisons
 
         Returns:
-        -------
+        --------
         Pandas.Series[float]
             Capture Ratios
 
@@ -1191,7 +1195,7 @@ class OpenFrame(_CommonModel[SeriesFloat]):
             Variance bias factor taking the value 0 or 1.
 
         Returns:
-        -------
+        --------
         float
             Beta as Co-variance of x & y divided by Variance of x
 
@@ -1260,7 +1264,7 @@ class OpenFrame(_CommonModel[SeriesFloat]):
             If True the fit is added as a new column in the .tsdf Pandas.DataFrame
 
         Returns:
-        -------
+        --------
         dict[str, float]
             A dictionary with the coefficient, intercept and rsquared outputs.
 
@@ -1329,7 +1333,7 @@ class OpenFrame(_CommonModel[SeriesFloat]):
             Variance bias factor taking the value 0 or 1.
 
         Returns:
-        -------
+        --------
         float
             Jensen's alpha
 
@@ -1401,7 +1405,7 @@ class OpenFrame(_CommonModel[SeriesFloat]):
             weight calculation strategies
 
         Returns:
-        -------
+        --------
         Pandas.DataFrame
             A basket timeseries
 
@@ -1431,6 +1435,60 @@ class OpenFrame(_CommonModel[SeriesFloat]):
                 vol = divide(1.0, std(returns, axis=0, ddof=1))
                 vol[isinf(vol)] = nan
                 self.weights = list(divide(vol, vol.sum()))
+            elif weight_strat == "max_div":
+                corr_matrix = corrcoef(returns.T)
+                corr_matrix[isinf(corr_matrix)] = nan
+                corr_matrix[isnan(corr_matrix)] = nan
+
+                msga = (
+                    "max_div weight strategy failed: "
+                    "correlation matrix contains NaN values"
+                )
+                if isnan(corr_matrix).any():
+                    raise MaxDiversificationNaNError(msga)
+
+                try:
+                    inv_corr_sum = linalg.inv(corr_matrix).sum(axis=1)
+
+                    msgb = (
+                        "max_div weight strategy failed: "
+                        "inverse correlation matrix sum contains NaN values"
+                    )
+                    if isnan(inv_corr_sum).any():
+                        raise MaxDiversificationNaNError(msgb)
+
+                    self.weights = list(divide(inv_corr_sum, inv_corr_sum.sum()))
+
+                    msgc = (
+                        "max_div weight strategy failed: "
+                        "final weights contain NaN values"
+                    )
+                    if any(  # pragma: no cover
+                        isnan(weight) for weight in self.weights
+                    ):
+                        raise MaxDiversificationNaNError(msgc)
+
+                    msgd = (
+                        "max_div weight strategy failed: negative weights detected"
+                        f" - weights: {[round(w, 6) for w in self.weights]}"
+                    )
+                    if any(weight < 0 for weight in self.weights):
+                        raise MaxDiversificationNegativeWeightsError(msgd)
+
+                except linalg.LinAlgError as e:
+                    msge = (
+                        "max_div weight strategy failed: "
+                        f"correlation matrix is singular - {e!s}"
+                    )
+                    raise MaxDiversificationNaNError(msge) from e
+            elif weight_strat == "min_vol_overweight":
+                vols = std(returns, axis=0, ddof=1)
+                min_vol_idx = vols.argmin()
+                min_vol_weight = 0.6
+                remaining_weight = 0.4
+                weights = [remaining_weight / (self.item_count - 1)] * self.item_count
+                weights[min_vol_idx] = min_vol_weight
+                self.weights = weights
             else:
                 raise NotImplementedError(msg)
 
@@ -1466,7 +1524,7 @@ class OpenFrame(_CommonModel[SeriesFloat]):
             Allows locking the periods-in-a-year to simplify test cases and comparisons
 
         Returns:
-        -------
+        --------
         Pandas.DataFrame
             Rolling Information Ratios
 
@@ -1532,7 +1590,7 @@ class OpenFrame(_CommonModel[SeriesFloat]):
             Variance bias factor taking the value 0 or 1.
 
         Returns:
-        -------
+        --------
         Pandas.DataFrame
             Rolling Betas
 
@@ -1592,7 +1650,7 @@ class OpenFrame(_CommonModel[SeriesFloat]):
             The length of the rolling window to use is set as number of observations
 
         Returns:
-        -------
+        --------
         Pandas.DataFrame
             Rolling Correlations
 
@@ -1637,7 +1695,7 @@ class OpenFrame(_CommonModel[SeriesFloat]):
             to use as the dependent variable
 
         Returns:
-        -------
+        --------
         tuple[pandas.DataFrame, OpenTimeSeries]
             - A DataFrame with the R-squared, the intercept
               and the regression coefficients
@@ -1677,3 +1735,271 @@ class OpenFrame(_CommonModel[SeriesFloat]):
         result = DataFrame(data=output, index=indx, columns=[dependent_column[0]])
 
         return result, predictions.to_cumret()
+
+    def rebalanced_portfolio(
+        self: Self,
+        name: str,
+        items: list[str] | None = None,
+        bal_weights: list[float] | None = None,
+        frequency: int = 1,
+        cash_index: OpenTimeSeries | None = None,
+        *,
+        equal_weights: bool = False,
+        drop_extras: bool = True,
+    ) -> OpenFrame:
+        """Create a rebalanced portfolio from the OpenFrame constituents.
+
+        Parameters
+        ----------
+        name: str
+            Name of the portfolio
+        items: list[str], optional
+            List of items to include in the portfolio. If None, uses all items.
+        bal_weights: list[float], optional
+            List of weights for rebalancing. If None, uses frame weights.
+        frequency: int, default: 1
+            Rebalancing frequency
+        cash_index: OpenTimeSeries, optional
+            Cash index series for cash component
+        equal_weights: bool, default: False
+            If True, use equal weights for all items
+        drop_extras: bool, default: True
+            If True, only return TWR series; if False, return all details
+
+        Returns:
+        --------
+        OpenFrame
+            OpenFrame containing the rebalanced portfolio
+
+        """
+        if bal_weights is None and not equal_weights:
+            if self.weights is None:
+                msg = "Weights must be provided."
+                raise WeightsNotProvidedError(msg)
+            bal_weights = list(self.weights)
+
+        if items is None:
+            items = list(self.columns_lvl_zero)
+        else:
+            msg = "Items must be passed as list."
+            if not isinstance(items, list):
+                raise TypeError(msg)
+            if not items:
+                msg = "Items for portfolio must be within SeriesFrame items."
+                raise PortfolioItemsNotWithinFrameError(msg)
+            if not set(items) <= set(self.columns_lvl_zero):
+                msg = "Items for portfolio must be within SeriesFrame items."
+                raise PortfolioItemsNotWithinFrameError(msg)
+
+        if equal_weights:
+            bal_weights = [1 / len(items)] * len(items)
+
+        if cash_index:
+            cash_index.tsdf = cash_index.tsdf.reindex(self.tsdf.index)
+            cash_values: list[float] = cast(
+                "list[float]", cash_index.tsdf.iloc[:, 0].to_numpy().tolist()
+            )
+        else:
+            cash_values = [1.0] * self.length
+
+        if self.tsdf.isna().to_numpy().any():
+            self.value_nan_handle()
+
+        ccies = list({serie.currency for serie in self.constituents})
+
+        if len(ccies) != 1:
+            msg = "Items for portfolio must be denominated in same currency."
+            raise MultipleCurrenciesError(msg)
+
+        currency = ccies[0]
+
+        instruments = [*items, "cash", name]
+        subheaders = [
+            ValueType.PRICE,
+            "buysell_qty",
+            "position",
+            "value",
+            "twr",
+            "settle",
+        ]
+
+        output = {
+            item: {
+                ValueType.PRICE: [],
+                "buysell_qty": [0.0] * self.length,
+                "position": [0.0] * self.length,
+                "value": [0.0] * self.length,
+                "twr": [0.0] * self.length,
+                "settle": [0.0] * self.length,
+            }
+            for item in items
+        }
+        output.update(
+            {
+                "cash": {
+                    ValueType.PRICE: cash_values,
+                    "buysell_qty": [0.0] * self.length,
+                    "position": [0.0] * self.length,
+                    "value": [0.0] * self.length,
+                    "twr": [0.0] * self.length,
+                    "settle": [0.0] * self.length,
+                },
+                name: {
+                    ValueType.PRICE: [1.0] + [0.0] * (self.length - 1),
+                    "buysell_qty": [-1.0] + [0.0] * (self.length - 1),
+                    "position": [-1.0] + [0.0] * (self.length - 1),
+                    "value": [-1.0] + [0.0] * (self.length - 1),
+                    "twr": [1.0] + [0.0] * (self.length - 1),
+                    "settle": [1.0] + [0.0] * (self.length - 1),
+                },
+            },
+        )
+
+        for item, weight in zip(items, cast("list[float]", bal_weights), strict=False):
+            output[item][ValueType.PRICE] = cast(
+                "list[float]", self.tsdf[(item, ValueType.PRICE)].to_numpy().tolist()
+            )
+            output[item]["buysell_qty"][0] = (
+                weight / self.tsdf[(item, ValueType.PRICE)].iloc[0]
+            )
+            output[item]["position"][0] = output[item]["buysell_qty"][0]
+            output[item]["value"][0] = (
+                output[item]["position"][0] * output[item][ValueType.PRICE][0]
+            )
+            output[item]["settle"][0] = (
+                -output[item]["buysell_qty"][0] * output[item][ValueType.PRICE][0]
+            )
+            output["cash"]["buysell_qty"][0] += output[item]["settle"][0]
+            output[item]["twr"][0] = (
+                output[item]["value"][0] / -output[item]["settle"][0]
+            )
+
+        output["cash"]["position"][0] = (
+            output["cash"]["buysell_qty"][0] + output[name]["settle"][0]
+        )
+        output["cash"]["settle"][0] = -output["cash"]["position"][0]
+
+        counter = 1
+        for day in range(1, self.length):
+            portfolio_value = 0.0
+            settle_value = 0.0
+            if day == frequency * counter:
+                for item, weight in zip(
+                    items, cast("list[float]", bal_weights), strict=False
+                ):
+                    output[item]["buysell_qty"][day] = (
+                        weight
+                        - output[item]["value"][day - 1]
+                        / -output[name]["value"][day - 1]
+                    ) / output[item][ValueType.PRICE][day]
+                    output[item]["position"][day] = (
+                        output[item]["position"][day - 1]
+                        + output[item]["buysell_qty"][day]
+                    )
+                    output[item]["value"][day] = (
+                        output[item]["position"][day]
+                        * output[item][ValueType.PRICE][day]
+                    )
+                    portfolio_value += output[item]["value"][day]
+                    output[item]["twr"][day] = (
+                        output[item]["value"][day]
+                        / (
+                            output[item]["value"][day - 1]
+                            - output[item]["settle"][day]
+                        )
+                        * output[item]["twr"][day - 1]
+                    )
+                    output[item]["settle"][day] = (
+                        -output[item]["buysell_qty"][day]
+                        * output[item][ValueType.PRICE][day]
+                    )
+                    settle_value += output[item]["settle"][day]
+                counter += 1
+            else:
+                for item in items:
+                    output[item]["position"][day] = output[item]["position"][day - 1]
+                    output[item]["value"][day] = (
+                        output[item]["position"][day]
+                        * output[item][ValueType.PRICE][day]
+                    )
+                    portfolio_value += output[item]["value"][day]
+                    output[item]["twr"][day] = (
+                        output[item]["value"][day]
+                        / (
+                            output[item]["value"][day - 1]
+                            - output[item]["settle"][day]
+                        )
+                        * output[item]["twr"][day - 1]
+                    )
+            output["cash"]["buysell_qty"][day] = settle_value
+            output["cash"]["position"][day] = (
+                output["cash"]["position"][day - 1]
+                * output["cash"][ValueType.PRICE][day]
+                / output["cash"][ValueType.PRICE][day - 1]
+                + output["cash"]["buysell_qty"][day]
+            )
+            output["cash"]["value"][day] = output["cash"]["position"][day]
+            portfolio_value += output["cash"]["value"][day]
+            output[name]["position"][day] = output[name]["position"][day - 1]
+            output[name]["value"][day] = -portfolio_value
+            output[name]["twr"][day] = (
+                output[name]["value"][day] / output[name]["position"][day]
+            )
+            output[name][ValueType.PRICE][day] = output[name]["twr"][day]
+
+        result = DataFrame()
+        for outvalue in output.values():
+            result = concat(
+                [
+                    result,
+                    DataFrame(
+                        data=outvalue,
+                        index=self.tsdf.index,
+                    ),
+                ],
+                axis="columns",
+            )
+        lvlone, lvltwo = [], []
+        for instr in instruments:
+            lvlone.extend([instr] * 6)
+            lvltwo.extend(subheaders)
+        result.columns = MultiIndex.from_arrays([lvlone, lvltwo])
+
+        series = []
+        if drop_extras:
+            used_constituents = [
+                item for item in self.constituents if item.label in items
+            ]
+            series.extend(
+                [
+                    OpenTimeSeries.from_df(
+                        dframe=result[(item.label, "twr")],
+                        valuetype=ValueType.PRICE,
+                        baseccy=item.currency,
+                        local_ccy=item.local_ccy,
+                    )
+                    for item in used_constituents
+                ]
+            )
+            series.append(
+                OpenTimeSeries.from_df(
+                    dframe=result[(name, "twr")],
+                    valuetype=ValueType.PRICE,
+                    baseccy=currency,
+                    local_ccy=True,
+                ),
+            )
+        else:
+            series.extend(
+                [
+                    OpenTimeSeries.from_df(
+                        dframe=result.loc[:, col],
+                        valuetype=ValueType.PRICE,
+                        baseccy=currency,
+                        local_ccy=True,
+                    ).set_new_label(f"{col[0]}, {col[1]!s}")
+                    for col in result.columns
+                ]
+            )
+
+        return OpenFrame(series)

openseries/load_plotly.py

@@ -1,11 +1,4 @@
-"""Function to load plotly layout and configuration from local json file.
-
-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
-"""
+"""Function to load plotly layout and configuration from local json file."""
 
 from __future__ import annotations
 
@@ -34,7 +27,7 @@ def _check_remote_file_existence(url: str) -> bool:
         Path to remote file
 
     Returns:
-    -------
+    --------
     bool
         True if url is valid and False otherwise
 
@@ -62,7 +55,7 @@ def load_plotly_dict(
         Flag whether to load as responsive
 
     Returns:
-    -------
+    --------
     tuple[PlotlyLayoutType, CaptorLogoType]
         A dictionary with the Plotly config and layout template