1+
2+ /**
3+ * Factory functions for standard statistics strings
4+ */
5+ export abstract class Stats {
6+ /**
7+ * The count (number) of data points used for the statistical calculation.
8+ */
9+ public static readonly SAMPLE_COUNT = 'SampleCount' ;
10+
11+ /**
12+ * The value of Sum / SampleCount during the specified period.
13+ */
14+ public static readonly AVERAGE = 'Average' ;
15+ /**
16+ * All values submitted for the matching metric added together.
17+ * This statistic can be useful for determining the total volume of a metric.
18+ */
19+ public static readonly SUM = 'Sum' ;
20+
21+ /**
22+ * The lowest value observed during the specified period.
23+ * You can use this value to determine low volumes of activity for your application.
24+ */
25+ public static readonly MINIMUM = 'Minimum' ;
26+
27+ /**
28+ * The highest value observed during the specified period.
29+ * You can use this value to determine high volumes of activity for your application.
30+ */
31+ public static readonly MAXIMUM = 'Maximum' ;
32+
33+ /**
34+ * Interquartile mean (IQM) is the trimmed mean of the interquartile range, or the middle 50% of values.
35+ *
36+ * It is equivalent to `trimmedMean(25, 75)`.
37+ */
38+ public static readonly IQM = 'IQM' ;
39+
40+ /**
41+ * Percentile indicates the relative standing of a value in a dataset.
42+ *
43+ * Percentiles help you get a better understanding of the distribution of your metric data.
44+ *
45+ * For example, `p(90)` is the 90th percentile and means that 90% of the data
46+ * within the period is lower than this value and 10% of the data is higher
47+ * than this value.
48+ */
49+ public static percentile ( percentile : number ) {
50+ assertPercentage ( percentile ) ;
51+ return `p${ percentile } ;
52+ }
53+
54+ /**
55+ * A shorter alias for `percentile()`.
56+ */
57+ public static p ( percentile : number ) {
58+ return Stats . percentile ( percentile ) ;
59+ }
60+
61+ /**
62+ * Trimmed mean (TM) is the mean of all values that are between two specified boundaries.
63+ *
64+ * Values outside of the boundaries are ignored when the mean is calculated.
65+ * You define the boundaries as one or two numbers between 0 and 100, up to 10
66+ * decimal places. The numbers are percentages.
67+ *
68+ * - If two numbers are given, they define the lower and upper bounds in percentages,
69+ * respectively.
70+ * - If one number is given, it defines the upper bound (the lower bound is assumed to
71+ * be 0).
72+ *
73+ * For example, `tm(90)` calculates the average after removing the 10% of data
74+ * points with the highest values; `tm(10, 90)` calculates the average after removing the
75+ * 10% with the lowest and 10% with the highest values.
76+ */
77+ public static trimmedMean ( p1 : number , p2 ?: number ) {
78+ return boundaryPercentileStat ( 'tm' , 'TM' , p1 , p2 ) ;
79+ }
80+
81+ /**
82+ * A shorter alias for `trimmedMean()`.
83+ */
84+ public static tm ( p1 : number , p2 ?: number ) {
85+ return Stats . trimmedMean ( p1 , p2 ) ;
86+ }
87+
88+ /**
89+ * Winsorized mean (WM) is similar to trimmed mean.
90+ *
91+ * However, with winsorized mean, the values that are outside the boundary are
92+ * not ignored, but instead are considered to be equal to the value at the
93+ * edge of the appropriate boundary. After this normalization, the average is
94+ * calculated. You define the boundaries as one or two numbers between 0 and
95+ * 100, up to 10 decimal places.
96+ *
97+ * - If two numbers are given, they define the lower and upper bounds in percentages,
98+ * respectively.
99+ * - If one number is given, it defines the upper bound (the lower bound is assumed to
100+ * be 0).
101+ *
102+ * For example, `tm(90)` calculates the average after removing the 10% of data
103+ * points with the highest values; `tm(10, 90)` calculates the average after removing the
104+ * 10% with the lowest and 10% with the highest values.
105+ *
106+ * For example, `wm(90)` calculates the average while treating the 10% of the
107+ * highest values to be equal to the value at the 90th percentile.
108+ * `wm(10, 90)` calculates the average while treaing the bottom 10% and the
109+ * top 10% of values to be equal to the boundary values.
110+ */
111+ public static winsorizedMean ( p1 : number , p2 ?: number ) {
112+ return boundaryPercentileStat ( 'wm' , 'WM' , p1 , p2 ) ;
113+ }
114+
115+ /**
116+ * A shorter alias for `winsorizedMean()`.
117+ */
118+ public static wm ( p1 : number , p2 ?: number ) {
119+ return Stats . winsorizedMean ( p1 , p2 ) ;
120+ }
121+
122+ /**
123+ * Trimmed count (TC) is the number of data points in the chosen range for a trimmed mean statistic.
124+ *
125+ * - If two numbers are given, they define the lower and upper bounds in percentages,
126+ * respectively.
127+ * - If one number is given, it defines the upper bound (the lower bound is assumed to
128+ * be 0).
129+ *
130+ * For example, `tc(90)` returns the number of data points not including any
131+ * data points that fall in the highest 10% of the values. `tc(10, 90)`
132+ * returns the number of data points not including any data points that fall
133+ * in the lowest 10% of the values and the highest 90% of the values.
134+ */
135+ public static trimmedCount ( p1 : number , p2 ?: number ) {
136+ return boundaryPercentileStat ( 'tc' , 'TC' , p1 , p2 ) ;
137+ }
138+
139+ /**
140+ * Shorter alias for `trimmedCount()`.
141+ */
142+ public static tc ( p1 : number , p2 ?: number ) {
143+ return Stats . trimmedCount ( p1 , p2 ) ;
144+ }
145+
146+ /**
147+ * Trimmed sum (TS) is the sum of the values of data points in a chosen range for a trimmed mean statistic.
148+ * It is equivalent to `(Trimmed Mean) * (Trimmed count)`.
149+ *
150+ * - If two numbers are given, they define the lower and upper bounds in percentages,
151+ * respectively.
152+ * - If one number is given, it defines the upper bound (the lower bound is assumed to
153+ * be 0).
154+ *
155+ * For example, `ts(90)` returns the sum of the data points not including any
156+ * data points that fall in the highest 10% of the values. `ts(10, 90)`
157+ * returns the sum of the data points not including any data points that fall
158+ * in the lowest 10% of the values and the highest 90% of the values.
159+ */
160+ public static trimmedSum ( p1 : number , p2 ?: number ) {
161+ return boundaryPercentileStat ( 'ts' , 'TS' , p1 , p2 ) ;
162+ }
163+
164+ /**
165+ * Shorter alias for `trimmedSum()`.
166+ */
167+ public static ts ( p1 : number , p2 ?: number ) {
168+ return Stats . trimmedSum ( p1 , p2 ) ;
169+ }
170+
171+ /**
172+ * Percentile rank (PR) is the percentage of values that meet a fixed threshold.
173+ *
174+ * - If two numbers are given, they define the lower and upper bounds in absolute values,
175+ * respectively.
176+ * - If one number is given, it defines the upper bound (the lower bound is assumed to
177+ * be 0).
178+ *
179+ * For example, `percentileRank(300)` returns the percentage of data points that have a value of 300 or less.
180+ * `percentileRank(100, 2000)` returns the percentage of data points that have a value between 100 and 2000.
181+ */
182+ public static percentileRank ( v1 : number , v2 ?: number ) {
183+ if ( v2 !== undefined ) {
184+ return `PR(${ v1 } ${ v2 } ;
185+ } else {
186+ return `PR(:${ v1 } ;
187+ }
188+ }
189+
190+ /**
191+ * Shorter alias for `percentileRank()`.
192+ */
193+ public static pr ( v1 : number , v2 ?: number ) {
194+ return this . percentileRank ( v1 , v2 ) ;
195+ }
196+ }
197+
198+ function assertPercentage ( x ?: number ) {
199+ if ( x !== undefined && ( x < 0 || x > 100 ) ) {
200+ throw new Error ( `Expecting a percentage, got: ${ x } ) ;
201+ }
202+ }
203+
204+ /**
205+ * Formatting helper because all these stats look the same
206+ */
207+ function boundaryPercentileStat ( oneBoundaryStat : string , twoBoundaryStat : string , p1 : number , p2 : number | undefined ) {
208+ assertPercentage ( p1 ) ;
209+ assertPercentage ( p2 ) ;
210+ if ( p2 !== undefined ) {
211+ return `${ twoBoundaryStat } ${ p1 } ${ p2 } ;
212+ } else {
213+ return `${ oneBoundaryStat } ${ p1 } ;
214+ }
215+ }
0 commit comments