1 #Region "Microsoft.VisualBasic::f26d583246bdc61109e553deda4d4bd2, Microsoft.VisualBasic.Core\Extensions\Math\StatisticsMathExtensions\Linq\EnumerableStatsStandardDeviation.vb"
2
3     ' Author:
4     
5     '       asuka (amethyst.asuka@gcmodeller.org)
6     '       xie (genetics@smrucc.org)
7     '       xieguigang (xie.guigang@live.com)
8     
9     ' Copyright (c) 2018 GPL3 Licensed
10     
11     
12     ' GNU GENERAL PUBLIC LICENSE (GPL3)
13     
14     
15     ' This program is free software: you can redistribute it and/or modify
16     ' it under the terms of the GNU General Public License as published by
17     ' the Free Software Foundation, either version 3 of the License, or
18     ' (at your option) any later version.
19     
20     ' This program is distributed in the hope that it will be useful,
21     ' but WITHOUT ANY WARRANTY; without even the implied warranty of
22     ' MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
23     ' GNU General Public License for more details.
24     
25     ' You should have received a copy of the GNU General Public License
26     ' along with this program. If not, see <http://www.gnu.org/licenses/>.
27
28
29
30     ' /********************************************************************************/
31
32     ' Summaries:
33
34     '     Module EnumerableStatsStandardDeviation
35     
36     '         Function: (+20 Overloads) StandardDeviation
37     
38     
39     ' /********************************************************************************/
40
41 #End Region
42
43 Imports System.Runtime.CompilerServices
44 Imports sys = System.Math
45
46 Namespace Math.Statistics.Linq
47
48     Public Module EnumerableStatsStandardDeviation
49         '         ' Summary:
50         '     Computes the StandardDeviation of a sequence of nullable System.Decimal values.
51         '         ' Parameters:
52         '   source:
53         '     A sequence of nullable System.Decimal values to calculate the StandardDeviation of.
54         '         ' Returns:
55         '     The StandardDeviation of the sequence of values, or null if the source sequence is
56         '     empty or contains only values that are null.
57         '         ' Exceptions:
58         '   System.ArgumentNullException:
59         '     source is null.
60         '         '   System.OverflowException:
61         '     The sum of the elements in the sequence is larger than System.Decimal.MaxValue.
62         <Extension>
63         Public Function StandardDeviation(source As IEnumerable(Of Decimal?)) As Decimal
64             Dim values As IEnumerable(Of Decimal) = source.Coalesce()
65             If values.Any() Then
66                 Return values.StandardDeviation()
67             End If
68
69             Return Nothing
70         End Function
71         '         ' Summary:
72         '     Computes the StandardDeviation of a sequence of System.Decimal values.
73         '         ' Parameters:
74         '   source:
75         '     A sequence of System.Decimal values to calculate the StandardDeviation of.
76         '         ' Returns:
77         '     The StandardDeviation of the sequence of values.
78         '         ' Exceptions:
79         '   System.ArgumentNullException:
80         '     source is null.
81         '         '   System.InvalidOperationException:
82         '     source contains no elements.
83         '         '   System.OverflowException:
84         '     The sum of the elements in the sequence is larger than System.Decimal.MaxValue.
85         <Extension>
86         Public Function StandardDeviation(source As IEnumerable(Of Decimal)) As Decimal
87             Return CDec(source.[Select](Function(x) CDbl(x)).StandardDeviation())
88         End Function
89         '         ' Summary:
90         '     Computes the StandardDeviation of a sequence of nullable System.Double values.
91         '         ' Parameters:
92         '   source:
93         '     A sequence of nullable System.Double values to calculate the StandardDeviation of.
94         '         ' Returns:
95         '     The StandardDeviation of the sequence of values, or null if the source sequence is
96         '     empty or contains only values that are null.
97         '         ' Exceptions:
98         '   System.ArgumentNullException:
99         '     source is null.
100         <Extension>
101         Public Function StandardDeviation(source As IEnumerable(Of Double?)) As Double
102             Dim values As IEnumerable(Of Double) = source.Coalesce()
103             If values.Any() Then
104                 Return values.StandardDeviation()
105             End If
106
107             Return Nothing
108         End Function
109         '         ' Summary:
110         '     Computes the StandardDeviation of a sequence of System.Double values.
111         '         ' Parameters:
112         '   source:
113         '     A sequence of System.Double values to calculate the StandardDeviation of.
114         '         ' Returns:
115         '     The StandardDeviation of the sequence of values.
116         '         ' Exceptions:
117         '   System.ArgumentNullException:
118         '     source is null.
119         '         '   System.InvalidOperationException:
120         '     source contains no elements.
121         <Extension>
122         Public Function StandardDeviation(source As IEnumerable(Of Double)) As Double
123             Return sys.Sqrt(source.Variance())
124         End Function
125         '         ' Summary:
126         '     Computes the StandardDeviation of a sequence of nullable System.Single values.
127         '         ' Parameters:
128         '   source:
129         '     A sequence of nullable System.Single values to calculate the StandardDeviation of.
130         '         ' Returns:
131         '     The StandardDeviation of the sequence of values, or null if the source sequence is
132         '     empty or contains only values that are null.
133         '         ' Exceptions:
134         '   System.ArgumentNullException:
135         '     source is null.
136         <Extension>
137         Public Function StandardDeviation(source As IEnumerable(Of Single?)) As Single
138             Dim values As IEnumerable(Of Single) = source.Coalesce()
139             If values.Any() Then
140                 Return values.StandardDeviation()
141             End If
142
143             Return Nothing
144         End Function
145         '         ' Summary:
146         '     Computes the StandardDeviation of a sequence of System.Single values.
147         '         ' Parameters:
148         '   source:
149         '     A sequence of System.Single values to calculate the StandardDeviation of.
150         '         ' Returns:
151         '     The StandardDeviation of the sequence of values.
152         '         ' Exceptions:
153         '   System.ArgumentNullException:
154         '     source is null.
155         '         '   System.InvalidOperationException:
156         '     source contains no elements.
157         <Extension>
158         Public Function StandardDeviation(source As IEnumerable(Of Single)) As Single
159             Return CSng(source.[Select](Function(x) CDbl(x)).StandardDeviation())
160         End Function
161         '         ' Summary:
162         '     Computes the StandardDeviation of a sequence of nullable System.Int32 values.
163         '         ' Parameters:
164         '   source:
165         '     A sequence of nullable System.Int32values to calculate the StandardDeviation of.
166         '         ' Returns:
167         '     The StandardDeviation of the sequence of values, or null if the source sequence is
168         '     empty or contains only values that are null.
169         '         ' Exceptions:
170         '   System.ArgumentNullException:
171         '     source is null.
172         '         '   System.OverflowException:
173         '     The sum of the elements in the sequence is larger than System.Int64.MaxValue.
174         <Extension>
175         Public Function StandardDeviation(source As IEnumerable(Of Integer?)) As Double
176             Dim values As IEnumerable(Of Double) = source.Where(Function(d) d.HasValue).[Select](Function(x) CDbl(x))
177             If values.Any() Then
178                 Return values.StandardDeviation()
179             End If
180
181             Return Nothing
182         End Function
183         '         ' Summary:
184         '     Computes the StandardDeviation of a sequence of System.Int32 values.
185         '         ' Parameters:
186         '   source:
187         '     A sequence of System.Int32 values to calculate the StandardDeviation of.
188         '         ' Returns:
189         '     The StandardDeviation of the sequence of values.
190         '         ' Exceptions:
191         '   System.ArgumentNullException:
192         '     source is null.
193         '         '   System.InvalidOperationException:
194         '     source contains no elements.
195         '         '   System.OverflowException:
196         '     The sum of the elements in the sequence is larger than System.Int64.MaxValue.
197         <Extension>
198         Public Function StandardDeviation(source As IEnumerable(Of Integer)) As Double
199             Return source.[Select](Function(x) CDbl(x)).StandardDeviation()
200         End Function
201         '         ' Summary:
202         '     Computes the StandardDeviation of a sequence of nullable System.Int64 values.
203         '         ' Parameters:
204         '   source:
205         '     A sequence of nullable System.Int64 values to calculate the StandardDeviation of.
206         '         ' Returns:
207         '     The StandardDeviation of the sequence of values, or null if the source sequence is
208         '     empty or contains only values that are null.
209         '         ' Exceptions:
210         '   System.ArgumentNullException:
211         '     source is null.
212         '         '   System.OverflowException:
213         '     The sum of the elements in the sequence is larger than System.Int64.MaxValue.
214         <Extension>
215         Public Function StandardDeviation(source As IEnumerable(Of Long?)) As Double
216             Dim values As IEnumerable(Of Long) = source.Coalesce()
217             If values.Any() Then
218                 Return values.StandardDeviation()
219             End If
220
221             Return Nothing
222         End Function
223         '         ' Summary:
224         '     Computes the StandardDeviation of a sequence of System.Int64 values.
225         '         ' Parameters:
226         '   source:
227         '     A sequence of System.Int64 values to calculate the StandardDeviation of.
228         '         ' Returns:
229         '     The StandardDeviation of the sequence of values.
230         '         ' Exceptions:
231         '   System.ArgumentNullException:
232         '     source is null.
233         '         '   System.InvalidOperationException:
234         '     source contains no elements.
235         '         '   System.OverflowException:
236         '     The sum of the elements in the sequence is larger than System.Int64.MaxValue.
237         <Extension>
238         Public Function StandardDeviation(source As IEnumerable(Of Long)) As Double
239             Return source.[Select](Function(x) CDbl(x)).StandardDeviation()
240         End Function
241         '         ' Summary:
242         '     Computes the StandardDeviation of a sequence of nullable System.Decimal values that
243         '     are obtained by invoking a transform function on each element of the input
244         '     sequence.
245         '         ' Parameters:
246         '   source:
247         '     A sequence of values to calculate the StandardDeviation of.
248         '         '   selector:
249         '     A transform function to apply to each element.
250         '         ' Type parameters:
251         '   TSource:
252         '     The type of the elements of source.
253         '         ' Returns:
254         '     The StandardDeviation of the sequence of values, or null if the source sequence is
255         '     empty or contains only values that are null.
256         '         ' Exceptions:
257         '   System.ArgumentNullException:
258         '     source or selector is null.
259         '         '   System.OverflowException:
260         '     The sum of the elements in the sequence is larger than System.Decimal.MaxValue.
261         <Extension>
262         Public Function StandardDeviation(Of TSource)(source As IEnumerable(Of TSource), selector As Func(Of TSource, Decimal?)) As Decimal
263             Return source.[Select](selector).StandardDeviation()
264         End Function
265         '         ' Summary:
266         '     Computes the StandardDeviation of a sequence of System.Decimal values that are obtained
267         '     by invoking a transform function on each element of the input sequence.
268         '         ' Parameters:
269         '   source:
270         '     A sequence of values that are used to calculate an StandardDeviation.
271         '         '   selector:
272         '     A transform function to apply to each element.
273         '         ' Type parameters:
274         '   TSource:
275         '     The type of the elements of source.
276         '         ' Returns:
277         '     The StandardDeviation of the sequence of values.
278         '         ' Exceptions:
279         '   System.ArgumentNullException:
280         '     source or selector is null.
281         '         '   System.InvalidOperationException:
282         '     source contains no elements.
283         '         '   System.OverflowException:
284         '     The sum of the elements in the sequence is larger than System.Decimal.MaxValue.
285         <Extension>
286         Public Function StandardDeviation(Of TSource)(source As IEnumerable(Of TSource), selector As Func(Of TSource, Decimal)) As Decimal
287             Return source.[Select](selector).StandardDeviation()
288         End Function
289         '         ' Summary:
290         '     Computes the StandardDeviation of a sequence of nullable System.Double values that
291         '     are obtained by invoking a transform function on each element of the input
292         '     sequence.
293         '         ' Parameters:
294         '   source:
295         '     A sequence of values to calculate the StandardDeviation of.
296         '         '   selector:
297         '     A transform function to apply to each element.
298         '         ' Type parameters:
299         '   TSource:
300         '     The type of the elements of source.
301         '         ' Returns:
302         '     The StandardDeviation of the sequence of values, or null if the source sequence is
303         '     empty or contains only values that are null.
304         '         ' Exceptions:
305         '   System.ArgumentNullException:
306         '     source or selector is null.
307         <Extension>
308         Public Function StandardDeviation(Of TSource)(source As IEnumerable(Of TSource), selector As Func(Of TSource, Double?)) As Double
309             Return source.[Select](selector).StandardDeviation()
310         End Function
311         '         ' Summary:
312         '     Computes the StandardDeviation of a sequence of System.Double values that are obtained
313         '     by invoking a transform function on each element of the input sequence.
314         '         ' Parameters:
315         '   source:
316         '     A sequence of values to calculate the StandardDeviation of.
317         '         '   selector:
318         '     A transform function to apply to each element.
319         '         ' Type parameters:
320         '   TSource:
321         '     The type of the elements of source.
322         '         ' Returns:
323         '     The StandardDeviation of the sequence of values.
324         '         ' Exceptions:
325         '   System.ArgumentNullException:
326         '     source or selector is null.
327         '         '   System.InvalidOperationException:
328         '     source contains no elements.
329         <Extension>
330         Public Function StandardDeviation(Of TSource)(source As IEnumerable(Of TSource), selector As Func(Of TSource, Double)) As Double
331             Return source.[Select](selector).StandardDeviation()
332         End Function
333         '         ' Summary:
334         '     Computes the StandardDeviation of a sequence of nullable System.Single values that
335         '     are obtained by invoking a transform function on each element of the input
336         '     sequence.
337         '         ' Parameters:
338         '   source:
339         '     A sequence of values to calculate the StandardDeviation of.
340         '         '   selector:
341         '     A transform function to apply to each element.
342         '         ' Type parameters:
343         '   TSource:
344         '     The type of the elements of source.
345         '         ' Returns:
346         '     The StandardDeviation of the sequence of values, or null if the source sequence is
347         '     empty or contains only values that are null.
348         '         ' Exceptions:
349         '   System.ArgumentNullException:
350         '     source or selector is null.
351         <Extension>
352         Public Function StandardDeviation(Of TSource)(source As IEnumerable(Of TSource), selector As Func(Of TSource, Single?)) As Single
353             Return source.[Select](selector).StandardDeviation()
354         End Function
355         '         ' Summary:
356         '     Computes the StandardDeviation of a sequence of System.Single values that are obtained
357         '     by invoking a transform function on each element of the input sequence.
358         '         ' Parameters:
359         '   source:
360         '     A sequence of values to calculate the StandardDeviation of.
361         '         '   selector:
362         '     A transform function to apply to each element.
363         '         ' Type parameters:
364         '   TSource:
365         '     The type of the elements of source.
366         '         ' Returns:
367         '     The StandardDeviation of the sequence of values.
368         '         ' Exceptions:
369         '   System.ArgumentNullException:
370         '     source or selector is null.
371         '         '   System.InvalidOperationException:
372         '     source contains no elements.
373         <Extension>
374         Public Function StandardDeviation(Of TSource)(source As IEnumerable(Of TSource), selector As Func(Of TSource, Single)) As Single
375             Return source.[Select](selector).StandardDeviation()
376         End Function
377         '         ' Summary:
378         '     Computes the StandardDeviation of a sequence of nullable System.Int32 values that are
379         '     obtained by invoking a transform function on each element of the input sequence.
380         '         ' Parameters:
381         '   source:
382         '     A sequence of values to calculate the StandardDeviation of.
383         '         '   selector:
384         '     A transform function to apply to each element.
385         '         ' Type parameters:
386         '   TSource:
387         '     The type of the elements of source.
388         '         ' Returns:
389         '     The StandardDeviation of the sequence of values, or null if the source sequence is
390         '     empty or contains only values that are null.
391         '         ' Exceptions:
392         '   System.ArgumentNullException:
393         '     source or selector is null.
394         '         '   System.OverflowException:
395         '     The sum of the elements in the sequence is larger than System.Int64.MaxValue.
396         <Extension>
397         Public Function StandardDeviation(Of TSource)(source As IEnumerable(Of TSource), selector As Func(Of TSource, Integer?)) As Double
398             Return source.[Select](selector).StandardDeviation()
399         End Function
400         '         ' Summary:
401         '     Computes the StandardDeviation of a sequence of System.Int32 values that are obtained
402         '     by invoking a transform function on each element of the input sequence.
403         '         ' Parameters:
404         '   source:
405         '     A sequence of values to calculate the StandardDeviation of.
406         '         '   selector:
407         '     A transform function to apply to each element.
408         '         ' Type parameters:
409         '   TSource:
410         '     The type of the elements of source.
411         '         ' Returns:
412         '     The StandardDeviation of the sequence of values.
413         '         ' Exceptions:
414         '   System.ArgumentNullException:
415         '     source or selector is null.
416         '         '   System.InvalidOperationException:
417         '     source contains no elements.
418         '         '   System.OverflowException:
419         '     The sum of the elements in the sequence is larger than System.Int64.MaxValue.
420         <Extension>
421         Public Function StandardDeviation(Of TSource)(source As IEnumerable(Of TSource), selector As Func(Of TSource, Integer)) As Double
422             Return source.[Select](selector).StandardDeviation()
423         End Function
424         '         ' Summary:
425         '     Computes the StandardDeviation of a sequence of nullable System.Int64 values that are
426         '     obtained by invoking a transform function on each element of the input sequence.
427         '         ' Parameters:
428         '   source:
429         '     A sequence of values to calculate the StandardDeviation of.
430         '         '   selector:
431         '     A transform function to apply to each element.
432         '         ' Type parameters:
433         '   TSource:
434         '     The type of the elements of source.
435         '         ' Returns:
436         '     The StandardDeviation of the sequence of values, or null if the source sequence is
437         '     empty or contains only values that are null.
438         <Extension>
439         Public Function StandardDeviation(Of TSource)(source As IEnumerable(Of TSource), selector As Func(Of TSource, Long?)) As Double
440             Return source.[Select](selector).StandardDeviation()
441         End Function
442         '         ' Summary:
443         '     Computes the StandardDeviation of a sequence of System.Int64 values that are obtained
444         '     by invoking a transform function on each element of the input sequence.
445         '         ' Parameters:
446         '   source:
447         '     A sequence of values to calculate the StandardDeviation of.
448         '         '   selector:
449         '     A transform function to apply to each element.
450         '         ' Type parameters:
451         '   TSource:
452         '     The type of the elements of source.
453         '         ' Returns:
454         '     The StandardDeviation of the sequence of values.
455         '         ' Exceptions:
456         '   System.ArgumentNullException:
457         '     source or selector is null.
458         '         '   System.InvalidOperationException:
459         '     source contains no elements.
460         '         '   System.OverflowException:
461         '     The sum of the elements in the sequence is larger than System.Int64.MaxValue.
462         <Extension>
463         Public Function StandardDeviation(Of TSource)(source As IEnumerable(Of TSource), selector As Func(Of TSource, Long)) As Double
464             Return source.[Select](selector).StandardDeviation()
465         End Function
466     End Module
467 End Namespace