openseries 2.1.5__tar.gz → 2.1.7__tar.gz

{openseries-2.1.5 → openseries-2.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openseries
-Version: 2.1.5
+Version: 2.1.7
 Summary: Tools for analyzing financial timeseries.
 License-Expression: BSD-3-Clause
 License-File: LICENSE.md
@@ -31,6 +31,7 @@ Requires-Dist: python-dateutil (>=2.8.2)
 Requires-Dist: requests (>=2.20.0)
 Requires-Dist: scikit-learn (>=1.4.0)
 Requires-Dist: scipy (>=1.14.1)
+Requires-Dist: tzdata (>=2025.3)
 Project-URL: Documentation, https://openseries.readthedocs.io/
 Project-URL: Homepage, https://captorab.github.io/openseries/
 Project-URL: Issue Tracker, https://github.com/CaptorAB/openseries/issues
@@ -50,7 +51,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 Status](https://readthedocs.org/projects/openseries/badge/?version=latest)
+[![Documentation Status](https://readthedocs.org/projects/openseries/badge/?version=latest)](https://captorab.github.io/openseries/)
 [![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)
@@ -60,7 +61,7 @@ Tools for analyzing financial timeseries of a single asset or a group of assets.
 
 ## Documentation
 
-Complete documentation is available at: [https://openseries.readthedocs.io](https://openseries.readthedocs.io/)
+Complete documentation is available at: [https://captorab.github.io/openseries/](https://captorab.github.io/openseries/)
 
 The documentation includes:
 

{openseries-2.1.5 → openseries-2.1.7}/README.md

@@ -10,7 +10,7 @@
 [![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 Status](https://readthedocs.org/projects/openseries/badge/?version=latest)
+[![Documentation Status](https://readthedocs.org/projects/openseries/badge/?version=latest)](https://captorab.github.io/openseries/)
 [![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)
@@ -20,7 +20,7 @@ Tools for analyzing financial timeseries of a single asset or a group of assets.
 
 ## Documentation
 
-Complete documentation is available at: [https://openseries.readthedocs.io](https://openseries.readthedocs.io/)
+Complete documentation is available at: [https://captorab.github.io/openseries/](https://captorab.github.io/openseries/)
 
 The documentation includes:
 

{openseries-2.1.5 → openseries-2.1.7}/openseries/_common_model.py

@@ -162,6 +162,30 @@ def _get_base_column_data(
     return data, item, label
 
 
+def _demeaned_returns_for_autocorr(
+    series: Series[float], valuetype: ValueType, *, squared: bool = False
+) -> Series[float]:
+    """Return demeaned return series for autocorrelation analysis.
+
+    Args:
+        series: Input series (prices or returns).
+        valuetype: ValueType.PRICE for price data (pct_change applied),
+            else use as returns.
+        squared: If True, square the demeaned returns.
+
+    Returns:
+        Demeaned return series (optionally squared).
+    """
+    if valuetype == ValueType.PRICE:
+        rets = series.ffill().pct_change().dropna()
+    else:
+        rets = series.ffill().dropna()
+    rets = rets - rets.mean()
+    if squared:
+        rets = rets**2
+    return rets
+
+
 def _calculate_time_factor(
     data: Series[float],
     earlier: dt.date,
@@ -282,8 +306,9 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
         result = (
             self.tsdf.groupby(years)
             .apply(
-                lambda prices: (prices / prices.expanding(min_periods=1).max()).min()
-                - 1,
+                lambda prices: (
+                    (prices / prices.expanding(min_periods=1).max()).min() - 1
+                ),
             )
             .min()
         )
@@ -353,6 +378,23 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
         """
         return self.vol_func()
 
+    @property
+    def autocorr(self: Self) -> SeriesOrFloat_co:
+        """Autocorrelation at lag 1.
+
+        Shorthand for ``autocorr_func(lag=1)``. Returns the lag-1 autocorrelation
+        of demeaned returns. For price series, returns are computed via
+        ``pct_change``; for return series, raw values are used after demeaning.
+
+        Returns:
+        --------
+        SeriesOrFloat_co
+            Autocorrelation at lag 1.
+            Returns float for OpenTimeSeries, Series[float] for OpenFrame.
+
+        """
+        return self.autocorr_func()
+
     @property
     def downside_deviation(self: Self) -> SeriesOrFloat_co:
         """Downside Deviation.
@@ -823,7 +865,7 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
                 else None,
             )
         ]
-        self.tsdf = self.tsdf.reindex(labels=d_range, method=method, copy=False)
+        self.tsdf = self.tsdf.reindex(labels=d_range, method=method)
 
         return self
 
@@ -1481,6 +1523,50 @@ class _CommonModel(BaseModel, Generic[SeriesOrFloat_co]):
 
         return self._coerce_result(result=result, name="Volatility")
 
+    def autocorr_func(
+        self: Self,
+        lag: int = 1,
+        *,
+        squared: bool = False,
+    ) -> SeriesOrFloat_co:
+        """Calculate autocorrelation at a given lag.
+
+        Computes the autocorrelation of demeaned returns at the specified lag.
+        For price series (ValueType.PRICE), returns are derived via ``pct_change``;
+        for return series (ValueType.RTRN), raw values are demeaned. Use
+        ``squared=True`` for squared-return autocorrelation (e.g. volatility
+        clustering). Returns ``nan`` when the series has too few observations.
+
+        Args:
+            lag: The lag at which to compute autocorrelation. Defaults to 1.
+            squared: If True, compute autocorrelation of squared returns.
+                Defaults to False.
+
+        Returns:
+            Autocorrelation at the specified lag. Float for OpenTimeSeries,
+            ``Series[float]`` for OpenFrame.
+        """
+        values: list[float] = []
+        vtypes = self.tsdf.columns.get_level_values(1)
+        for col_idx, col in enumerate(self.tsdf.columns):
+            valuetype = cast("ValueType", vtypes[col_idx])
+            rets = _demeaned_returns_for_autocorr(
+                series=self.tsdf[col],
+                valuetype=valuetype,
+                squared=squared,
+            )
+            if len(rets) > lag:
+                values.append(float(rets.autocorr(lag=lag)))
+            else:
+                values.append(float("nan"))
+        result = Series(
+            data=values,
+            index=self.tsdf.columns,
+            name="Autocorrelation",
+            dtype="float64",
+        )
+        return self._coerce_result(result=result, name="Autocorrelation")
+
     def vol_from_var_func(
         self: Self,
         level: float = 0.95,

{openseries-2.1.5 → openseries-2.1.7}/openseries/datefixer.py

@@ -374,13 +374,22 @@ def generate_calendar_date_range(
         raise TradingDaysNotAboveZeroError(msg)
 
     if start and not end:
+        adjusted_start = date_offset_foll(
+            raw_date=start,
+            months_offset=0,
+            countries=countries,
+            markets=markets,
+            custom_holidays=custom_holidays,
+            adjust=True,
+            following=True,
+        )
         tmp_range = date_range(
-            start=start,
+            start=adjusted_start,
             periods=trading_days * 365 // 252,
             freq="D",
         )
         calendar = holiday_calendar(
-            startyear=start.year,
+            startyear=adjusted_start.year,
             endyear=date_fix(tmp_range.tolist()[-1]).year,
             countries=countries,
             markets=markets,
@@ -389,17 +398,30 @@ def generate_calendar_date_range(
         return [
             d.date()
             for d in date_range(
-                start=start,
+                start=adjusted_start,
                 periods=trading_days,
                 freq=CustomBusinessDay(calendar=calendar),
             )
         ]
 
     if end and not start:
-        tmp_range = date_range(end=end, periods=trading_days * 365 // 252, freq="D")
+        adjusted_end = date_offset_foll(
+            raw_date=end,
+            months_offset=0,
+            countries=countries,
+            markets=markets,
+            custom_holidays=custom_holidays,
+            adjust=True,
+            following=False,
+        )
+        tmp_range = date_range(
+            end=adjusted_end,
+            periods=trading_days * 365 // 252,
+            freq="D",
+        )
         calendar = holiday_calendar(
             startyear=date_fix(tmp_range.tolist()[0]).year,
-            endyear=end.year,
+            endyear=adjusted_end.year,
             countries=countries,
             markets=markets,
             custom_holidays=custom_holidays,
@@ -407,7 +429,7 @@ def generate_calendar_date_range(
         return [
             d.date()
             for d in date_range(
-                end=end,
+                end=adjusted_end,
                 periods=trading_days,
                 freq=CustomBusinessDay(calendar=calendar),
             )

{openseries-2.1.5 → openseries-2.1.7}/openseries/frame.py

@@ -663,13 +663,12 @@ class OpenFrame(_CommonModel[SeriesFloat]):
         if not end_cut and where in ["after", "both"]:
             end_cut = self.last_indices.min()
         self.tsdf = self.tsdf.sort_index()
-        self.tsdf = self.tsdf.truncate(before=start_cut, after=end_cut, copy=False)
+        self.tsdf = self.tsdf.truncate(before=start_cut, after=end_cut)
 
         for xerie in self.constituents:
             xerie.tsdf = xerie.tsdf.truncate(
                 before=start_cut,
                 after=end_cut,
-                copy=False,
             )
         if len(set(self.first_indices)) != 1:
             msg = (

{openseries-2.1.5 → openseries-2.1.7}/openseries/owntypes.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import datetime as dt
-from enum import Enum
+from enum import StrEnum
 from pprint import pformat
 from typing import (
     TYPE_CHECKING,
@@ -184,11 +184,14 @@ LiteralSeriesProps = Literal[
     "span_of_days",
     "yearfrac",
     "periods_in_a_year",
+    "autocorr",
+    "partial_autocorr",
 ]
 LiteralFrameProps = Literal[
     "value_ret",
     "geo_ret",
     "arithmetic_ret",
+    "autocorr",
     "vol",
     "downside_deviation",
     "ret_vol_ratio",
@@ -273,6 +276,8 @@ class OpenTimeSeriesPropertiesList(PropertiesList):
         "span_of_days",
         "yearfrac",
         "periods_in_a_year",
+        "autocorr",
+        "partial_autocorr",
     }
 
     def __init__(
@@ -288,6 +293,7 @@ class OpenFramePropertiesList(PropertiesList):
     """Allowed property arguments for the OpenFrame class."""
 
     allowed_strings: ClassVar[set[str]] = PropertiesList.allowed_strings | {
+        "autocorr",
         "first_indices",
         "last_indices",
         "lengths_of_items",
@@ -300,10 +306,11 @@ class OpenFramePropertiesList(PropertiesList):
         self._validate()
 
 
-class ValueType(str, Enum):
+class ValueType(StrEnum):
     """Enum types of OpenTimeSeries to identify the output."""
 
-    EWMA = "EWMA"
+    EWMA_VOL = "EWMA volatility"
+    EWMA_VAR = "EWMA VaR"
     PRICE = "Price(Close)"
     RTRN = "Return(Total)"
     RELRTRN = "Relative return"

{openseries-2.1.5 → openseries-2.1.7}/openseries/portfoliotools.py

@@ -296,8 +296,10 @@ def _build_frontier_dataframe(
     weight_cols = columns_lvl_zero
     weight_header = "<br><br>Weights:<br>"
     line_df["text"] = line_df[weight_cols].apply(
-        lambda row: weight_header
-        + "<br>".join([f"{row[col]:.1%}  {col}" for col in weight_cols]),
+        lambda row: (
+            weight_header
+            + "<br>".join([f"{row[col]:.1%}  {col}" for col in weight_cols])
+        ),
         axis=1,
     )
 
@@ -781,7 +783,7 @@ def _generate_sharpeplot_output(
         )
         return str(plotfile)
 
-    div_id = filename.split(sep=".")[0]
+    div_id = filename.split(maxsplit=1, sep=".")[0]
     return cast(
         "str",
         to_html(

{openseries-2.1.5 → openseries-2.1.7}/openseries/report.py

@@ -586,19 +586,21 @@ def report_html(
 
     for item, f in zip(rpt_df.index, formats, strict=False):
         rpt_df.loc[item] = rpt_df.loc[item].apply(
-            lambda x, fmt=f: ""
-            if (
-                x is None
-                or (not isinstance(x, str) and isna(x))
-                or (isinstance(x, str) and x.lower() in ("nan", "nan%", ""))
-            )
-            else (
-                str(x)
-                if isinstance(x, str)
+            lambda x, fmt=f: (
+                ""
+                if (
+                    x is None
+                    or (not isinstance(x, str) and isna(x))
+                    or (isinstance(x, str) and x.lower() in ("nan", "nan%", ""))
+                )
                 else (
-                    Timestamp(x).strftime("%Y-%m-%d")
-                    if "%Y-%m-%d" in fmt and not isinstance(x, str)
-                    else fmt.format(x)
+                    str(x)
+                    if isinstance(x, str)
+                    else (
+                        Timestamp(x).strftime("%Y-%m-%d")
+                        if "%Y-%m-%d" in fmt and not isinstance(x, str)
+                        else fmt.format(x)
+                    )
                 )
             ),
         )

{openseries-2.1.5 → openseries-2.1.7}/openseries/series.py

@@ -32,8 +32,13 @@ from pandas import (
     date_range,
 )
 from pydantic import field_validator, model_validator
+from scipy.stats import chi2, norm
 
-from ._common_model import _calculate_time_factor, _CommonModel
+from ._common_model import (
+    _calculate_time_factor,
+    _CommonModel,
+    _demeaned_returns_for_autocorr,
+)
 from .datefixer import _do_resample_to_business_period_ends, date_fix
 from .owntypes import (
     Countries,
@@ -415,7 +420,18 @@ class OpenTimeSeries(_CommonModel[float]):
             )
 
         props = OpenTimeSeriesPropertiesList(*properties)
-        pdf = DataFrame.from_dict({x: getattr(self, x) for x in props}, orient="index")
+
+        def _prop_value(name: str) -> float | int | dt.date | Series[float]:
+            attr = getattr(self, name)
+            return cast(
+                "float | int | dt.date | Series[float]",
+                attr() if callable(attr) else attr,
+            )
+
+        pdf = DataFrame.from_dict(
+            {x: _prop_value(x) for x in props},
+            orient="index",
+        )
         pdf.columns = self.tsdf.columns
         return pdf
 
@@ -647,7 +663,83 @@ class OpenTimeSeries(_CommonModel[float]):
         return Series(
             data=rawdata,
             index=data.index,
-            name=(self.label, ValueType.EWMA),
+            name=(self.label, ValueType.EWMA_VOL),
+            dtype="float64",
+        )
+
+    def ewma_var_func(
+        self: Self,
+        lmbda: float = 0.94,
+        day_chunk: int = 11,
+        level: float = 0.95,
+        dlta_degr_freedms: int = 0,
+        months_from_last: int | None = None,
+        from_date: dt.date | None = None,
+        to_date: dt.date | None = None,
+        periods_in_a_year_fixed: DaysInYearType | None = None,
+    ) -> Series[float]:
+        """Exponentially Weighted Moving Average Model for Value At Risk (VaR).
+
+        Reference: https://www.investopedia.com/articles/07/ewma.asp.
+
+        Args:
+            lmbda: Scaling factor to determine weighting. Defaults to 0.94.
+            day_chunk: Sampling the data which is assumed to be daily.
+                Defaults to 11.
+            level: The sought VaR level. Defaults to 0.95.
+            dlta_degr_freedms: Variance bias factor taking the value 0 or 1.
+                Defaults to 0.
+            months_from_last: Number of months offset as positive integer.
+                Overrides use of from_date and to_date. Optional.
+            from_date: Specific from date. Optional.
+            to_date: Specific to date. Optional.
+            periods_in_a_year_fixed: Allows locking the periods-in-a-year to simplify
+                test cases and comparisons. Optional.
+
+        Returns:
+            Series EWMA VaR.
+        """
+        earlier, later = self.calc_range(
+            months_offset=months_from_last,
+            from_dt=from_date,
+            to_dt=to_date,
+        )
+        time_factor = _calculate_time_factor(
+            data=self.tsdf.loc[
+                cast("Timestamp", earlier) : cast("Timestamp", later)
+            ].iloc[:, 0],
+            earlier=earlier,
+            later=later,
+            periods_in_a_year_fixed=periods_in_a_year_fixed,
+        )
+
+        data = self.tsdf.loc[
+            cast("Timestamp", earlier) : cast("Timestamp", later)
+        ].copy()
+
+        data.loc[:, (self.label, ValueType.RTRN)] = log(
+            data.loc[:, self.tsdf.columns.to_numpy()[0]],
+        ).diff()
+
+        rawdata = [
+            data[(self.label, ValueType.RTRN)]
+            .iloc[1:day_chunk]
+            .std(ddof=dlta_degr_freedms)
+            * sqrt(time_factor),
+        ]
+
+        for item in data[(self.label, ValueType.RTRN)].iloc[1:]:
+            prev = rawdata[-1]
+            rawdata.append(
+                sqrt(
+                    square(item) * time_factor * (1 - lmbda) + square(prev) * lmbda,
+                ),
+            )
+
+        return Series(
+            data=array(rawdata) * norm.ppf(1 - level),
+            index=data.index,
+            name=(self.label, ValueType.EWMA_VAR),
             dtype="float64",
         )
 
@@ -747,6 +839,147 @@ class OpenTimeSeries(_CommonModel[float]):
             self.tsdf.columns = self.tsdf.columns.droplevel(level=1)
         return self
 
+    def _returns_series(self: Self, *, squared: bool = False) -> Series[float]:
+        """Return demeaned return series for autocorrelation analysis."""
+        data: Series[float] = self.tsdf.iloc[:, 0]
+        return _demeaned_returns_for_autocorr(
+            series=data, valuetype=self.valuetype, squared=squared
+        )
+
+    def acf(
+        self: Self,
+        lags: int | list[int],
+        *,
+        squared: bool = False,
+    ) -> Series[float]:
+        """Calculate autocorrelation function for specified lags.
+
+        Args:
+            lags: If int, compute ACF from lag 0 to this value (inclusive).
+                If list, compute ACF at lag 0 plus each lag in the list.
+            squared: If True, compute ACF of squared returns. Defaults to False.
+
+        Returns:
+            Series of autocorrelations indexed by lag.
+        """
+        rets = self._returns_series(squared=squared)
+        if isinstance(lags, int):
+            lag_list = list(range(lags + 1))
+        else:
+            lag_list = sorted({0} | set(lags))
+        values: list[float] = []
+        for lag in lag_list:
+            if lag == 0:
+                values.append(1.0)
+            else:
+                values.append(float(rets.autocorr(lag=lag)))
+        return Series(
+            data=values,
+            index=lag_list,
+            name="ACF",
+            dtype="float64",
+        )
+
+    def partial_autocorr(self: Self, lag: int = 1, *, squared: bool = False) -> float:
+        """Calculate partial autocorrelation at a given lag.
+
+        Args:
+            lag: The lag at which to compute partial autocorrelation. Defaults to 1.
+            squared: If True, compute partial autocorrelation of squared returns.
+                Defaults to False.
+
+        Returns:
+            Partial autocorrelation at the specified lag.
+        """
+        pacf_series = self.pacf(lags=lag, squared=squared)
+        return float(pacf_series.loc[lag])
+
+    def pacf(
+        self: Self,
+        lags: int | list[int],
+        *,
+        squared: bool = False,
+    ) -> Series[float]:
+        """Calculate partial autocorrelation function for specified lags.
+
+        Args:
+            lags: If int, compute PACF from lag 0 to this value (inclusive).
+                If list, compute PACF at lag 0 plus each lag in the list.
+            squared: If True, compute PACF of squared returns. Defaults to False.
+
+        Returns:
+            Series of partial autocorrelations indexed by lag.
+        """
+        if isinstance(lags, int):
+            lag_list = list(range(lags + 1))
+        else:
+            lag_list = sorted({0} | set(lags))
+        max_lag = max(lag_list) if lag_list else 0
+        acf_vals = self.acf(lags=max_lag, squared=squared)
+        acf_arr = array([acf_vals.loc[k] for k in range(max_lag + 1)])
+        pacf_values: list[float] = [1.0]
+        phi: list[list[float]] = []
+        for k in range(1, max_lag + 1):
+            if k == 1:
+                phi_kk = acf_arr[1]
+            else:
+                numer = acf_arr[k]
+                denom = 1.0
+                for j in range(k - 1):
+                    numer -= phi[k - 2][j] * acf_arr[k - 1 - j]
+                    denom -= phi[k - 2][j] * acf_arr[j + 1]
+                phi_kk = numer / denom
+            phi_row = [0.0] * k
+            for j in range(k - 1):
+                phi_row[j] = phi[k - 2][j] - phi_kk * phi[k - 2][k - 2 - j]
+            phi_row[k - 1] = phi_kk
+            phi.append(phi_row)
+            pacf_values.append(phi_kk)
+        result = {lag: pacf_values[lag] for lag in lag_list}
+        return Series(
+            data=[result[lag] for lag in lag_list],
+            index=lag_list,
+            name="PACF",
+            dtype="float64",
+        )
+
+    def ljung_box(
+        self: Self,
+        lags: int | list[int],
+        *,
+        squared: bool = False,
+    ) -> tuple[float, float, list[int]]:
+        """Compute Ljung-Box test for autocorrelation.
+
+        Args:
+            lags: If int, use lags 1 through this value. If list, use the given
+                lags (lag 0 excluded from test).
+            squared: If True, test autocorrelation of squared returns.
+                Defaults to False.
+
+        Returns:
+            Tuple of (statistic, pvalue, lags) where statistic is the Ljung-Box
+            Q statistic, pvalue is the chi-squared p-value, and lags is the
+            list of lags used.
+        """
+        rets = self._returns_series(squared=squared)
+        n = len(rets)
+        if isinstance(lags, int):
+            lag_list = list(range(1, lags + 1))
+        else:
+            lag_list = sorted({k for k in lags if k > 0})
+        if not lag_list:
+            return 0.0, 1.0, []
+        r_k_sq_sum = 0.0
+        for k in lag_list:
+            if k < n:
+                r_k = float(rets.autocorr(lag=k))
+                r_k_sq_sum += r_k**2 / (n - k)
+        q_stat = n * (n + 2) * r_k_sq_sum
+        df = len(lag_list)
+        pval = float(1.0 - chi2.cdf(q_stat, df))
+        return q_stat, pval, lag_list
+
 
 def timeseries_chain(
     front: TypeOpenTimeSeries,

{openseries-2.1.5 → openseries-2.1.7}/openseries/simulation.py

@@ -47,6 +47,35 @@ class _JumpParams(TypedDict, total=False):
     jumps_mu: float
 
 
+def _validate_ar1_coef(ar1_coef: float) -> None:
+    """Validate ar1_coef is in (-1, 1) for stationarity."""
+    if not -1.0 < ar1_coef < 1.0:
+        msg = f"ar1_coef must be in (-1, 1) for stationarity, got {ar1_coef}"
+        raise ValueError(msg)
+
+
+def _apply_ar1_filter(returns: DataFrame, ar1_coef: float) -> DataFrame:
+    """Apply AR(1) filter to returns to introduce lag-1 autocorrelation.
+
+    r_t = ar1_coef * r_{t-1} + sqrt(1 - ar1_coef**2) * innovation_t
+    Preserves mean and variance of the base process.
+
+    Args:
+        returns: DataFrame of shape (number_of_sims, trading_days).
+        ar1_coef: Lag-1 autocorrelation coefficient in (-1, 1).
+
+    Returns:
+        Filtered returns.
+    """
+    if ar1_coef == 0.0:
+        return returns
+    arr = returns.to_numpy(copy=True)
+    scale = sqrt(1.0 - ar1_coef * ar1_coef)
+    for t in range(1, arr.shape[1]):
+        arr[:, t] = ar1_coef * arr[:, t - 1] + scale * arr[:, t]
+    return DataFrame(data=arr, dtype="float64")
+
+
 def _random_generator(seed: int | None) -> Generator:
     """Make a Numpy Random Generator object.
 
@@ -183,6 +212,7 @@ class ReturnSimulation(BaseModel):
         trading_days_in_year: DaysInYearType = 252,
         seed: int | None = None,
         randomizer: Generator | None = None,
+        ar1_coef: float = 0.0,
     ) -> ReturnSimulation:
         """Create a Normal distribution simulation.
 
@@ -195,22 +225,29 @@ class ReturnSimulation(BaseModel):
                 Defaults to 252.
             seed: Seed for random process initiation.
             randomizer: Random process generator.
+            ar1_coef: Lag-1 autoregressive coefficient in (-1, 1) to induce
+                autocorrelation. Defaults to 0.0 (i.i.d. returns).
 
         Returns:
             Normal distribution simulation.
         """
+        _validate_ar1_coef(ar1_coef)
         if not randomizer:
             randomizer = _random_generator(seed=seed)
 
-        returns = randomizer.normal(
-            loc=mean_annual_return / trading_days_in_year,
-            scale=mean_annual_vol / sqrt(trading_days_in_year),
-            size=(number_of_sims, trading_days),
+        returns_df = DataFrame(
+            data=randomizer.normal(
+                loc=mean_annual_return / trading_days_in_year,
+                scale=mean_annual_vol / sqrt(trading_days_in_year),
+                size=(number_of_sims, trading_days),
+            ),
+            dtype="float64",
         )
+        returns = _apply_ar1_filter(returns_df, ar1_coef)
 
         return _create_base_simulation(
             cls=cls,
-            returns=DataFrame(data=returns, dtype="float64"),
+            returns=returns,
             number_of_sims=number_of_sims,
             trading_days=trading_days,
             trading_days_in_year=trading_days_in_year,
@@ -229,6 +266,7 @@ class ReturnSimulation(BaseModel):
         trading_days_in_year: DaysInYearType = 252,
         seed: int | None = None,
         randomizer: Generator | None = None,
+        ar1_coef: float = 0.0,
     ) -> ReturnSimulation:
         """Create a Lognormal distribution simulation.
 
@@ -241,25 +279,32 @@ class ReturnSimulation(BaseModel):
                 Defaults to 252.
             seed: Seed for random process initiation.
             randomizer: Random process generator.
+            ar1_coef: Lag-1 autoregressive coefficient in (-1, 1) to induce
+                autocorrelation. Defaults to 0.0 (i.i.d. returns).
 
         Returns:
             Lognormal distribution simulation.
         """
+        _validate_ar1_coef(ar1_coef)
         if not randomizer:
             randomizer = _random_generator(seed=seed)
 
-        returns = (
-            randomizer.lognormal(
-                mean=mean_annual_return / trading_days_in_year,
-                sigma=mean_annual_vol / sqrt(trading_days_in_year),
-                size=(number_of_sims, trading_days),
-            )
-            - 1
+        returns_df = DataFrame(
+            data=(
+                randomizer.lognormal(
+                    mean=mean_annual_return / trading_days_in_year,
+                    sigma=mean_annual_vol / sqrt(trading_days_in_year),
+                    size=(number_of_sims, trading_days),
+                )
+                - 1
+            ),
+            dtype="float64",
         )
+        returns = _apply_ar1_filter(returns_df, ar1_coef)
 
         return _create_base_simulation(
             cls=cls,
-            returns=DataFrame(data=returns, dtype="float64"),
+            returns=returns,
             number_of_sims=number_of_sims,
             trading_days=trading_days,
             trading_days_in_year=trading_days_in_year,
@@ -278,6 +323,7 @@ class ReturnSimulation(BaseModel):
         trading_days_in_year: DaysInYearType = 252,
         seed: int | None = None,
         randomizer: Generator | None = None,
+        ar1_coef: float = 0.0,
     ) -> ReturnSimulation:
         """Create a Geometric Brownian Motion simulation.
 
@@ -290,10 +336,13 @@ class ReturnSimulation(BaseModel):
                 Defaults to 252.
             seed: Seed for random process initiation.
             randomizer: Random process generator.
+            ar1_coef: Lag-1 autoregressive coefficient in (-1, 1) to induce
+                autocorrelation. Defaults to 0.0 (i.i.d. returns).
 
         Returns:
             Geometric Brownian Motion simulation.
         """
+        _validate_ar1_coef(ar1_coef)
         if not randomizer:
             randomizer = _random_generator(seed=seed)
 
@@ -308,11 +357,12 @@ class ReturnSimulation(BaseModel):
             size=(number_of_sims, trading_days),
         )
 
-        returns = drift + wiener
+        returns_df = DataFrame(data=drift + wiener, dtype="float64")
+        returns = _apply_ar1_filter(returns_df, ar1_coef)
 
         return _create_base_simulation(
             cls=cls,
-            returns=DataFrame(data=returns, dtype="float64"),
+            returns=returns,
             number_of_sims=number_of_sims,
             trading_days=trading_days,
             trading_days_in_year=trading_days_in_year,
@@ -334,6 +384,7 @@ class ReturnSimulation(BaseModel):
         trading_days_in_year: DaysInYearType = 252,
         seed: int | None = None,
         randomizer: Generator | None = None,
+        ar1_coef: float = 0.0,
     ) -> ReturnSimulation:
         """Create a Merton Jump-Diffusion model simulation.
 
@@ -350,10 +401,13 @@ class ReturnSimulation(BaseModel):
                 Defaults to 252.
             seed: Seed for random process initiation.
             randomizer: Random process generator.
+            ar1_coef: Lag-1 autoregressive coefficient in (-1, 1) to induce
+                autocorrelation. Defaults to 0.0 (i.i.d. returns).
 
         Returns:
             Merton Jump-Diffusion model simulation.
         """
+        _validate_ar1_coef(ar1_coef)
         if not randomizer:
             randomizer = _random_generator(seed=seed)
 
@@ -382,13 +436,15 @@ class ReturnSimulation(BaseModel):
             - jumps_lamda * (jumps_mu + jumps_sigma**2.0)
         ) * (1.0 / trading_days_in_year)
 
-        returns = poisson_jumps + drift + wiener
+        raw_returns = poisson_jumps + drift + wiener
+        raw_returns[:, 0] = 0.0
 
-        returns[:, 0] = 0.0
+        returns_df = DataFrame(data=raw_returns, dtype="float64")
+        returns = _apply_ar1_filter(returns_df, ar1_coef)
 
         return _create_base_simulation(
             cls=cls,
-            returns=DataFrame(data=returns, dtype="float64"),
+            returns=returns,
             number_of_sims=number_of_sims,
             trading_days=trading_days,
             trading_days_in_year=trading_days_in_year,

{openseries-2.1.5 → openseries-2.1.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "openseries"
-version = "2.1.5"
+version = "2.1.7"
 description = "Tools for analyzing financial timeseries."
 authors = [
     { name = "Martin Karrin", email = "martin.karrin@captor.se" },
@@ -50,7 +50,8 @@ dependencies = [
     "python-dateutil>=2.8.2",
     "requests>=2.20.0",
     "scipy>=1.14.1",
-    "scikit-learn>=1.4.0"
+    "scikit-learn>=1.4.0",
+    "tzdata (>=2025.3)"
 ]
 
 [project.urls]
@@ -67,7 +68,7 @@ pre-commit = ">=4.5.1"
 pytest = ">=9.0.2"
 pytest-cov = ">=7.0.0"
 pytest-xdist = ">=3.8.0"
-ruff = "0.14.10"
+ruff = "0.15.6"
 types-openpyxl = ">=3.1.2"
 scipy-stubs = ">=1.14.1.0"
 types-python-dateutil = ">=2.8.2"
@@ -80,7 +81,7 @@ sphinx-autodoc-typehints = ">=3.6.0"
 sphinx-rtd-theme = ">=3.1.0rc1"
 
 [build-system]
-requires = ["poetry-core>=2.2.1"]
+requires = ["poetry-core>=2.3.1"]
 build-backend = "poetry.core.masonry.api"
 
 [tool.setuptools.package-data]