nautilus_analysis/python/statistics/
tail_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::tail_ratio::TailRatio};
23
24#[pymethods]
25#[pyo3_stub_gen::derive::gen_stub_pymethods]
26impl TailRatio {
27    /// Calculates the tail ratio of portfolio returns.
28    ///
29    /// The tail ratio compares the magnitude of the right (gain) tail to the left
30    /// (loss) tail of the return distribution. It is the absolute ratio of the 95th
31    /// to the 5th percentile of returns:
32    ///
33    /// `TailRatio = | percentile(r, 95) / percentile(r, 5) |`
34    ///
35    /// Percentiles use linear interpolation between closest ranks, matching
36    /// `numpy.percentile` and `pandas.Series.quantile` with the default `linear`
37    /// method (the convention used by the `quantstats` tail-ratio definition).
38    ///
39    /// A value greater than `1` indicates a heavier upside tail (gains larger in
40    /// magnitude than losses); a value below `1` indicates a heavier downside tail.
41    /// Returns `NaN` for fewer than two returns or when the 5th percentile is zero.
42    ///
43    /// # References
44    ///
45    /// - empyrical `tail_ratio` (<https://github.com/quantopian/empyrical>).
46    #[new]
47    fn py_new() -> Self {
48        Self::new()
49    }
50
51    fn __repr__(&self) -> String {
52        self.name()
53    }
54
55    #[getter]
56    #[pyo3(name = "name")]
57    fn py_name(&self) -> String {
58        self.name()
59    }
60
61    #[pyo3(name = "calculate_from_returns")]
62    #[expect(clippy::needless_pass_by_value)]
63    fn py_calculate_from_returns(&mut self, raw_returns: BTreeMap<u64, f64>) -> Option<f64> {
64        self.calculate_from_returns(&transform_returns(&raw_returns))
65    }
66
67    #[pyo3(name = "calculate_from_realized_pnls")]
68    fn py_calculate_from_realized_pnls(&mut self, _realized_pnls: Vec<f64>) -> Option<f64> {
69        None
70    }
71
72    #[pyo3(name = "calculate_from_positions")]
73    fn py_calculate_from_positions(&mut self, _positions: Vec<Position>) -> Option<f64> {
74        None
75    }
76}
nautilus_analysis/python/statistics/tail_ratio.rs

nautilus_analysis/python/statistics/
tail_ratio.rs
