nautilus_analysis/statistics/
returns_volatility.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::fmt::Display;
17
18use nautilus_model::position::Position;
19
20use crate::{Returns, statistic::PortfolioStatistic};
21
22/// Calculates the annualized volatility (standard deviation) of portfolio returns.
23///
24/// Volatility is calculated as the standard deviation of returns, annualized by
25/// multiplying the daily standard deviation by the square root of the period:
26/// `Standard Deviation * sqrt(period)`
27///
28/// Uses Bessel's correction (ddof=1) for sample standard deviation.
29/// This provides a measure of the portfolio's risk or uncertainty of returns.
30///
31/// # References
32///
33/// - CFA Institute Level I Curriculum: Quantitative Methods
34/// - Hull, J. C. (2018). *Options, Futures, and Other Derivatives* (10th ed.). Pearson.
35/// - Fabozzi, F. J., et al. (2002). *The Handbook of Financial Instruments*. Wiley.
36#[repr(C)]
37#[derive(Debug, Clone)]
38#[cfg_attr(
39    feature = "python",
40    pyo3::pyclass(module = "nautilus_trader.core.nautilus_pyo3.analysis", from_py_object)
41)]
42#[cfg_attr(
43    feature = "python",
44    pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.analysis")
45)]
46pub struct ReturnsVolatility {
47    /// The annualization period (default: 252 for daily data).
48    period: usize,
49}
50
51impl ReturnsVolatility {
52    /// Creates a new [`ReturnsVolatility`] instance.
53    #[must_use]
54    pub fn new(period: Option<usize>) -> Self {
55        Self {
56            period: period.unwrap_or(252),
57        }
58    }
59}
60
61impl Display for ReturnsVolatility {
62    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
63        write!(f, "Returns Volatility ({} days)", self.period)
64    }
65}
66
67impl PortfolioStatistic for ReturnsVolatility {
68    type Item = f64;
69
70    fn name(&self) -> String {
71        self.to_string()
72    }
73
74    fn calculate_from_returns(&self, raw_returns: &Returns) -> Option<Self::Item> {
75        if !self.check_valid_returns(raw_returns) {
76            return Some(f64::NAN);
77        }
78
79        let returns = self.downsample_to_daily_bins(raw_returns);
80        let daily_std = self.calculate_std(&returns);
81        let annualized_std = daily_std * (self.period as f64).sqrt();
82        Some(annualized_std)
83    }
84    fn calculate_from_realized_pnls(&self, _realized_pnls: &[f64]) -> Option<Self::Item> {
85        None
86    }
87
88    fn calculate_from_positions(&self, _positions: &[Position]) -> Option<Self::Item> {
89        None
90    }
91}
92
93#[cfg(test)]
94mod tests {
95    use std::collections::BTreeMap;
96
97    use nautilus_core::{UnixNanos, approx_eq};
98    use rstest::rstest;
99
100    use super::*;
101
102    fn create_returns(values: &[f64]) -> BTreeMap<UnixNanos, f64> {
103        let mut new_return = BTreeMap::new();
104        let one_day_in_nanos = 86_400_000_000_000;
105        let start_time = 1_600_000_000_000_000_000;
106
107        for (i, &value) in values.iter().enumerate() {
108            let timestamp = start_time + i as u64 * one_day_in_nanos;
109            new_return.insert(UnixNanos::from(timestamp), value);
110        }
111
112        new_return
113    }
114
115    #[rstest]
116    fn test_empty_returns() {
117        let volatility = ReturnsVolatility::new(None);
118        let returns = create_returns(&[]);
119        let result = volatility.calculate_from_returns(&returns);
120        assert!(result.is_some());
121        assert!(result.unwrap().is_nan());
122    }
123
124    #[rstest]
125    fn test_default_period() {
126        let volatility = ReturnsVolatility::new(None);
127        assert_eq!(volatility.period, 252);
128    }
129
130    #[rstest]
131    fn test_custom_period() {
132        let volatility = ReturnsVolatility::new(Some(365));
133        assert_eq!(volatility.period, 365);
134    }
135
136    #[rstest]
137    fn test_volatility_calculation() {
138        let volatility = ReturnsVolatility::new(None);
139
140        let returns = create_returns(&[
141            0.01, -0.02, 0.03, -0.01, 0.02, 0.04, -0.03, 0.05, -0.04, 0.02,
142        ]);
143        let result = volatility.calculate_from_returns(&returns);
144        assert!(result.is_some());
145
146        assert!(approx_eq!(
147            f64,
148            result.unwrap(),
149            0.48526281538976396,
150            epsilon = 1e-9
151        ));
152    }
153
154    #[rstest]
155    fn test_name() {
156        let volatility = ReturnsVolatility::new(None);
157        assert_eq!(volatility.name(), "Returns Volatility (252 days)");
158    }
159}
nautilus_analysis/statistics/returns_volatility.rs

nautilus_analysis/statistics/
returns_volatility.rs
