feat!: tracking error is the standard deviation of return differences (#97)

BREAKING CHANGE: `tracking_error()` returns different values and no longer
accepts a `method` argument.

`okama` implemented two formulas behind `method`, and the default was the
uncentered root-mean-square of the monthly return differences. That quantity is
not the tracking error: leaving the differences uncentered folds the systematic
lag behind the benchmark — the tracking difference — into the dispersion
measure, so a fund that trails by a steady amount every month is reported as
badly tracking even when the gap never moves.

Tracking error is the sample standard deviation of the differences around their
mean (CFA Level II, 2019, V6, eq. 8; CFA Level I, 2025, V9 Portfolio Management,
footnote 3), which is what all three entry points now compute — and the only
thing they compute:

    helpers.Index.tracking_error(ror)
    AssetList.tracking_error(rolling_window=None)
    Portfolio.tracking_error(benchmark, rolling_window=None)

The relation between the two is exact: TE_rms² = (N-1)/N · TE_std² + mean(d)²,
so the RMS variant is not a different estimator of the same thing but a mixture
of two measures the curriculum deliberately keeps apart. It is removed rather
than kept as an option — callers who passed `method="std"` keep their numbers by
dropping the argument.

Docstrings now state the formula, the relation to tracking difference and the
CFA reference. `pyproject.toml` is deliberately left at 2.3.1: the version bump
belongs to the release workflow.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VUmxQQKrKZRAi1qKUternL

Author: chilango74

CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- **Breaking.** `tracking_error()` now returns the sample standard deviation of the
+  return differences around their mean (Bessel's correction), annualized by
+  `sqrt(12)` — the tracking error as defined by the CFA curriculum (CFA Level II,
+  2019, V6, eq. 8; CFA Level I, 2025, V9 Portfolio Management, footnote 3). The
+  previous default was the uncentered root-mean-square of the differences, which
+  folded the systematic lag behind the benchmark (the tracking difference) into the
+  result: `TE_rms² = (N-1)/N · TE_std² + mean(d)²`. The same symbols over the same
+  period therefore return a different number than in 2.3.1 and earlier — usually
+  lower, since the lag term drops out, though marginally higher for a fund whose lag
+  is smaller than `TE_std / sqrt(N)`, where the uncentered formula's division by `N`
+  instead of `N-1` dominates. Affects `helpers.Index.tracking_error`,
+  `AssetList.tracking_error` and `Portfolio.tracking_error` (#97).
+
+### Removed
+
+- **Breaking.** The `method` parameter of `helpers.Index.tracking_error`,
+  `AssetList.tracking_error` and `Portfolio.tracking_error`. Tracking error now has a
+  single definition, so `method="rms"` and `method="std"` (both added in 2.2.2) are
+  gone — passing `method=` raises `TypeError`. Code that asked for `method="std"`
+  keeps its values by simply dropping the argument; code that relied on the `"rms"`
+  values has to compute them itself, as the mixture of tracking difference and
+  tracking error that it is.
+
 ### Fixed
 
 - `Portfolio.assets_weights` (the symbol → weight mapping) was built once in the

okama/asset_list.py

@@ -1,7 +1,4 @@
-from typing import Literal  # noqa: I001
-from functools import partial
-
-import numpy as np
+import numpy as np  # noqa: I001
 import pandas as pd
 
 from okama.common.helpers.helpers import check_rolling_window
@@ -1397,40 +1394,29 @@ def tracking_difference_annual(self) -> pd.DataFrame:
         result.index = result.index.asfreq("Y")
         return result
 
-    def tracking_error(
-        self,
-        rolling_window: int | None = None,
-        method: Literal["rms", "std"] = "rms",
-    ) -> pd.DataFrame:
+    def tracking_error(self, rolling_window: int | None = None) -> pd.DataFrame:
         """
         Calculate tracking error time series for the rate of return of assets.
 
-        Tracking error is an ex-post measure of how closely the assets follow the benchmark.
-        It is computed from the realized monthly return differences between each asset and
-        the benchmark, and is annualized (multiplied by sqrt(12)). Tracking error values
+        Tracking error is an ex-post measure of how closely the assets follow the benchmark:
+        the sample standard deviation of the realized monthly return differences between
+        each asset and the benchmark, taken around their mean and corrected for bias
+        (Bessel's correction), annualized by multiplying by sqrt(12). Tracking error values
         are decimal fractions: 0.05 corresponds to 5% annualized.
 
         Benchmark should be in the first position of the symbols list in AssetList parameters.
 
-        Two formulas are available (`method` parameter):
-
-        - "rms" (default): root-mean-square of the return differences. The differences are
-          not centered around their mean, hence the systematic lag between an asset and
-          the benchmark (tracking difference) is included in the result.
-        - "std": sample standard deviation of the return differences with Bessel's
-          correction — the classic tracking error definition (Hwang & Satchell,
-          "Tracking Error: Ex-Ante versus Ex-Post Measures", 2001, eq. 2) measuring
-          the pure volatility of deviations from the benchmark. The first point of the
-          expanding time series is dropped (a single observation has no standard deviation).
+        Because the differences are centered, a systematic lag behind the benchmark does not
+        inflate the result: how far an asset falls behind is measured by
+        `tracking_difference`, how unstable that gap is — by tracking error (CFA Level II,
+        2019, V6, eq. 8). The first point of the expanding time series is dropped (a single
+        observation has no standard deviation).
 
         Parameters
         ----------
         rolling_window : int or None, default None
             Size of the moving window in months. Must be at least 12 months.
             If None calculate expanding tracking error.
-        method : {"rms", "std"}, default "rms"
-            Tracking error formula: "rms" for the uncentered root-mean-square of return
-            differences, "std" for the centered sample standard deviation.
 
         Returns
         -------
@@ -1447,18 +1433,18 @@ def tracking_error(
 
         To calculate rolling tracking error set `rolling_window` to a number of months (moving window size):
 
-        >>> x.tracking_error(rolling_window=12 * 5, method="std").plot()
+        >>> x.tracking_error(rolling_window=12 * 5).plot()
         >>> plt.show()
         """
         if rolling_window:
             return helpers.Index.rolling_fn(
                 df=self.assets_ror,
                 window=rolling_window,
-                fn=partial(helpers.Index.tracking_error, method=method),
+                fn=helpers.Index.tracking_error,
                 window_below_year=False,  # small windows below 12 months are not allowed
             )
         else:
-            return helpers.Index.tracking_error(self.assets_ror, method=method)
+            return helpers.Index.tracking_error(self.assets_ror)
 
     def index_corr(self, rolling_window: int | None = None) -> pd.DataFrame:
         """

okama/common/helpers/helpers.py

@@ -656,25 +656,23 @@ def tracking_difference_annualized(tracking_diff: pd.DataFrame) -> pd.DataFrame:
         return diff.iloc[settings._MONTHS_PER_YEAR - 1 :]  # returns for the first 11 months can't be annualized
 
     @staticmethod
-    def tracking_error(ror: pd.DataFrame, method: str = "rms") -> pd.DataFrame:
+    def tracking_error(ror: pd.DataFrame) -> pd.DataFrame:
         """
         Return expanding tracking error time series for a rate of return time series.
 
         Assets are compared with the index or another benchmark.
         Index should be in the first position (first column).
 
         Tracking error is an ex-post measure: it is computed from the realized (historical)
-        monthly return differences `d` between each asset and the benchmark.
-        Two formulas are available:
-
-        - "rms" (default): expanding root-mean-square of the differences, sqrt(mean(d²)).
-          The differences are not centered around their mean, hence the systematic lag
-          between an asset and the benchmark (tracking difference) is included in the result.
-        - "std": expanding sample standard deviation of the differences with Bessel's
-          correction, sqrt(sum((d - mean(d))²) / (n - 1)) — the classic tracking error
-          definition (Hwang & Satchell, "Tracking Error: Ex-Ante versus Ex-Post Measures",
-          2001, eq. 2) measuring the pure volatility of deviations. The first expanding
-          point is dropped (a single observation has no standard deviation).
+        monthly return differences `d` between each asset and the benchmark as the expanding
+        sample standard deviation of those differences with Bessel's correction,
+        sqrt(sum((d - mean(d))²) / (n - 1)).
+
+        The differences are centered around their mean, so a systematic lag behind the
+        benchmark does not inflate the result: how far an asset falls behind is tracking
+        difference (`Index.tracking_difference`), how unstable that gap is, is tracking
+        error (CFA Level II, 2019, V6, eq. 8). The first expanding point is dropped
+        (a single observation has no standard deviation).
 
         The result is annualized for monthly time series (multiplied by sqrt(12)).
         """
@@ -684,14 +682,8 @@ def tracking_error(ror: pd.DataFrame, method: str = "rms") -> pd.DataFrame:
             raise ShortPeriodLengthError("Tracking Error is not defined for time periods < 1 year")
         difference = ror.subtract(ror.iloc[:, 0], axis=0)
         difference = difference.drop(difference.columns[0], axis=1)  # drop the first column (stock index data)
-        if method == "rms":
-            cumsum = difference.pow(2, axis=0).cumsum()
-            tracking_error = cumsum.divide((1.0 + np.arange(ror.shape[0])), axis=0).pow(0.5, axis=0)
-        elif method == "std":
-            tracking_error = difference.expanding().std().dropna(how="all")
-        else:
-            raise ValueError(f"method must be 'rms' or 'std', got '{method}'.")
-        return tracking_error * np.sqrt(12)
+        tracking_error = difference.expanding().std().dropna(how="all")
+        return tracking_error * np.sqrt(settings._MONTHS_PER_YEAR)
 
     @staticmethod
     def expanding_cov_cor(ror: pd.DataFrame, fn: str) -> pd.DataFrame:

okama/portfolios/core.py

@@ -1661,26 +1661,21 @@ def tracking_error(
         self,
         benchmark: str | type,
         rolling_window: int | None = None,
-        method: Literal["rms", "std"] = "rms",
     ) -> pd.Series:
         """
         Calculate ex-post tracking error time series of the portfolio against a benchmark.
 
         Tracking error is an ex-post (backward-looking) measure of how closely the portfolio
-        follows the benchmark. It is computed from the realized monthly return differences
-        between the portfolio and the benchmark, and is annualized (multiplied by sqrt(12)).
+        follows the benchmark: the sample standard deviation of the realized monthly return
+        differences between the portfolio and the benchmark, taken around their mean and
+        corrected for bias (Bessel's correction), annualized by multiplying by sqrt(12).
         Tracking error values are decimal fractions: 0.05 corresponds to 5% annualized.
 
-        Two formulas are available (`method` parameter):
-
-        - "rms" (default): root-mean-square of the return differences. The differences are
-          not centered around their mean, hence the systematic lag between the portfolio
-          and the benchmark (tracking difference) is included in the result.
-        - "std": sample standard deviation of the return differences with Bessel's
-          correction — the classic tracking error definition (Hwang & Satchell,
-          "Tracking Error: Ex-Ante versus Ex-Post Measures", 2001, eq. 2) measuring
-          the pure volatility of deviations from the benchmark. The first point of the
-          expanding time series is dropped (a single observation has no standard deviation).
+        Because the differences are centered, a systematic lag behind the benchmark does not
+        inflate the result: how far the portfolio falls behind is measured by tracking
+        difference, how unstable that gap is — by tracking error (CFA Level II, 2019, V6,
+        eq. 8). The first point of the expanding time series is dropped (a single
+        observation has no standard deviation).
 
         The benchmark rate of return is converted to the portfolio base currency, and the
         time period is limited to the intersection of the portfolio and benchmark
@@ -1694,9 +1689,6 @@ def tracking_error(
         rolling_window : int or None, default None
             Size of the moving window in months. Must be at least 12 months.
             If None calculate expanding tracking error.
-        method : {"rms", "std"}, default "rms"
-            Tracking error formula: "rms" for the uncentered root-mean-square of return
-            differences, "std" for the centered sample standard deviation.
 
         Returns
         -------
@@ -1714,11 +1706,11 @@ def tracking_error(
 
         To calculate rolling tracking error set `rolling_window` to a number of months (moving window size):
 
-        >>> pf.tracking_error(benchmark="SP500TR.INDX", rolling_window=24, method="std").plot()
+        >>> pf.tracking_error(benchmark="SP500TR.INDX", rolling_window=24).plot()
         >>> plt.show()
         """
         al = AssetList([benchmark, self], ccy=self.currency, inflation=False)
-        tracking_error = al.tracking_error(rolling_window=rolling_window, method=method)
+        tracking_error = al.tracking_error(rolling_window=rolling_window)
         return tracking_error[self.symbol]
 
     @property

tests/asset_list/test_asset_list.py

@@ -381,33 +381,29 @@ def test_tracking_difference_annualized_and_annual(synthetic_env2):
     assert tdan.shape[0] >= 1
 
 
-def test_tracking_error_std_method(synthetic_env):
-    """method='std' returns the centered sample std (ddof=1) of return differences, annualized."""
+def test_tracking_error_is_centered_sample_std(synthetic_env):
+    """Tracking error is the centered sample std (ddof=1) of return differences, annualized."""
     al = ok.AssetList(["IDX.US", "A.US", "B.US"], ccy="USD", inflation=False)
-    te = al.tracking_error(method="std")
+    te = al.tracking_error()
     assert isinstance(te, pd.DataFrame)
     assert list(te.columns) == ["A.US", "B.US"]
     d = al.assets_ror["A.US"] - al.assets_ror["IDX.US"]
     assert te["A.US"].iloc[-1] == pytest.approx(d.std(ddof=1) * np.sqrt(12))
-    # The first expanding point is dropped for the std method
+    # The first expanding point is dropped (a single observation has no standard deviation)
     assert len(te) == len(al.assets_ror) - 1
 
 
-def test_tracking_error_rms_default_unchanged(synthetic_env):
-    """Calling without arguments equals method='rms' and reproduces the legacy formula."""
+def test_tracking_error_does_not_accept_a_method_argument(synthetic_env):
+    """The `method` switch is gone: tracking error has a single definition."""
     al = ok.AssetList(["IDX.US", "A.US", "B.US"], ccy="USD", inflation=False)
-    d = al.assets_ror["A.US"] - al.assets_ror["IDX.US"]
-    expected_last = np.sqrt((d**2).sum() / len(d)) * np.sqrt(12)
-    te_default = al.tracking_error()
-    te_rms = al.tracking_error(method="rms")
-    pd.testing.assert_frame_equal(te_default, te_rms)
-    assert te_default["A.US"].iloc[-1] == pytest.approx(expected_last)
+    with pytest.raises(TypeError):
+        al.tracking_error(method="rms")
 
 
-def test_tracking_error_rolling_with_std_method(synthetic_env):
-    """Rolling tracking error supports method='std' (window >= 12 months)."""
+def test_tracking_error_rolling(synthetic_env):
+    """Rolling tracking error requires a window of at least 12 months."""
     al = ok.AssetList(["IDX.US", "A.US", "B.US"], ccy="USD", inflation=False)
-    te = al.tracking_error(rolling_window=12, method="std")
+    te = al.tracking_error(rolling_window=12)
     assert isinstance(te, pd.DataFrame)
     assert list(te.columns) == ["A.US", "B.US"]
     assert len(te) > 0

tests/portfolio/test_portfolio.py

@@ -415,12 +415,12 @@ def test_tracking_error_matches_asset_list_workaround(pf_ab_monthly):
     pd.testing.assert_series_equal(te, expected)
 
 
-def test_tracking_error_std_matches_manual_computation(pf_ab_monthly, synthetic_env):
-    """method='std' equals the centered std (ddof=1) of portfolio-vs-benchmark differences."""
-    te = pf_ab_monthly.tracking_error(benchmark="IDX.US", method="std")
+def test_tracking_error_matches_manual_computation(pf_ab_monthly, synthetic_env):
+    """Tracking error equals the centered std (ddof=1) of portfolio-vs-benchmark differences."""
+    te = pf_ab_monthly.tracking_error(benchmark="IDX.US")
     diff = pf_ab_monthly.ror - synthetic_env["series"]["IDX.US"]
     assert te.iloc[-1] == pytest.approx(diff.std(ddof=1) * np.sqrt(12))
-    # The first expanding point is dropped for the std method
+    # The first expanding point is dropped (a single observation has no standard deviation)
     assert len(te) == len(diff) - 1
 
 
@@ -448,13 +448,14 @@ def test_tracking_error_with_portfolio_benchmark(pf_ab_monthly, synthetic_env):
     assert isinstance(te, pd.Series)
     assert te.name == pf_ab_monthly.symbol
     diff = pf_ab_monthly.ror - bench_pf.ror
-    expected_last = np.sqrt((diff**2).sum() / len(diff)) * np.sqrt(12)
+    expected_last = diff.std(ddof=1) * np.sqrt(12)
     assert te.iloc[-1] == pytest.approx(expected_last)
 
 
-def test_tracking_error_invalid_method_raises(pf_ab_monthly):
-    with pytest.raises(ValueError, match="method"):
-        pf_ab_monthly.tracking_error(benchmark="IDX.US", method="mad")
+def test_tracking_error_does_not_accept_a_method_argument(pf_ab_monthly):
+    """The `method` switch is gone: tracking error has a single definition."""
+    with pytest.raises(TypeError):
+        pf_ab_monthly.tracking_error(benchmark="IDX.US", method="rms")
 
 
 def test_table_adds_local_name_when_present(synthetic_env):