openseries 2.1.6__tar.gz → 2.1.7__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openseries
-Version: 2.1.6
+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

{openseries-2.1.6 → 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,
@@ -354,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.
@@ -824,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
 
@@ -1482,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.6 → 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.6 → openseries-2.1.7}/openseries/owntypes.py

@@ -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",

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

@@ -32,9 +32,13 @@ from pandas import (
     date_range,
 )
 from pydantic import field_validator, model_validator
-from scipy.stats import norm
+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,
@@ -416,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
 
@@ -824,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.6 → 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.6 → openseries-2.1.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "openseries"
-version = "2.1.6"
+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.15.0"
+ruff = "0.15.6"
 types-openpyxl = ">=3.1.2"
 scipy-stubs = ">=1.14.1.0"
 types-python-dateutil = ">=2.8.2"