optionstratlib_math/error/
metrics.rs

1/******************************************************************************
2   Author: Joaquín Béjar García
3   Email: jb@taunais.com
4   Date: 22/1/25
5******************************************************************************/
6//! Owned by `optionstratlib-math` (ADR-0001 D6, amended by M1 decision D2):
7//! `MetricsError`, whose only crate references are `CurveError` and
8//! `SurfaceError`, both math-owned; the metric traits that report it live in
9//! `curves`, `surfaces` and `geometrics`. The `metrics` *module* stays in
10//! analytics: it is the chain analytics built on top, not this error.
11
12use crate::error::{CurveError, SurfaceError};
13use thiserror::Error;
14
15/// Error types specifically related to financial and statistical metrics calculations.
16///
17/// This enum represents various error conditions that can occur during metrics
18/// processing, analysis, and validation within the library's metrics module.
19/// Each variant provides context about the specific type of error encountered.
20///
21/// # Variants
22///
23/// * `BasicError` - General metrics calculation errors
24/// * `ShapeError` - Errors related to data shape mismatches or incompatible dimensions
25/// * `RangeError` - Errors when data falls outside of expected/valid ranges
26/// * `TrendError` - Errors in trend analysis, regression, or pattern detection
27/// * `RiskError` - Errors in risk metrics calculations (like VaR, Sharpe ratio, etc.)
28/// * `ZeroMean` - A ratio over the mean, such as the coefficient of variation, asked of data whose mean is zero
29/// * `Curve` - Errors related to curve-fitting or curve-based calculations
30/// * `Surface` - Errors in surface modeling or multi-dimensional metrics
31///
32/// # Examples
33///
34/// ```
35/// use optionstratlib_math::error::MetricsError;
36///
37/// // Creating different error types
38/// let basic_err = MetricsError::BasicError("Calculation failed".to_string());
39/// let range_err = MetricsError::RangeError("Value outside expected bounds".to_string());
40/// ```
41#[derive(Error, Debug)]
42pub enum MetricsError {
43    /// General errors in metrics calculations.
44    #[error("Basic Error: {0}")]
45    BasicError(String),
46
47    /// Errors related to data shape mismatches or dimensional incompatibility.
48    /// This typically occurs when input data has an unexpected structure.
49    #[error("Shape Error: {0}")]
50    ShapeError(String),
51
52    /// Errors when data falls outside expected or valid ranges.
53    /// This can indicate outliers or invalid input values.
54    #[error("Range Error: {0}")]
55    RangeError(String),
56
57    /// Errors in trend analysis, regression, or pattern detection algorithms.
58    #[error("Trend Error: {0}")]
59    TrendError(String),
60
61    /// Errors specifically related to financial risk metrics calculations,
62    /// such as Value at Risk (VaR), Conditional VaR, or Sharpe ratio.
63    #[error("Risk Error: {0}")]
64    RiskError(String),
65
66    /// A ratio over the mean, such as the coefficient of variation in
67    /// [`crate::geometrics::RiskMetrics`], asked of data whose mean is zero,
68    /// where the ratio is undefined (#824).
69    #[error("{metric} is undefined: the mean is zero")]
70    ZeroMean {
71        /// The metric that divides by the mean.
72        metric: &'static str,
73    },
74
75    /// Errors encountered during curve-fitting or curve-based calculations,
76    /// such as yield curves or volatility curves.
77    #[error(transparent)]
78    Curve(#[from] CurveError),
79
80    /// Errors in surface modeling or multi-dimensional metrics,
81    /// such as volatility surfaces or correlation matrices.
82    #[error(transparent)]
83    Surface(#[from] SurfaceError),
84}
85
86// Conversions whose SOURCE error is owned by this layer and whose target
87// sits in a lower layer. They live here (ADR-0001 D6, M1-14) so that the
88// lower layer's error file never names a higher one.
89
90/// Wraps a metrics failure as `CurveError::MetricsError` carrying its
91/// `Display` text, so curve builders that call analytics can use `?`.
92impl From<MetricsError> for CurveError {
93    fn from(err: MetricsError) -> Self {
94        CurveError::MetricsError(err.to_string())
95    }
96}
optionstratlib_math/error/metrics.rs

optionstratlib_math/error/
metrics.rs
