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

openseries/__init__.py

@@ -1,5 +1,7 @@
 """openseries.openseries.__init__.py."""
 
+__version__ = "2.0.1"
+
 from .datefixer import (
     date_fix,
     date_offset_foll,

openseries/_common_model.py

@@ -760,6 +760,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
 
         Parameters
         ----------
+
         countries: CountriesType, optional
             (List of) country code(s) according to ISO 3166-1 alpha-2
         markets: list[str] | str, optional
@@ -767,7 +768,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
         custom_holidays: list[str] | str, optional
             Argument where missing holidays can be added
         method: LiteralPandasReindexMethod, default: "nearest"
-
+            Method for reindexing when aligning to business days
 
         Returns:
         --------
@@ -2694,3 +2695,70 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
         )
 
         return DataFrame(voldf)
+
+    def outliers(
+        self: Self,
+        threshold: float = 3.0,
+        months_from_last: int | None = None,
+        from_date: dt.date | None = None,
+        to_date: dt.date | None = None,
+    ) -> Series | DataFrame:
+        """Detect outliers using z-score analysis.
+
+        Identifies data points where the absolute z-score exceeds the threshold.
+        For OpenTimeSeries, returns a pandas Series with dates and outlier values.
+        For OpenFrame, returns a pandas DataFrame with dates and outlier values
+        for each column.
+
+        Parameters
+        ----------
+        threshold: float, default: 3.0
+            Z-score threshold for outlier detection. Values with absolute
+            z-score > threshold are considered outliers.
+        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
+
+        Returns:
+        --------
+        pandas.Series | pandas.DataFrame
+            For OpenTimeSeries: Series with dates as index and outlier values.
+            For OpenFrame: DataFrame with dates as index and outlier values for
+            each column.
+            Returns empty Series/DataFrame if no outliers found.
+
+        """
+        earlier, later = self.calc_range(
+            months_offset=months_from_last,
+            from_dt=from_date,
+            to_dt=to_date,
+        )
+
+        # Get the data for the specified date range
+        data = self.tsdf.loc[cast("Timestamp", earlier) : cast("Timestamp", later)]
+
+        # Calculate z-scores for each column
+        z_scores = (data - data.mean()) / data.std()
+
+        # Find outliers where |z-score| > threshold
+        outliers_mask = z_scores.abs() > threshold
+
+        if self.tsdf.shape[1] == 1:
+            # OpenTimeSeries case - return Series
+            outlier_values = data[outliers_mask].iloc[:, 0].dropna()
+            return Series(
+                data=outlier_values.values,
+                index=outlier_values.index,
+                name="Outliers",
+                dtype="float64",
+            )
+        # OpenFrame case - return DataFrame
+        outlier_df = data[outliers_mask].dropna(how="all")
+        return DataFrame(
+            data=outlier_df,
+            dtype="float64",
+        )

openseries/frame.py

@@ -60,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
 
@@ -1434,12 +1439,49 @@ class OpenFrame(_CommonModel[SeriesFloat]):
                 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()))
-                except linalg.LinAlgError:
-                    self.weights = [1.0 / self.item_count] * self.item_count
-            elif weight_strat == "target_risk":
+
+                    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
@@ -1693,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/owntypes.py

@@ -135,7 +135,9 @@ LiteralPlotlyHistogramHistNorm = Literal[
     "density",
     "probability density",
 ]
-LiteralPortfolioWeightings = Literal["eq_weights", "inv_vol", "max_div", "target_risk"]
+LiteralPortfolioWeightings = Literal[
+    "eq_weights", "inv_vol", "max_div", "min_vol_overweight"
+]
 LiteralMinimizeMethods = Literal[
     "SLSQP",
     "Nelder-Mead",
@@ -374,3 +376,23 @@ class PropertiesInputValidationError(Exception):
 
 class ResampleDataLossError(Exception):
     """Raised when user attempts to run resample_to_business_period_ends on returns."""
+
+
+class WeightsNotProvidedError(Exception):
+    """Raised when weights are not provided."""
+
+
+class MultipleCurrenciesError(Exception):
+    """Raised when multiple currencies are provided."""
+
+
+class PortfolioItemsNotWithinFrameError(Exception):
+    """Raised when portfolio items are not within frame."""
+
+
+class MaxDiversificationNaNError(Exception):
+    """Raised when max_div weight strategy produces NaN values."""
+
+
+class MaxDiversificationNegativeWeightsError(Exception):
+    """Raised when max_div weight strategy produces negative weights."""

{openseries-2.0.0.dist-info → openseries-2.0.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openseries
-Version: 2.0.0
+Version: 2.0.1
 Summary: Tools for analyzing financial timeseries.
 License: # BSD 3-Clause License
          
@@ -35,11 +35,12 @@ Author: Martin Karrin
 Author-email: martin.karrin@captor.se
 Maintainer: Martin Karrin
 Maintainer-email: martin.karrin@captor.se
-Requires-Python: >=3.10,<3.14
+Requires-Python: >=3.10,<3.15
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: License :: OSI Approved :: BSD License
 Classifier: Intended Audience :: Financial and Insurance Industry
 Classifier: Topic :: Office/Business :: Financial :: Investment
@@ -77,6 +78,7 @@ Description-Content-Type: text/markdown
 [![Python version](https://img.shields.io/pypi/pyversions/openseries.svg)](https://www.python.org/)
 [![GitHub Action Test Suite](https://github.com/CaptorAB/openseries/actions/workflows/test.yml/badge.svg)](https://github.com/CaptorAB/openseries/actions/workflows/test.yml)
 [![codecov](https://img.shields.io/codecov/c/gh/CaptorAB/openseries?logo=codecov)](https://codecov.io/gh/CaptorAB/openseries/branch/master)
+[![Documentation](https://readthedocs.org/projects/openseries/badge/?version=latest)](https://openseries.readthedocs.io/en/latest/?badge=latest)
 [![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)](https://python-poetry.org/)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://beta.ruff.rs/docs/)
 [![GitHub License](https://img.shields.io/github/license/CaptorAB/openseries)](https://github.com/CaptorAB/openseries/blob/master/LICENSE.md)

{openseries-2.0.0.dist-info → openseries-2.0.1.dist-info}/RECORD

@@ -1,10 +1,10 @@
-openseries/__init__.py,sha256=WVAO2vtZUZHp7wlXCXV_OKaLkPHfGUjfxTGgBsMdORc,1104
-openseries/_common_model.py,sha256=vXVsSuD6ULTDT6A_sg58uS_yfoazQQvwtjo_jxKMQHA,89131
+openseries/__init__.py,sha256=vkJZmQaReCry7g6f8plQU5RaP1LBwVKe3DoD9ekF3Sc,1127
+openseries/_common_model.py,sha256=y-udTW6LI0Q5er-Egzd4IrFoGHfRGSnsjHJuCu_YTIU,91628
 openseries/_risk.py,sha256=YisMnI8DQT0w9n9SQbrvq0ZZqmZHrz7-jhZtngObJRk,2094
 openseries/datefixer.py,sha256=U1Kc6QdW3UEzAp61NIUALOllyLWb-mJemiL7KLfSAto,15512
-openseries/frame.py,sha256=OCx4soNy_PzjOwpEzxhmdBUIbXjM2WzXv-JaW5GJ4U8,57343
+openseries/frame.py,sha256=g3X3eVkUptawmj7fb-86i21odIFTX_QvwJEcMU_mtO0,69376
 openseries/load_plotly.py,sha256=sVssTMzJ2tPPHceCa9OCavI4Mv5BFgSKR6wnTltnqQQ,1997
-openseries/owntypes.py,sha256=I709YjKqN9W9bJNNezhCQbnmTZgTIZZnoxzoUkbHF8w,9436
+openseries/owntypes.py,sha256=wxyU4d08YrxfEGL_bSI9M6ZVLjipqMLEsq376gVV9lk,10001
 openseries/plotly_captor_logo.json,sha256=F5nhMzEyxKywtjvQqMTKgKRCJQYMDIiBgDSxdte8Clo,178
 openseries/plotly_layouts.json,sha256=MvDEQuiqIhMBXBelXb1sedTOlTPheizv6NZRLeE9YS4,1431
 openseries/portfoliotools.py,sha256=v7s9-AgJFlvPIbPuPf6J7d0VjP-dDT-rsm086EoqSAE,19073
@@ -12,7 +12,7 @@ openseries/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 openseries/report.py,sha256=FYN79MroQfY8DrDSSdsSDBcy6S9PwIS0FyujnqPEQV0,14106
 openseries/series.py,sha256=Wp5G3EmzsBqABtkIPvFQ0Y4T77RhXM9uzvtJBPFWMrQ,28354
 openseries/simulation.py,sha256=J58uHuakeIbZ2Pabha-RtsaO-k-MVsRfXSdZexrMAkI,16071
-openseries-2.0.0.dist-info/METADATA,sha256=8L-PeC1b2pv8VfrC5upsvunrh1WNSiaOMvWg2BfxXZs,6085
-openseries-2.0.0.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
-openseries-2.0.0.dist-info/licenses/LICENSE.md,sha256=wNupG-KLsG0aTncb_SMNDh1ExtrKXlpxSJ6RC-g-SWs,1516
-openseries-2.0.0.dist-info/RECORD,,
+openseries-2.0.1.dist-info/METADATA,sha256=_YFEzFjSM-xzkD9ayOMVf41bJ2NGk8dLw15E2k9yu9c,6281
+openseries-2.0.1.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+openseries-2.0.1.dist-info/licenses/LICENSE.md,sha256=wNupG-KLsG0aTncb_SMNDh1ExtrKXlpxSJ6RC-g-SWs,1516
+openseries-2.0.1.dist-info/RECORD,,