Add benchmark-relative portfolio statistics (#4251)

* Add benchmark-relative portfolio statistics
* Strengthen benchmark-statistic tests

Replace degenerate-input unit tests with discriminating ones for the
five benchmark-relative statistics so they fail under subtle formula
errors:

- InformationRatio/TrackingError: known-value tests with a non-zero
  benchmark so the active = r - b subtraction is exercised.
- TreynorRatio: a case with period != n and rf != 0 to catch a wrong
  annualization exponent and a missing rf annualization.
- Alpha: a non-zero-mean benchmark with a small period to exercise the
  beta * (mean_b - rf) term and the geometric annualization.
- InformationRatio: partial-overlap inner-join and intraday->daily
  compounding cases covering align_returns end-to-end.
- Non-default-period name() tests.

Also align BetaRatio.__repr__ with the other wrappers via to_string().

* Wire benchmark statistics into analyzer and tearsheet

Expose the five benchmark-relative statistics (Beta, Alpha, Information
Ratio, Tracking Error, Treynor) through the PortfolioAnalyzer and the
tearsheet so they are computed and displayed when a benchmark is given:

- analyzer.rs: add a stateless `get_performance_stats_returns_vs_benchmark`
  that iterates registered statistics and calls
  `calculate_from_returns_with_benchmark` against the primary returns and
  the caller-supplied benchmark, collecting only `Some` values. No
  benchmark field is stored; `Default`, `reset`, and `calculate_statistics`
  are untouched.
- python/analyzer.rs: register/deregister the five new class names and add
  the PyO3 getter `get_performance_stats_returns_vs_benchmark`, transforming
  the benchmark map into the returns type before delegating to Rust.
- analyzer.py: add a thin delegating getter that dispatches to the
  registered PyO3 benchmark statistics (non-benchmark stats lack the method
  and are skipped); no parallel Python math.
- tearsheet.py: when a benchmark series is present, merge the benchmark
  stats into the returns statistics shown, consistent with `stats_returns`.
- analysis/__init__.py: export the five new classes.
- nautilus_pyo3.pyi: add the five classes and the new getter to the stub.

* Compute benchmark stats from resolved tearsheet returns

* Share active-return stats between IR and tracking error

* Refine benchmark-statistic docs and add analyzer tests

Polish the benchmark-statistic stack ahead of review:

- Complete the Sharpe (1964) citation and unify doc terminology on
  "portfolio" across the five new statistics.
- Correct the trait doc for the None default and add a genuine
  zero-beta Treynor test alongside the renamed flat-benchmark case.
- Rename the unused PyO3 stub parameter to _returns, alphabetize the
  register/deregister match arms and .pyi class blocks.
- Guard the Python benchmark getter to pyo3 statistics only and build
  the dict conversions lazily; note the pd.Timestamp index requirement.
- Document benchmark-relative statistics in the tearsheet docstring.
- Add analyzer-level benchmark tests in Rust and Python.

Author: mahimn01

RELEASES.md

@@ -18,6 +18,7 @@ Released on TBD (UTC).
 - Added negative price support for `Commodity` instruments in risk checks (#2330), thanks for reporting @fabz1
 - Added `add_native_exec_algorithm` and `ExecutionAlgorithmConfig` bindings to the Python v2 backtest engine
 - Added `Order::to_order_status_report` conversion in Rust
+- Added benchmark-relative portfolio statistics (Beta, Alpha, Information Ratio, Tracking Error, Treynor Ratio) (#4251), thanks @mahimn01
 
 ### Breaking Changes
 - Changed plug-in loader to reject build mismatches by default; opt out with `set_allow_build_mismatch` (Rust)

crates/analysis/src/analyzer.rs

@@ -546,6 +546,30 @@ impl PortfolioAnalyzer {
         self.calculate_returns_stats(self.portfolio_returns())
     }
 
+    /// Gets all benchmark-relative return statistics for the primary returns.
+    ///
+    /// This is stateless: the `benchmark` series is supplied by the caller rather
+    /// than stored on the analyzer. Only statistics that override
+    /// [`PortfolioStatistic::calculate_from_returns_with_benchmark`] (the benchmark-relative
+    /// statistics) contribute values; all others return `None` and are skipped.
+    #[must_use]
+    pub fn get_performance_stats_returns_vs_benchmark(
+        &self,
+        benchmark: &Returns,
+    ) -> AHashMap<String, f64> {
+        let mut output = AHashMap::new();
+
+        for (name, stat) in &self.statistics {
+            if let Some(value) =
+                stat.calculate_from_returns_with_benchmark(self.returns(), benchmark)
+            {
+                output.insert(name.clone(), value);
+            }
+        }
+
+        output
+    }
+
     /// Gets general portfolio statistics.
     #[must_use]
     pub fn get_performance_stats_general(&self) -> AHashMap<String, f64> {
@@ -690,6 +714,7 @@ mod tests {
     use rstest::rstest;
 
     use super::*;
+    use crate::statistics::beta_ratio::BetaRatio;
 
     /// Mock implementation of `PortfolioStatistic` for testing.
     #[derive(Debug)]
@@ -1422,4 +1447,38 @@ mod tests {
         ));
         assert_eq!(returns_stats, portfolio_stats);
     }
+
+    #[rstest]
+    fn test_get_performance_stats_returns_vs_benchmark() {
+        let mut analyzer = PortfolioAnalyzer::new();
+        analyzer.register_statistic(Arc::new(BetaRatio::new()));
+        analyzer.register_statistic(Arc::new(SharpeRatio::new(None)));
+
+        let one_day = 86_400_000_000_000_u64;
+        let start = 1_600_000_000_000_000_000_u64;
+        for (i, value) in [0.03, -0.01, 0.02, 0.04].iter().enumerate() {
+            analyzer.add_return(UnixNanos::from(start + i as u64 * one_day), *value);
+        }
+
+        let mut benchmark: Returns = BTreeMap::new();
+        for (i, value) in [0.01, 0.005, 0.005, 0.01].iter().enumerate() {
+            benchmark.insert(UnixNanos::from(start + i as u64 * one_day), *value);
+        }
+
+        let stats = analyzer.get_performance_stats_returns_vs_benchmark(&benchmark);
+
+        // r = [0.03, -0.01, 0.02, 0.04], b = [0.01, 0.005, 0.005, 0.01]:
+        //   mean_r = 0.02, mean_b = 0.0075
+        //   Cov = 1.5e-4 / 3 = 5e-5, Var(b) = 2.5e-5 / 3 -> beta = 6.0
+        // Only the benchmark-relative statistic contributes; SharpeRatio
+        // returns None from the default and is skipped.
+        assert_eq!(stats.len(), 1);
+        assert!(approx_eq!(
+            f64,
+            *stats.get("Beta").unwrap(),
+            6.0,
+            epsilon = 1e-9
+        ));
+        assert!(!stats.contains_key("Sharpe Ratio (252 days)"));
+    }
 }

crates/analysis/src/python/analyzer.rs

@@ -13,7 +13,10 @@
 //  limitations under the License.
 // -------------------------------------------------------------------------------------------------
 
-use std::{collections::HashMap, sync::Arc};
+use std::{
+    collections::{BTreeMap, HashMap},
+    sync::Arc,
+};
 
 use nautilus_core::{UnixNanos, python::to_pyvalue_err};
 use nautilus_model::{
@@ -24,13 +27,16 @@ use nautilus_model::{
 use pyo3::prelude::*;
 
 use crate::{
+    Returns,
     analyzer::{PortfolioAnalyzer, Statistic},
     statistics::{
-        expectancy::Expectancy, long_ratio::LongRatio, loser_avg::AvgLoser, loser_max::MaxLoser,
-        loser_min::MinLoser, profit_factor::ProfitFactor, returns_avg::ReturnsAverage,
-        returns_avg_loss::ReturnsAverageLoss, returns_avg_win::ReturnsAverageWin,
-        returns_volatility::ReturnsVolatility, risk_return_ratio::RiskReturnRatio,
-        sharpe_ratio::SharpeRatio, sortino_ratio::SortinoRatio, win_rate::WinRate,
+        alpha::Alpha, beta_ratio::BetaRatio, expectancy::Expectancy,
+        information_ratio::InformationRatio, long_ratio::LongRatio, loser_avg::AvgLoser,
+        loser_max::MaxLoser, loser_min::MinLoser, profit_factor::ProfitFactor,
+        returns_avg::ReturnsAverage, returns_avg_loss::ReturnsAverageLoss,
+        returns_avg_win::ReturnsAverageWin, returns_volatility::ReturnsVolatility,
+        risk_return_ratio::RiskReturnRatio, sharpe_ratio::SharpeRatio, sortino_ratio::SortinoRatio,
+        tracking_error::TrackingError, treynor_ratio::TreynorRatio, win_rate::WinRate,
         winner_avg::AvgWinner, winner_max::MaxWinner, winner_min::MinWinner,
     },
 };
@@ -81,6 +87,21 @@ impl PortfolioAnalyzer {
             .collect()
     }
 
+    /// Gets all benchmark-relative return statistics for the primary returns.
+    #[pyo3(name = "get_performance_stats_returns_vs_benchmark")]
+    fn py_get_performance_stats_returns_vs_benchmark(
+        &self,
+        benchmark: BTreeMap<u64, f64>,
+    ) -> HashMap<String, f64> {
+        let benchmark: Returns = benchmark
+            .into_iter()
+            .map(|(k, v)| (UnixNanos::from(k), v))
+            .collect();
+        self.get_performance_stats_returns_vs_benchmark(&benchmark)
+            .into_iter()
+            .collect()
+    }
+
     #[pyo3(name = "get_performance_stats_pnls")]
     fn py_get_performance_stats_pnls(
         &self,
@@ -196,6 +217,26 @@ impl PortfolioAnalyzer {
                 let stat = statistic.extract::<LongRatio>(py)?;
                 self.register_statistic(Arc::new(stat));
             }
+            "Alpha" => {
+                let stat = statistic.extract::<Alpha>(py)?;
+                self.register_statistic(Arc::new(stat));
+            }
+            "BetaRatio" => {
+                let stat = statistic.extract::<BetaRatio>(py)?;
+                self.register_statistic(Arc::new(stat));
+            }
+            "InformationRatio" => {
+                let stat = statistic.extract::<InformationRatio>(py)?;
+                self.register_statistic(Arc::new(stat));
+            }
+            "TrackingError" => {
+                let stat = statistic.extract::<TrackingError>(py)?;
+                self.register_statistic(Arc::new(stat));
+            }
+            "TreynorRatio" => {
+                let stat = statistic.extract::<TreynorRatio>(py)?;
+                self.register_statistic(Arc::new(stat));
+            }
             _ => {
                 return Err(to_pyvalue_err(format!(
                     "Unknown statistic type: {type_name}"
@@ -284,6 +325,26 @@ impl PortfolioAnalyzer {
                 let stat = statistic.extract::<LongRatio>(py)?;
                 self.deregister_statistic(&(Arc::new(stat) as Statistic));
             }
+            "Alpha" => {
+                let stat = statistic.extract::<Alpha>(py)?;
+                self.deregister_statistic(&(Arc::new(stat) as Statistic));
+            }
+            "BetaRatio" => {
+                let stat = statistic.extract::<BetaRatio>(py)?;
+                self.deregister_statistic(&(Arc::new(stat) as Statistic));
+            }
+            "InformationRatio" => {
+                let stat = statistic.extract::<InformationRatio>(py)?;
+                self.deregister_statistic(&(Arc::new(stat) as Statistic));
+            }
+            "TrackingError" => {
+                let stat = statistic.extract::<TrackingError>(py)?;
+                self.deregister_statistic(&(Arc::new(stat) as Statistic));
+            }
+            "TreynorRatio" => {
+                let stat = statistic.extract::<TreynorRatio>(py)?;
+                self.deregister_statistic(&(Arc::new(stat) as Statistic));
+            }
             _ => {
                 return Err(to_pyvalue_err(format!(
                     "Unknown statistic type: {type_name}"

crates/analysis/src/python/mod.rs

@@ -62,5 +62,12 @@ pub fn analysis(_: Python<'_>, m: &Bound<'_, PyModule>) -> PyResult<()> {
     // Statistics - Position-based
     m.add_class::<crate::statistics::long_ratio::LongRatio>()?;
 
+    // Statistics - Benchmark-relative
+    m.add_class::<crate::statistics::alpha::Alpha>()?;
+    m.add_class::<crate::statistics::beta_ratio::BetaRatio>()?;
+    m.add_class::<crate::statistics::information_ratio::InformationRatio>()?;
+    m.add_class::<crate::statistics::tracking_error::TrackingError>()?;
+    m.add_class::<crate::statistics::treynor_ratio::TreynorRatio>()?;
+
     Ok(())
 }

crates/analysis/src/python/statistics/alpha.rs

@@ -0,0 +1,74 @@
+// -------------------------------------------------------------------------------------------------
+//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
+//  https://nautechsystems.io
+//
+//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
+//  You may not use this file except in compliance with the License.
+//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
+//
+//  Unless required by applicable law or agreed to in writing, software
+//  distributed under the License is distributed on an "AS IS" BASIS,
+//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+//  See the License for the specific language governing permissions and
+//  limitations under the License.
+// -------------------------------------------------------------------------------------------------
+
+use std::collections::BTreeMap;
+
+use pyo3::prelude::*;
+
+use super::transform_returns;
+use crate::{statistic::PortfolioStatistic, statistics::alpha::Alpha};
+
+#[pymethods]
+#[pyo3_stub_gen::derive::gen_stub_pymethods]
+impl Alpha {
+    /// Calculates Jensen's alpha of portfolio returns relative to a benchmark.
+    ///
+    /// `alpha = (mean_strategy - rf) - beta * (mean_benchmark - rf)` per period, then
+    /// annualized geometrically over `period` (default 252). The risk-free rate `rf`
+    /// is per period (default 0.0).
+    #[new]
+    #[pyo3(signature = (period=None, risk_free_rate=None))]
+    fn py_new(period: Option<usize>, risk_free_rate: Option<f64>) -> Self {
+        Self::new(period, risk_free_rate)
+    }
+
+    fn __repr__(&self) -> String {
+        self.to_string()
+    }
+
+    #[getter]
+    #[pyo3(name = "name")]
+    fn py_name(&self) -> String {
+        self.name()
+    }
+
+    #[pyo3(name = "calculate_from_returns")]
+    fn py_calculate_from_returns(&self, _returns: BTreeMap<u64, f64>) -> Option<f64> {
+        None
+    }
+
+    #[pyo3(name = "calculate_from_realized_pnls")]
+    fn py_calculate_from_realized_pnls(&self, _realized_pnls: Vec<f64>) -> Option<f64> {
+        None
+    }
+
+    #[pyo3(name = "calculate_from_positions")]
+    fn py_calculate_from_positions(&self, _positions: Vec<Py<PyAny>>) -> Option<f64> {
+        None
+    }
+
+    #[pyo3(name = "calculate_from_returns_with_benchmark")]
+    #[expect(clippy::needless_pass_by_value)]
+    fn py_calculate_from_returns_with_benchmark(
+        &self,
+        returns: BTreeMap<u64, f64>,
+        benchmark: BTreeMap<u64, f64>,
+    ) -> Option<f64> {
+        self.calculate_from_returns_with_benchmark(
+            &transform_returns(&returns),
+            &transform_returns(&benchmark),
+        )
+    }
+}

crates/analysis/src/python/statistics/beta_ratio.rs

@@ -0,0 +1,73 @@
+// -------------------------------------------------------------------------------------------------
+//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
+//  https://nautechsystems.io
+//
+//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
+//  You may not use this file except in compliance with the License.
+//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
+//
+//  Unless required by applicable law or agreed to in writing, software
+//  distributed under the License is distributed on an "AS IS" BASIS,
+//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+//  See the License for the specific language governing permissions and
+//  limitations under the License.
+// -------------------------------------------------------------------------------------------------
+
+use std::collections::BTreeMap;
+
+use pyo3::prelude::*;
+
+use super::transform_returns;
+use crate::{statistic::PortfolioStatistic, statistics::beta_ratio::BetaRatio};
+
+#[pymethods]
+#[pyo3_stub_gen::derive::gen_stub_pymethods]
+impl BetaRatio {
+    /// Calculates the beta of portfolio returns relative to a benchmark.
+    ///
+    /// Beta measures the systematic risk (market sensitivity) of a portfolio:
+    /// `Beta = Cov(strategy, benchmark) / Var(benchmark)` using sample (`ddof = 1`)
+    /// covariance and variance. Beta is not annualized.
+    #[new]
+    fn py_new() -> Self {
+        Self::new()
+    }
+
+    fn __repr__(&self) -> String {
+        self.to_string()
+    }
+
+    #[getter]
+    #[pyo3(name = "name")]
+    fn py_name(&self) -> String {
+        self.name()
+    }
+
+    #[pyo3(name = "calculate_from_returns")]
+    fn py_calculate_from_returns(&self, _returns: BTreeMap<u64, f64>) -> Option<f64> {
+        None
+    }
+
+    #[pyo3(name = "calculate_from_realized_pnls")]
+    fn py_calculate_from_realized_pnls(&self, _realized_pnls: Vec<f64>) -> Option<f64> {
+        None
+    }
+
+    #[pyo3(name = "calculate_from_positions")]
+    fn py_calculate_from_positions(&self, _positions: Vec<Py<PyAny>>) -> Option<f64> {
+        None
+    }
+
+    #[pyo3(name = "calculate_from_returns_with_benchmark")]
+    #[expect(clippy::needless_pass_by_value)]
+    fn py_calculate_from_returns_with_benchmark(
+        &self,
+        returns: BTreeMap<u64, f64>,
+        benchmark: BTreeMap<u64, f64>,
+    ) -> Option<f64> {
+        self.calculate_from_returns_with_benchmark(
+            &transform_returns(&returns),
+            &transform_returns(&benchmark),
+        )
+    }
+}