statrs/statistics/
order_statistics.rs

1use super::RankTieBreaker;
2
3/// The `OrderStatistics` trait provides statistical utilities
4/// having to do with ordering. All the algorithms are in-place thus requiring
5/// a mutable borrow.
6pub trait OrderStatistics<T> {
7    /// Returns the order statistic `(order 1..N)` from the data
8    ///
9    /// # Remarks
10    ///
11    /// No sorting is assumed. Order must be one-based (between `1` and `N`
12    /// inclusive)
13    /// Returns `f64::NAN` if order is outside the viable range or data is
14    /// empty.
15    ///
16    /// # Examples
17    ///
18    /// ```
19    /// use statrs::statistics::OrderStatistics;
20    /// use statrs::statistics::Data;
21    ///
22    /// let x = [];
23    /// let mut x = Data::new(x);
24    /// assert!(x.order_statistic(1).is_nan());
25    ///
26    /// let y = [0.0, 3.0, -2.0];
27    /// let mut y = Data::new(y);
28    /// assert!(y.order_statistic(0).is_nan());
29    /// assert!(y.order_statistic(4).is_nan());
30    /// assert_eq!(y.order_statistic(2), 0.0);
31    /// assert!(y != Data::new([0.0, 3.0, -2.0]));
32    /// ```
33    fn order_statistic(&mut self, order: usize) -> T;
34
35    /// Returns the median value from the data
36    ///
37    /// # Remarks
38    ///
39    /// Returns `f64::NAN` if data is empty
40    ///
41    /// # Examples
42    ///
43    /// ```
44    /// use statrs::statistics::OrderStatistics;
45    /// use statrs::statistics::Data;
46    ///
47    /// let x = [];
48    /// let mut x = Data::new(x);
49    /// assert!(x.median().is_nan());
50    ///
51    /// let y = [0.0, 3.0, -2.0];
52    /// let mut y = Data::new(y);
53    /// assert_eq!(y.median(), 0.0);
54    /// assert!(y != Data::new([0.0, 3.0, -2.0]));
55    fn median(&mut self) -> T;
56
57    /// Estimates the tau-th quantile from the data. The tau-th quantile
58    /// is the data value where the cumulative distribution function crosses
59    /// tau.
60    ///
61    /// # Remarks
62    ///
63    /// No sorting is assumed. Tau must be between `0` and `1` inclusive.
64    /// Returns `f64::NAN` if data is empty or tau is outside the inclusive
65    /// range.
66    ///
67    /// # Examples
68    ///
69    /// ```
70    /// use statrs::statistics::OrderStatistics;
71    /// use statrs::statistics::Data;
72    ///
73    /// let x = [];
74    /// let mut x = Data::new(x);
75    /// assert!(x.quantile(0.5).is_nan());
76    ///
77    /// let y = [0.0, 3.0, -2.0];
78    /// let mut y = Data::new(y);
79    /// assert!(y.quantile(-1.0).is_nan());
80    /// assert!(y.quantile(2.0).is_nan());
81    /// assert_eq!(y.quantile(0.5), 0.0);
82    /// assert!(y != Data::new([0.0, 3.0, -2.0]));
83    /// ```
84    fn quantile(&mut self, tau: f64) -> T;
85
86    /// Estimates the p-Percentile value from the data.
87    ///
88    /// # Remarks
89    ///
90    /// Use quantile for non-integer percentiles. `p` must be between `0` and
91    /// `100` inclusive.
92    /// Returns `f64::NAN` if data is empty or `p` is outside the inclusive
93    /// range.
94    ///
95    /// # Examples
96    ///
97    /// ```
98    /// use statrs::statistics::OrderStatistics;
99    /// use statrs::statistics::Data;
100    ///
101    /// let x = [];
102    /// let mut x = Data::new(x);
103    /// assert!(x.percentile(0).is_nan());
104    ///
105    /// let y = [1.0, 5.0, 3.0, 4.0, 10.0, 9.0, 6.0, 7.0, 8.0, 2.0];
106    /// let mut y = Data::new(y);
107    /// assert_eq!(y.percentile(0), 1.0);
108    /// assert_eq!(y.percentile(50), 5.5);
109    /// assert_eq!(y.percentile(100), 10.0);
110    /// assert!(y.percentile(105).is_nan());
111    /// assert!(y != Data::new([1.0, 5.0, 3.0, 4.0, 10.0, 9.0, 6.0, 7.0, 8.0, 2.0]));
112    /// ```
113    fn percentile(&mut self, p: usize) -> T;
114
115    /// Estimates the first quartile value from the data.
116    ///
117    /// # Remarks
118    ///
119    /// Returns `f64::NAN` if data is empty
120    ///
121    /// # Examples
122    ///
123    /// ```
124    /// #[macro_use]
125    /// extern crate statrs;
126    ///
127    /// use statrs::statistics::OrderStatistics;
128    /// use statrs::statistics::Data;
129    ///
130    /// # fn main() {
131    /// let x = [];
132    /// let mut x = Data::new(x);
133    /// assert!(x.lower_quartile().is_nan());
134    ///
135    /// let y = [2.0, 1.0, 3.0, 4.0];
136    /// let mut y = Data::new(y);
137    /// assert_almost_eq!(y.lower_quartile(), 1.416666666666666, 1e-15);
138    /// assert!(y != Data::new([2.0, 1.0, 3.0, 4.0]));
139    /// # }
140    /// ```
141    fn lower_quartile(&mut self) -> T;
142
143    /// Estimates the third quartile value from the data.
144    ///
145    /// # Remarks
146    ///
147    /// Returns `f64::NAN` if data is empty
148    ///
149    /// # Examples
150    ///
151    /// ```
152    /// #[macro_use]
153    /// extern crate statrs;
154    ///
155    /// use statrs::statistics::OrderStatistics;
156    /// use statrs::statistics::Data;
157    ///
158    /// # fn main() {
159    /// let x = [];
160    /// let mut x = Data::new(x);
161    /// assert!(x.upper_quartile().is_nan());
162    ///
163    /// let y = [2.0, 1.0, 3.0, 4.0];
164    /// let mut y = Data::new(y);
165    /// assert_almost_eq!(y.upper_quartile(), 3.5833333333333333, 1e-15);
166    /// assert!(y != Data::new([2.0, 1.0, 3.0, 4.0]));
167    /// # }
168    /// ```
169    fn upper_quartile(&mut self) -> T;
170
171    /// Estimates the inter-quartile range from the data.
172    ///
173    /// # Remarks
174    ///
175    /// Returns `f64::NAN` if data is empty
176    ///
177    /// # Examples
178    ///
179    /// ```
180    /// #[macro_use]
181    /// extern crate statrs;
182    ///
183    /// use statrs::statistics::Data;
184    /// use statrs::statistics::OrderStatistics;
185    ///
186    /// # fn main() {
187    /// let x = [];
188    /// let mut x = Data::new(x);
189    /// assert!(x.interquartile_range().is_nan());
190    ///
191    /// let y = [2.0, 1.0, 3.0, 4.0];
192    /// let mut y = Data::new(y);
193    /// assert_almost_eq!(y.interquartile_range(), 2.166666666666667, 1e-15);
194    /// assert!(y != Data::new([2.0, 1.0, 3.0, 4.0]));
195    /// # }
196    /// ```
197    fn interquartile_range(&mut self) -> T;
198
199    /// Evaluates the rank of each entry of the data.
200    ///
201    /// # Examples
202    ///
203    /// ```
204    /// use statrs::statistics::{OrderStatistics, RankTieBreaker};
205    /// use statrs::statistics::Data;
206    ///
207    /// let x = [];
208    /// let mut x = Data::new(x);
209    /// assert_eq!(x.ranks(RankTieBreaker::Average).len(), 0);
210    ///
211    /// let y = [1.0, 3.0, 2.0, 2.0];
212    /// let mut y = Data::new([1.0, 3.0, 2.0, 2.0]);
213    /// assert_eq!(y.clone().ranks(RankTieBreaker::Average), [1.0, 4.0,
214    /// 2.5, 2.5]);
215    /// assert_eq!(y.clone().ranks(RankTieBreaker::Min), [1.0, 4.0, 2.0,
216    /// 2.0]);
217    /// ```
218    fn ranks(&mut self, tie_breaker: RankTieBreaker) -> Vec<T>;
219}
statrs/statistics/order_statistics.rs

statrs/statistics/
order_statistics.rs
