nautilus_analysis/python/statistics/
up_capture_ratio.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16use std::collections::BTreeMap;
17
18use nautilus_model::position::Position;
19use pyo3::prelude::*;
20
21use super::transform_returns;
22use crate::{statistic::PortfolioStatistic, statistics::up_capture_ratio::UpCaptureRatio};
23
24#[pymethods]
25#[pyo3_stub_gen::derive::gen_stub_pymethods]
26impl UpCaptureRatio {
27    /// Calculates the up capture ratio of portfolio returns relative to a benchmark.
28    ///
29    /// The up capture ratio measures how the portfolio performed, on average, during the
30    /// periods when the benchmark return was positive. It is the ratio of the portfolio's
31    /// geometric annualized return to the benchmark's geometric annualized return, both
32    /// computed over the up-market subset only:
33    ///
34    /// `UpCapture = annualized_return(portfolio | benchmark > 0) / annualized_return(benchmark | benchmark > 0)`
35    ///
36    /// where each side's annualized return is the geometric (CAGR-style) value
37    /// `(prod(1 + x_i))^(period / m) - 1` and `m` is the number of up-market periods (the
38    /// size of the filtered subset, not the full aligned length). The period defaults to
39    /// 252 trading days. A value above 1.0 means the portfolio outperformed the benchmark
40    /// in up markets.
41    ///
42    /// This is the `empyrical.up_capture` convention (geometric annualized-return ratio over
43    /// the `benchmark > 0` subset). Note that this differs from the Morningstar definition,
44    /// which uses a ratio of *cumulative* (non-annualized) returns; the two coincide only
45    /// when both subsets contain the same number of periods.
46    ///
47    /// # References
48    ///
49    /// - empyrical `up_capture` / `capture` / `annual_return`
50    ///   (<https://github.com/quantopian/empyrical>).
51    /// - CFA Institute Investment Foundations, 3rd Edition
52    #[new]
53    #[pyo3(signature = (period=None))]
54    fn py_new(period: Option<usize>) -> Self {
55        Self::new(period)
56    }
57
58    fn __repr__(&self) -> String {
59        self.to_string()
60    }
61
62    #[getter]
63    #[pyo3(name = "name")]
64    fn py_name(&self) -> String {
65        self.name()
66    }
67
68    #[pyo3(name = "calculate_from_returns")]
69    fn py_calculate_from_returns(&self, _returns: BTreeMap<u64, f64>) -> Option<f64> {
70        None
71    }
72
73    #[pyo3(name = "calculate_from_realized_pnls")]
74    fn py_calculate_from_realized_pnls(&self, _realized_pnls: Vec<f64>) -> Option<f64> {
75        None
76    }
77
78    #[pyo3(name = "calculate_from_positions")]
79    fn py_calculate_from_positions(&self, _positions: Vec<Position>) -> Option<f64> {
80        None
81    }
82
83    #[pyo3(name = "calculate_from_returns_with_benchmark")]
84    #[expect(clippy::needless_pass_by_value)]
85    fn py_calculate_from_returns_with_benchmark(
86        &self,
87        returns: BTreeMap<u64, f64>,
88        benchmark: BTreeMap<u64, f64>,
89    ) -> Option<f64> {
90        self.calculate_from_returns_with_benchmark(
91            &transform_returns(&returns),
92            &transform_returns(&benchmark),
93        )
94    }
95}
nautilus_analysis/python/statistics/up_capture_ratio.rs

nautilus_analysis/python/statistics/
up_capture_ratio.rs
