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

openseries/__init__.py

@@ -1,11 +1,4 @@
-"""openseries.openseries.__init__.py.
-
-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
-"""
+"""openseries.openseries.__init__.py."""
 
 from .datefixer import (
     date_fix,

openseries/_common_model.py

@@ -1,10 +1,6 @@
-"""Defining the _CommonModel class.
+"""The _CommonModel class.
 
-Copyright (c) Captor Fund Management AB. This file is part of the openseries project.
-
-Licensed under the BSD 3-Clause License. You may obtain a copy of the License at:
-https://github.com/CaptorAB/openseries/blob/master/LICENSE.md
-SPDX-License-Identifier: BSD-3-Clause
+_CommonModel class which is the base class for OpenFrame and OpenTimeSeries.
 """
 
 from __future__ import annotations
@@ -110,7 +106,7 @@ def _get_date_range_and_factor(
         comparisons
 
     Returns:
-    -------
+    --------
     tuple[dt.date, dt.date, float, DataFrame]
         earlier, later, time_factor, data
     """
@@ -153,7 +149,7 @@ def _get_base_column_data(
         End date
 
     Returns:
-    -------
+    --------
     tuple[Series[float], tuple[str, ValueType], str]
         data, item, label
     """
@@ -196,7 +192,7 @@ def _calculate_time_factor(
         Fixed periods in year
 
     Returns:
-    -------
+    --------
     float
         Time factor
     """
@@ -239,7 +235,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
         """Number of observations.
 
         Returns:
-        -------
+        --------
         int
             Number of observations
 
@@ -251,7 +247,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
         """The first date in the timeseries.
 
         Returns:
-        -------
+        --------
         datetime.date
             The first date in the timeseries
 
@@ -263,7 +259,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
         """The last date in the timeseries.
 
         Returns:
-        -------
+        --------
         datetime.date
             The last date in the timeseries
 
@@ -275,7 +271,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
         """Number of days from the first date to the last.
 
         Returns:
-        -------
+        --------
         int
             Number of days from the first date to the last
 
@@ -287,7 +283,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
         """Length of series expressed in years assuming all years have 365.25 days.
 
         Returns:
-        -------
+        --------
         float
             Length of the timeseries expressed in years assuming all years
             have 365.25 days
@@ -300,7 +296,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
         """The average number of observations per year.
 
         Returns:
-        -------
+        --------
         float
             The average number of observations per year
 
@@ -312,7 +308,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
         """https://www.investopedia.com/terms/m/maximum-drawdown-mdd.asp.
 
         Returns:
-        -------
+        --------
         SeriesOrFloat_co
             Maximum drawdown in a single calendar year.
             Returns float for OpenTimeSeries, Series[float] for OpenFrame.
@@ -334,7 +330,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
         """https://www.investopedia.com/terms/c/cagr.asp.
 
         Returns:
-        -------
+        --------
         SeriesOrFloat_co
             Compounded Annual Growth Rate (CAGR).
             Returns float for OpenTimeSeries, Series[float] for OpenFrame.
@@ -348,7 +344,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
         """https://www.investopedia.com/terms/a/arithmeticmean.asp.
 
         Returns:
-        -------
+        --------
         SeriesOrFloat_co
             Annualized arithmetic mean of returns.
             Returns float for OpenTimeSeries, Series[float] for OpenFrame.
@@ -362,7 +358,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
         """Simple return.
 
         Returns:
-        -------
+        --------
         SeriesOrFloat_co
             Simple return.
             Returns float for OpenTimeSeries, Series[float] for OpenFrame.
@@ -379,7 +375,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
         https://www.investopedia.com/terms/v/volatility.asp.
 
         Returns:
-        -------
+        --------
         SeriesOrFloat_co
             Annualized volatility.
             Returns float for OpenTimeSeries, Series[float] for OpenFrame.
@@ -397,7 +393,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
         https://www.investopedia.com/terms/d/downside-deviation.asp.
 
         Returns:
-        -------
+        --------
         SeriesOrFloat_co
             Downside deviation.
             Returns float for OpenTimeSeries, Series[float] for OpenFrame.
@@ -416,10 +412,9 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
         """Ratio of annualized arithmetic mean of returns and annualized volatility.
 
         Returns:
-        -------
+        --------
         SeriesOrFloat_co
-            Ratio of the annualized arithmetic mean of returns and annualized.
-            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
+            Ratio of the annualized arithmetic mean of returns and annualized
             volatility.
             Returns float for OpenTimeSeries, Series[float] for OpenFrame.
 
@@ -432,10 +427,9 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
         """https://www.investopedia.com/terms/s/sortinoratio.asp.
 
         Returns:
-        -------
+        --------
         SeriesOrFloat_co
-            Sortino ratio calculated as the annualized arithmetic mean of returns.
-            Returns float for OpenTimeSeries, Series[float] for OpenFrame
+            Sortino ratio calculated as the annualized arithmetic mean of returns
             / downside deviation. The ratio implies that the riskfree asset has zero
             volatility, and a minimum acceptable return of zero.
             Returns float for OpenTimeSeries, Series[float] for OpenFrame.
@@ -459,10 +453,9 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
         the Sortino ratio (which uses order 2).
 
         Returns:
-        -------
+        --------
         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.
 
@@ -481,7 +474,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
         """https://en.wikipedia.org/wiki/Omega_ratio.
 
         Returns:
-        -------
+        --------
         SeriesOrFloat_co
             Omega ratio calculation.
             Returns float for OpenTimeSeries, Series[float] for OpenFrame.
@@ -496,7 +489,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
         """https://www.investopedia.com/terms/z/zscore.asp.
 
         Returns:
-        -------
+        --------
         SeriesOrFloat_co
             Z-score as (last return - mean return) / standard deviation of returns.
             Returns float for OpenTimeSeries, Series[float] for OpenFrame.
@@ -510,7 +503,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
         """https://www.investopedia.com/terms/m/maximum-drawdown-mdd.asp.
 
         Returns:
-        -------
+        --------
         SeriesOrFloat_co
             Maximum drawdown without any limit on date range.
             Returns float for OpenTimeSeries, Series[float] for OpenFrame.
@@ -526,7 +519,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
         https://www.investopedia.com/terms/m/maximum-drawdown-mdd.asp.
 
         Returns:
-        -------
+        --------
         datetime.date | pandas.Series[dt.date]
             Date when the maximum drawdown occurred
 
@@ -549,7 +542,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
         """Most negative percentage change.
 
         Returns:
-        -------
+        --------
         SeriesOrFloat_co
             Most negative percentage change.
             Returns float for OpenTimeSeries, Series[float] for OpenFrame.
@@ -564,7 +557,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
         """Most negative month.
 
         Returns:
-        -------
+        --------
         SeriesOrFloat_co
             Most negative month.
             Returns float for OpenTimeSeries, Series[float] for OpenFrame.
@@ -610,7 +603,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
         """The share of percentage changes that are greater than zero.
 
         Returns:
-        -------
+        --------
         SeriesOrFloat_co
             The share of percentage changes that are greater than zero.
             Returns float for OpenTimeSeries, Series[float] for OpenFrame.
@@ -624,7 +617,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
         """https://www.investopedia.com/terms/s/skewness.asp.
 
         Returns:
-        -------
+        --------
         SeriesOrFloat_co
             Skew of the return distribution.
             Returns float for OpenTimeSeries, Series[float] for OpenFrame.
@@ -638,7 +631,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
         """https://www.investopedia.com/terms/k/kurtosis.asp.
 
         Returns:
-        -------
+        --------
         SeriesOrFloat_co
             Kurtosis of the return distribution.
             Returns float for OpenTimeSeries, Series[float] for OpenFrame.
@@ -652,7 +645,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
         """https://www.investopedia.com/terms/c/conditional_value_at_risk.asp.
 
         Returns:
-        -------
+        --------
         SeriesOrFloat_co
             Downside 95% Conditional Value At Risk "CVaR".
             Returns float for OpenTimeSeries, Series[float] for OpenFrame.
@@ -670,7 +663,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
         https://www.investopedia.com/terms/v/var.asp.
 
         Returns:
-        -------
+        --------
         SeriesOrFloat_co
             Downside 95% Value At Risk (VaR).
             Returns float for OpenTimeSeries, Series[float] for OpenFrame.
@@ -688,10 +681,9 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
         Assumes that returns are normally distributed.
 
         Returns:
-        -------
+        --------
         SeriesOrFloat_co
-            Implied annualized volatility from the Downside 95% VaR using the.
-            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
+            Implied annualized volatility from the Downside 95% VaR using the
             assumption that returns are normally distributed.
             Returns float for OpenTimeSeries, Series[float] for OpenFrame.
 
@@ -719,7 +711,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
             Specific from date
 
         Returns:
-        -------
+        --------
         tuple[datetime.date, datetime.date]
             Start and end date of the chosen date range
 
@@ -776,8 +768,9 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
             Argument where missing holidays can be added
         method: LiteralPandasReindexMethod, default: "nearest"
 
+
         Returns:
-        -------
+        --------
         OpenFrame
             An OpenFrame object
 
@@ -837,7 +830,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
         Equivalent to LN(value[t] / value[t=0]) in Excel.
 
         Returns:
-        -------
+        --------
         self
             An object of the same class
 
@@ -858,7 +851,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
             Method used to handle NaN. Either fill with last known or drop
 
         Returns:
-        -------
+        --------
         self
             An object of the same class
 
@@ -878,7 +871,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
             Method used to handle NaN. Either fill with zero or drop
 
         Returns:
-        -------
+        --------
         self
             An object of the same class
 
@@ -893,7 +886,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
         """Convert timeseries into a drawdown series.
 
         Returns:
-        -------
+        --------
         self
             An object of the same class
 
@@ -923,7 +916,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
             File folder location
 
         Returns:
-        -------
+        --------
         list[dict[str, str | bool | ValueType | list[str] | list[float]]]
             A list of dictionaries with the data of the series
 
@@ -990,7 +983,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
             Flag whether to overwrite an existing file
 
         Returns:
-        -------
+        --------
         str
             The Excel file path
 
@@ -1161,7 +1154,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
             If True a Captor logo is added to the plot
 
         Returns:
-        -------
+        --------
         tuple[plotly.go.Figure, str]
             Plotly Figure and a div section or a html filename with location
 
@@ -1258,7 +1251,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
             If True the last self.tsdf point is highlighted as red dot with a label
 
         Returns:
-        -------
+        --------
         tuple[plotly.go.Figure, str]
             Plotly Figure and a div section or a html filename with location
 
@@ -1395,7 +1388,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
             If True a Captor logo is added to the plot
 
         Returns:
-        -------
+        --------
         tuple[plotly.go.Figure, str]
             Plotly Figure and a div section or a html filename with location
 
@@ -1493,7 +1486,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
             comparisons
 
         Returns:
-        -------
+        --------
         SeriesOrFloat_co
             Annualized arithmetic mean of returns.
             Returns float for OpenTimeSeries, Series[float] for OpenFrame.
@@ -1537,7 +1530,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
             Allows locking the periods-in-a-year to simplify test cases and comparisons
 
         Returns:
-        -------
+        --------
         SeriesOrFloat_co
             Annualized volatility.
             Returns float for OpenTimeSeries, Series[float] for OpenFrame.
@@ -1591,11 +1584,11 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
             An adjustment to remove the bias implied by the average return
 
         Returns:
-        -------
+        --------
         SeriesOrFloat_co
-            Implied annualized volatility from the Downside VaR using the.
-            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
+            Implied annualized volatility from the Downside VaR using the
             assumption that returns are normally distributed.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
 
         """
         return self._var_implied_vol_and_target_func(
@@ -1653,11 +1646,11 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
             An adjustment to remove the bias implied by the average return
 
         Returns:
-        -------
+        --------
         SeriesOrFloat_co
-            A position weight multiplier from the ratio between a VaR implied.
+            A position weight multiplier from the ratio between a VaR implied
+            volatility and a given target volatility. Multiplier = 1.0 -> target met.
             Returns float for OpenTimeSeries, Series[float] for OpenFrame.
-            volatility and a given target volatility. Multiplier = 1.0 -> target met
 
         """
         return self._var_implied_vol_and_target_func(
@@ -1720,11 +1713,11 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
             An adjustment to remove the bias implied by the average return
 
         Returns:
-        -------
+        --------
         SeriesOrFloat_co
-            Target volatility if target_vol is provided otherwise the VaR.
-            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
+            Target volatility if target_vol is provided otherwise the VaR
             implied volatility.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
 
         """
         earlier, later = self.calc_range(
@@ -1808,7 +1801,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
             Specific to date
 
         Returns:
-        -------
+        --------
         SeriesOrFloat_co
             Downside Conditional Value At Risk "CVaR".
             Returns float for OpenTimeSeries, Series[float] for OpenFrame.
@@ -1868,7 +1861,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
             comparisons
 
         Returns:
-        -------
+        --------
         SeriesOrFloat_co
             Downside deviation if order set to 2.
             Returns float for OpenTimeSeries, Series[float] for OpenFrame.
@@ -1942,7 +1935,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
             Specific to date
 
         Returns:
-        -------
+        --------
         SeriesOrFloat_co
             Compounded Annual Growth Rate (CAGR).
             Returns float for OpenTimeSeries, Series[float] for OpenFrame.
@@ -1992,7 +1985,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
             Specific to date
 
         Returns:
-        -------
+        --------
         SeriesOrFloat_co
             Skew of the return distribution.
             Returns float for OpenTimeSeries, Series[float] for OpenFrame.
@@ -2036,7 +2029,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
             Specific to date
 
         Returns:
-        -------
+        --------
         SeriesOrFloat_co
             Kurtosis of the return distribution.
             Returns float for OpenTimeSeries, Series[float] for OpenFrame.
@@ -2087,7 +2080,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
             Smallest number of observations to use to find the maximum drawdown
 
         Returns:
-        -------
+        --------
         SeriesOrFloat_co
             Maximum drawdown without any limit on date range.
             Returns float for OpenTimeSeries, Series[float] for OpenFrame.
@@ -2126,7 +2119,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
             Specific to date
 
         Returns:
-        -------
+        --------
         SeriesOrFloat_co
             Calculate share of percentage changes that are greater than zero.
             Returns float for OpenTimeSeries, Series[float] for OpenFrame.
@@ -2191,11 +2184,11 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
             comparisons
 
         Returns:
-        -------
+        --------
         SeriesOrFloat_co
-            Ratio of the annualized arithmetic mean of returns and annualized.
+            Ratio of the annualized arithmetic mean of returns and annualized
+            volatility or, if risk-free return provided, Sharpe ratio.
             Returns float for OpenTimeSeries, Series[float] for OpenFrame.
-            volatility or, if risk-free return provided, Sharpe ratio
 
         """
         result = Series(
@@ -2256,11 +2249,11 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
             comparisons
 
         Returns:
-        -------
+        --------
         SeriesOrFloat_co
-            Sortino ratio calculated as ( return - riskfree return ) /.
+            Sortino ratio calculated as ( return - riskfree return ) /
+            downside deviation (std dev of returns below MAR).
             Returns float for OpenTimeSeries, Series[float] for OpenFrame.
-            downside deviation (std dev of returns below MAR)
 
         """
         result = Series(
@@ -2312,7 +2305,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
             Specific to date
 
         Returns:
-        -------
+        --------
         SeriesOrFloat_co
             Omega ratio calculation.
             Returns float for OpenTimeSeries, Series[float] for OpenFrame.
@@ -2353,7 +2346,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
             Specific to date
 
         Returns:
-        -------
+        --------
         SeriesOrFloat_co
             Calculate simple return.
             Returns float for OpenTimeSeries, Series[float] for OpenFrame.
@@ -2394,7 +2387,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
             Calendar month of the period to calculate.
 
         Returns:
-        -------
+        --------
         SeriesOrFloat_co
             Calculate simple return for a specific calendar period.
             Returns float for OpenTimeSeries, Series[float] for OpenFrame.
@@ -2440,7 +2433,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
             Type of interpolation in Pandas.DataFrame.quantile() function.
 
         Returns:
-        -------
+        --------
         SeriesOrFloat_co
             Downside Value At Risk.
             Returns float for OpenTimeSeries, Series[float] for OpenFrame.
@@ -2482,11 +2475,11 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
             Specific to date
 
         Returns:
-        -------
+        --------
         SeriesOrFloat_co
-            Most negative percentage change over a rolling number of observations.
+            Most negative percentage change over a rolling number of observations
+            within a chosen date range.
             Returns float for OpenTimeSeries, Series[float] for OpenFrame.
-            within a chosen date range
 
         """
         earlier, later = self.calc_range(
@@ -2526,7 +2519,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
             Specific to date
 
         Returns:
-        -------
+        --------
         SeriesOrFloat_co
             Z-score as (last return - mean return) / standard deviation of returns.
             Returns float for OpenTimeSeries, Series[float] for OpenFrame.
@@ -2564,7 +2557,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
             Number of observations in the overlapping window.
 
         Returns:
-        -------
+        --------
         Pandas.DataFrame
             Calculate rolling annualized downside CVaR
 
@@ -2595,7 +2588,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
             Number of observations in the overlapping window.
 
         Returns:
-        -------
+        --------
         Pandas.DataFrame
             Calculate rolling returns
 
@@ -2634,7 +2627,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
             Type of interpolation in Pandas.DataFrame.quantile() function.
 
         Returns:
-        -------
+        --------
         Pandas.DataFrame
            Calculate rolling annualized downside Value At Risk "VaR"
 
@@ -2674,7 +2667,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
             Variance bias factor taking the value 0 or 1.
 
         Returns:
-        -------
+        --------
         Pandas.DataFrame
             Calculate rolling annualised volatilities
 

openseries/_risk.py

@@ -1,11 +1,4 @@
-"""Various risk related functions.
-
-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
-"""
+"""Functions caclculating risk measures."""
 
 from __future__ import annotations
 
@@ -40,7 +33,7 @@ def _cvar_down_calc(
         The sought CVaR level
 
     Returns:
-    -------
+    --------
     float
         Downside Conditional Value At Risk "CVaR"
 
@@ -74,7 +67,7 @@ def _var_down_calc(
         type of interpolation in Pandas.DataFrame.quantile() function.
 
     Returns:
-    -------
+    --------
     float
         Downside Value At Risk