openseries 1.5.3__tar.gz → 1.5.5__tar.gz

{openseries-1.5.3 → openseries-1.5.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: openseries
-Version: 1.5.3
+Version: 1.5.5
 Summary: Tools for analyzing financial timeseries.
 Home-page: https://github.com/CaptorAB/openseries
 License: BSD-3-Clause
@@ -53,7 +53,7 @@ width="81" height="100" align="left" float="right"/><br/>
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://beta.ruff.rs/docs/)
 [![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
 
-`openseries` is a project with tools to analyse financial timeseries of a single
+This is a project with tools to analyze financial timeseries of a single
 asset or a group of assets. It is solely made for daily or less frequent data.
 
 <span style="font-size:2em;">[CHANGELOG](https://github.com/CaptorAB/openseries/blob/master/CHANGELOG.md)</span>
@@ -329,6 +329,7 @@ make lint
 | `downside_deviation`    | `float`, `pandas.Series` | `OpenTimeSeries`, `OpenFrame` | [Downside deviation](https://www.investopedia.com/terms/d/downside-deviation.asp) is the volatility of all negative return observations. Minimum Accepted Return (MAR) set to zero.                                     |
 | `ret_vol_ratio`         | `float`, `pandas.Series` | `OpenTimeSeries`, `OpenFrame` | Ratio of arithmetic mean return and annualized volatility. It is the [Sharpe Ratio](https://www.investopedia.com/terms/s/sharperatio.asp) with the riskfree rate set to zero.                                           |
 | `sortino_ratio`         | `float`, `pandas.Series` | `OpenTimeSeries`, `OpenFrame` | The [Sortino Ratio](https://www.investopedia.com/terms/s/sortinoratio.asp) is the arithmetic mean return divided by the downside deviation. This attribute assumes that the riskfree rate and the MAR are both zero.    |
+| `omega_ratio`           | `float`, `pandas.Series` | `OpenTimeSeries`, `OpenFrame` | The [Omega Ratio](https://en.wikipedia.org/wiki/Omega_ratio) compares returns above a certain target level (MAR) to the total downside risk below MAR.                                                                  |
 | `var_down`              | `float`, `pandas.Series` | `OpenTimeSeries`, `OpenFrame` | Downside 95% [Value At Risk](https://www.investopedia.com/terms/v/var.asp), "VaR". The equivalent of percentile.inc([...], 1-level) over returns in MS Excel. For other confidence levels use the corresponding method. |
 | `cvar_down`             | `float`, `pandas.Series` | `OpenTimeSeries`, `OpenFrame` | Downside 95% [Conditional Value At Risk](https://www.investopedia.com/terms/c/conditional_value_at_risk.asp), "CVaR". For other confidence levels use the corresponding method.                                         |
 | `worst`                 | `float`, `pandas.Series` | `OpenTimeSeries`, `OpenFrame` | Most negative percentage change of a single observation.                                                                                                                                                                |
@@ -355,6 +356,7 @@ properties for subset periods._
 | `downside_deviation_func` | `float`, `pandas.Series` | `OpenTimeSeries`, `OpenFrame` | [Downside deviation](https://www.investopedia.com/terms/d/downside-deviation.asp) is the volatility of all negative return observations. MAR and riskfree rate can be set.                                                                                     |
 | `ret_vol_ratio_func`      | `float`, `pandas.Series` | `OpenTimeSeries`, `OpenFrame` | Ratio of arithmetic mean return and annualized volatility. It is the [Sharpe Ratio](https://www.investopedia.com/terms/s/sharperatio.asp) with the riskfree rate set to zero. A riskfree rate can be set as a float or a series chosen for the frame function. |
 | `sortino_ratio_func`      | `float`, `pandas.Series` | `OpenTimeSeries`, `OpenFrame` | The [Sortino Ratio](https://www.investopedia.com/terms/s/sortinoratio.asp) is the arithmetic mean return divided by the downside deviation. A riskfree rate can be set as a float or a series chosen for the frame function. MAR is set to zero.               |
+| `omega_ratio_func`        | `float`, `pandas.Series` | `OpenTimeSeries`, `OpenFrame` | The [Omega Ratio](https://en.wikipedia.org/wiki/Omega_ratio) compares returns above a certain target level (MAR) to the total downside risk below MAR.                                                                                                         |
 | `var_down_func`           | `float`, `pandas.Series` | `OpenTimeSeries`, `OpenFrame` | Downside 95% [Value At Risk](https://www.investopedia.com/terms/v/var.asp), "VaR". The equivalent of percentile.inc([...], 1-level) over returns in MS Excel. Default is 95% confidence level.                                                                 |
 | `cvar_down_func`          | `float`, `pandas.Series` | `OpenTimeSeries`, `OpenFrame` | Downside 95% [Conditional Value At Risk](https://www.investopedia.com/terms/c/conditional_value_at_risk.asp), "CVaR". Default is 95% confidence level.                                                                                                         |
 | `worst_func`              | `float`, `pandas.Series` | `OpenTimeSeries`, `OpenFrame` | Most negative percentage change for a given number of observations (default=1).                                                                                                                                                                                |

{openseries-1.5.3 → openseries-1.5.5}/README.md

@@ -17,7 +17,7 @@ width="81" height="100" align="left" float="right"/><br/>
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://beta.ruff.rs/docs/)
 [![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
 
-`openseries` is a project with tools to analyse financial timeseries of a single
+This is a project with tools to analyze financial timeseries of a single
 asset or a group of assets. It is solely made for daily or less frequent data.
 
 <span style="font-size:2em;">[CHANGELOG](https://github.com/CaptorAB/openseries/blob/master/CHANGELOG.md)</span>
@@ -293,6 +293,7 @@ make lint
 | `downside_deviation`    | `float`, `pandas.Series` | `OpenTimeSeries`, `OpenFrame` | [Downside deviation](https://www.investopedia.com/terms/d/downside-deviation.asp) is the volatility of all negative return observations. Minimum Accepted Return (MAR) set to zero.                                     |
 | `ret_vol_ratio`         | `float`, `pandas.Series` | `OpenTimeSeries`, `OpenFrame` | Ratio of arithmetic mean return and annualized volatility. It is the [Sharpe Ratio](https://www.investopedia.com/terms/s/sharperatio.asp) with the riskfree rate set to zero.                                           |
 | `sortino_ratio`         | `float`, `pandas.Series` | `OpenTimeSeries`, `OpenFrame` | The [Sortino Ratio](https://www.investopedia.com/terms/s/sortinoratio.asp) is the arithmetic mean return divided by the downside deviation. This attribute assumes that the riskfree rate and the MAR are both zero.    |
+| `omega_ratio`           | `float`, `pandas.Series` | `OpenTimeSeries`, `OpenFrame` | The [Omega Ratio](https://en.wikipedia.org/wiki/Omega_ratio) compares returns above a certain target level (MAR) to the total downside risk below MAR.                                                                  |
 | `var_down`              | `float`, `pandas.Series` | `OpenTimeSeries`, `OpenFrame` | Downside 95% [Value At Risk](https://www.investopedia.com/terms/v/var.asp), "VaR". The equivalent of percentile.inc([...], 1-level) over returns in MS Excel. For other confidence levels use the corresponding method. |
 | `cvar_down`             | `float`, `pandas.Series` | `OpenTimeSeries`, `OpenFrame` | Downside 95% [Conditional Value At Risk](https://www.investopedia.com/terms/c/conditional_value_at_risk.asp), "CVaR". For other confidence levels use the corresponding method.                                         |
 | `worst`                 | `float`, `pandas.Series` | `OpenTimeSeries`, `OpenFrame` | Most negative percentage change of a single observation.                                                                                                                                                                |
@@ -319,6 +320,7 @@ properties for subset periods._
 | `downside_deviation_func` | `float`, `pandas.Series` | `OpenTimeSeries`, `OpenFrame` | [Downside deviation](https://www.investopedia.com/terms/d/downside-deviation.asp) is the volatility of all negative return observations. MAR and riskfree rate can be set.                                                                                     |
 | `ret_vol_ratio_func`      | `float`, `pandas.Series` | `OpenTimeSeries`, `OpenFrame` | Ratio of arithmetic mean return and annualized volatility. It is the [Sharpe Ratio](https://www.investopedia.com/terms/s/sharperatio.asp) with the riskfree rate set to zero. A riskfree rate can be set as a float or a series chosen for the frame function. |
 | `sortino_ratio_func`      | `float`, `pandas.Series` | `OpenTimeSeries`, `OpenFrame` | The [Sortino Ratio](https://www.investopedia.com/terms/s/sortinoratio.asp) is the arithmetic mean return divided by the downside deviation. A riskfree rate can be set as a float or a series chosen for the frame function. MAR is set to zero.               |
+| `omega_ratio_func`        | `float`, `pandas.Series` | `OpenTimeSeries`, `OpenFrame` | The [Omega Ratio](https://en.wikipedia.org/wiki/Omega_ratio) compares returns above a certain target level (MAR) to the total downside risk below MAR.                                                                                                         |
 | `var_down_func`           | `float`, `pandas.Series` | `OpenTimeSeries`, `OpenFrame` | Downside 95% [Value At Risk](https://www.investopedia.com/terms/v/var.asp), "VaR". The equivalent of percentile.inc([...], 1-level) over returns in MS Excel. Default is 95% confidence level.                                                                 |
 | `cvar_down_func`          | `float`, `pandas.Series` | `OpenTimeSeries`, `OpenFrame` | Downside 95% [Conditional Value At Risk](https://www.investopedia.com/terms/c/conditional_value_at_risk.asp), "CVaR". Default is 95% confidence level.                                                                                                         |
 | `worst_func`              | `float`, `pandas.Series` | `OpenTimeSeries`, `OpenFrame` | Most negative percentage change for a given number of observations (default=1).                                                                                                                                                                                |

{openseries-1.5.3 → openseries-1.5.5}/openseries/_common_model.py

@@ -38,6 +38,7 @@ from openseries.types import (
     CountriesType,
     DaysInYearType,
     LiteralBarPlotMode,
+    LiteralJsonOutput,
     LiteralLinePlotMode,
     LiteralNanMethod,
     LiteralPlotlyJSlib,
@@ -163,7 +164,7 @@ class _CommonModel(BaseModel):
         return Series(
             data=mddc,
             index=self.tsdf.columns,
-            name="Max Drawdown in cal yr",
+            name="Max drawdown in cal yr",
             dtype="float64",
         )
 
@@ -275,6 +276,20 @@ class _CommonModel(BaseModel):
             min_accepted_return=minimum_accepted_return,
         )
 
+    @property
+    def omega_ratio(self: Self) -> Union[float, Series[float]]:
+        """
+        https://en.wikipedia.org/wiki/Omega_ratio.
+
+        Returns
+        -------
+        Union[float, Pandas.Series[float]]
+            Omega ratio calculation
+
+        """
+        minimum_accepted_return: float = 0.0
+        return self.omega_ratio_func(min_accepted_return=minimum_accepted_return)
+
     @property
     def z_score(self: Self) -> Union[float, Series[float]]:
         """
@@ -637,16 +652,18 @@ class _CommonModel(BaseModel):
 
     def to_json(
         self: Self,
+        what_output: LiteralJsonOutput,
         filename: str,
         directory: Optional[DirectoryPath] = None,
     ) -> list[dict[str, Union[str, bool, ValueType, list[str], list[float]]]]:
         """
         Dump timeseries data into a json file.
 
-        The label and tsdf parameters are deleted before the json file is saved
-
         Parameters
         ----------
+        what_output: LiteralJsonOutput
+            Choice on whether the raw values or the tsdf Dataframe values are
+            returned as json and exported as json file.
         filename: str
             Filename including filetype
         directory: DirectoryPath, optional
@@ -655,7 +672,7 @@ class _CommonModel(BaseModel):
         Returns
         -------
         list[Dict[str, Union[str, bool, ValueType, list[str], list[float]]]]
-            A list of dictionaries with the raw original data of the series
+            A list of dictionaries with the data of the series
 
         """
         if directory:
@@ -669,21 +686,31 @@ class _CommonModel(BaseModel):
         data = dict(self.__dict__)
         output = []
         if "label" in data:
+            if what_output == "tsdf":
+                values = self.tsdf.iloc[:, 0].tolist()
+            else:
+                values = list(cast(list[float], data.get("values")))
             for item in cleaner_list:
                 data.pop(item)
+            valuetype = cast(ValueType, data.get("valuetype")).value
+            data.update({"valuetype": valuetype})
+            data.update({"values": values})
             output.append(dict(data))
         else:
             for serie in cast(list[Any], data.get("constituents")):
+                if what_output == "tsdf":
+                    values = serie.tsdf.iloc[:, 0].tolist()
+                else:
+                    values = list(serie.values)
                 itemdata = dict(serie.__dict__)
                 for item in cleaner_list:
                     itemdata.pop(item)
+                valuetype = cast(ValueType, itemdata["valuetype"]).value
+                itemdata.update({"valuetype": valuetype})
+                itemdata.update({"values": values})
                 output.append(dict(itemdata))
 
-        with Path.open(
-            dirpath.joinpath(filename),
-            "w",
-            encoding="utf-8",
-        ) as jsonfile:
+        with dirpath.joinpath(filename).open(mode="w", encoding="utf-8") as jsonfile:
             dump(output, jsonfile, indent=2, sort_keys=False)
 
         return output
@@ -1679,7 +1706,7 @@ class _CommonModel(BaseModel):
         return Series(
             data=result,
             index=self.tsdf.columns,
-            name="Max Drawdown",
+            name="Max drawdown",
             dtype="float64",
         )
 
@@ -1735,7 +1762,7 @@ class _CommonModel(BaseModel):
         return Series(
             data=share,
             index=self.tsdf.columns,
-            name="Positive Share",
+            name="Positive share",
             dtype="float64",
         )
 
@@ -1869,6 +1896,60 @@ class _CommonModel(BaseModel):
             dtype="float64",
         )
 
+    def omega_ratio_func(
+        self: Self,
+        min_accepted_return: float = 0.0,
+        months_from_last: Optional[int] = None,
+        from_date: Optional[dt.date] = None,
+        to_date: Optional[dt.date] = None,
+    ) -> Union[float, Series[float]]:
+        """
+        Omega Ratio.
+
+        The Omega Ratio compares returns above a certain target level
+        (often referred to as the “minimum acceptable return” or “MAR”)
+        to the total downside risk below that same threshold.
+        https://en.wikipedia.org/wiki/Omega_ratio.
+
+        Parameters
+        ----------
+        min_accepted_return : float, optional
+            The annualized Minimum Accepted Return (MAR)
+        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
+        -------
+        Union[float, Pandas.Series[float]]
+            Omega ratio calculation
+
+        """
+        earlier, later = self.calc_range(
+            months_offset=months_from_last,
+            from_dt=from_date,
+            to_dt=to_date,
+        )
+        retdf = self.tsdf.loc[cast(int, earlier) : cast(int, later)].pct_change(
+            fill_method=cast(str, None),
+        )
+        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
+
+        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",
+        )
+
     def value_ret_func(
         self: Self,
         months_from_last: Optional[int] = None,

{openseries-1.5.3 → openseries-1.5.5}/openseries/load_plotly.py

@@ -7,6 +7,7 @@ from logging import warning
 from pathlib import Path
 
 import requests
+from requests.exceptions import ConnectionError
 
 from openseries.types import CaptorLogoType, PlotlyLayoutType
 
@@ -32,7 +33,7 @@ def _check_remote_file_existence(url: str) -> bool:
         response = requests.head(url, timeout=30)
         if response.status_code != ok_code:
             return False
-    except requests.exceptions.ConnectionError:
+    except ConnectionError:
         return False
     return True
 
@@ -59,9 +60,9 @@ def load_plotly_dict(
     layoutfile = project_root.joinpath("openseries").joinpath("plotly_layouts.json")
     logofile = project_root.joinpath("openseries").joinpath("plotly_captor_logo.json")
 
-    with Path.open(layoutfile, encoding="utf-8") as layout_file:
+    with Path.open(layoutfile, mode="r", encoding="utf-8") as layout_file:
         fig = load(layout_file)
-    with Path.open(logofile, encoding="utf-8") as logo_file:
+    with Path.open(logofile, mode="r", encoding="utf-8") as logo_file:
         logo = load(logo_file)
 
     if _check_remote_file_existence(url=logo["source"]) is False:

{openseries-1.5.3 → openseries-1.5.5}/openseries/types.py

@@ -113,6 +113,7 @@ PlotlyLayoutType = dict[
 
 CaptorLogoType = dict[str, Union[str, float]]
 
+LiteralJsonOutput = Literal["values", "tsdf"]
 LiteralTrunc = Literal["before", "after", "both"]
 LiteralLinePlotMode = Literal[
     "lines",
@@ -220,6 +221,7 @@ class OpenTimeSeriesPropertiesList(list[str]):
         "downside_deviation",
         "ret_vol_ratio",
         "sortino_ratio",
+        "omega_ratio",
         "z_score",
         "skew",
         "kurtosis",
@@ -276,6 +278,7 @@ class OpenFramePropertiesList(list[str]):
         "downside_deviation",
         "ret_vol_ratio",
         "sortino_ratio",
+        "omega_ratio",
         "z_score",
         "skew",
         "kurtosis",

{openseries-1.5.3 → openseries-1.5.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "openseries"
-version = "1.5.3"
+version = "1.5.5"
 description = "Tools for analyzing financial timeseries."
 authors = ["Martin Karrin <martin.karrin@captor.se>"]
 repository = "https://github.com/CaptorAB/openseries"
@@ -47,19 +47,19 @@ scipy = ">=1.11.4,<2.0.0"
 statsmodels = ">=0.14.0,<1.0.0"
 
 [tool.poetry.group.dev.dependencies]
-coverage = "^7.5.0"
+coverage = "^7.5.1"
 coverage-badge = "^1.1.1"
 mypy = "^1.10.0"
-pandas-stubs = "^2.2.1.240316"
-pre-commit = "^3.7.0"
-pytest = "^8.2.0"
-ruff = "^0.4.2"
+pandas-stubs = "^2.2.2.240514"
+pre-commit = "^3.7.1"
+pytest = "^8.2.1"
+ruff = "^0.4.5"
 types-openpyxl = "^3.1.0.20240428"
 types-python-dateutil = "^2.9.0.20240316"
-types-requests = "^2.31.0.20240406"
+types-requests = "^2.32.0.20240523"
 
 [build-system]
-requires = ["poetry-core>=1.8.2"]
+requires = ["poetry-core>=1.8.3"]
 build-backend = "poetry.core.masonry.api"
 
 [tool.pytest.ini_options]