1 #Region "Microsoft.VisualBasic::018201163638d7ddfa7332a512a0ffcb, 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         '
50         ' Summary:
51         '     Computes the StandardDeviation of a sequence of nullable System.Decimal values.
52         '
53         ' Parameters:
54         '   source:
55         '     A sequence of nullable System.Decimal values to calculate the StandardDeviation of.
56         '
57         Returns:
58         '     The StandardDeviation of the sequence of values, or null if the source sequence is
59         '     empty or contains only values that are null.
60         '
61         ' Exceptions:
62         '   System.ArgumentNullException:
63         '     source is null.
64         '
65         '   System.OverflowException:
66         '     The sum of the elements in the sequence is larger than System.Decimal.MaxValue.
67         <Extension>
68         Public Function StandardDeviation(source As IEnumerable(Of Decimal?)) As Decimal
69             Dim values As IEnumerable(Of Decimal) = source.Coalesce()
70             If values.Any() Then
71                 Return values.StandardDeviation()
72             End If
73
74             Return Nothing
75         End Function
76         '
77         ' Summary:
78         '     Computes the StandardDeviation of a sequence of System.Decimal values.
79         '
80         ' Parameters:
81         '   source:
82         '     A sequence of System.Decimal values to calculate the StandardDeviation of.
83         '
84         Returns:
85         '     The StandardDeviation of the sequence of values.
86         '
87         ' Exceptions:
88         '   System.ArgumentNullException:
89         '     source is null.
90         '
91         '   System.InvalidOperationException:
92         '     source contains no elements.
93         '
94         '   System.OverflowException:
95         '     The sum of the elements in the sequence is larger than System.Decimal.MaxValue.
96         <Extension>
97         Public Function StandardDeviation(source As IEnumerable(Of Decimal)) As Decimal
98             Return CDec(source.[Select](Function(x) CDbl(x)).StandardDeviation())
99         End Function
100         '
101         ' Summary:
102         '     Computes the StandardDeviation of a sequence of nullable System.Double values.
103         '
104         ' Parameters:
105         '   source:
106         '     A sequence of nullable System.Double values to calculate the StandardDeviation of.
107         '
108         Returns:
109         '     The StandardDeviation of the sequence of values, or null if the source sequence is
110         '     empty or contains only values that are null.
111         '
112         ' Exceptions:
113         '   System.ArgumentNullException:
114         '     source is null.
115         <Extension>
116         Public Function StandardDeviation(source As IEnumerable(Of Double?)) As Double
117             Dim values As IEnumerable(Of Double) = source.Coalesce()
118             If values.Any() Then
119                 Return values.StandardDeviation()
120             End If
121
122             Return Nothing
123         End Function
124         '
125         ' Summary:
126         '     Computes the StandardDeviation of a sequence of System.Double values.
127         '
128         ' Parameters:
129         '   source:
130         '     A sequence of System.Double values to calculate the StandardDeviation of.
131         '
132         Returns:
133         '     The StandardDeviation of the sequence of values.
134         '
135         ' Exceptions:
136         '   System.ArgumentNullException:
137         '     source is null.
138         '
139         '   System.InvalidOperationException:
140         '     source contains no elements.
141         <Extension>
142         Public Function StandardDeviation(source As IEnumerable(Of Double)) As Double
143             Return sys.Sqrt(source.Variance())
144         End Function
145         '
146         ' Summary:
147         '     Computes the StandardDeviation of a sequence of nullable System.Single values.
148         '
149         ' Parameters:
150         '   source:
151         '     A sequence of nullable System.Single values to calculate the StandardDeviation of.
152         '
153         Returns:
154         '     The StandardDeviation of the sequence of values, or null if the source sequence is
155         '     empty or contains only values that are null.
156         '
157         ' Exceptions:
158         '   System.ArgumentNullException:
159         '     source is null.
160         <Extension>
161         Public Function StandardDeviation(source As IEnumerable(Of Single?)) As Single
162             Dim values As IEnumerable(Of Single) = source.Coalesce()
163             If values.Any() Then
164                 Return values.StandardDeviation()
165             End If
166
167             Return Nothing
168         End Function
169         '
170         ' Summary:
171         '     Computes the StandardDeviation of a sequence of System.Single values.
172         '
173         ' Parameters:
174         '   source:
175         '     A sequence of System.Single values to calculate the StandardDeviation of.
176         '
177         Returns:
178         '     The StandardDeviation of the sequence of values.
179         '
180         ' Exceptions:
181         '   System.ArgumentNullException:
182         '     source is null.
183         '
184         '   System.InvalidOperationException:
185         '     source contains no elements.
186         <Extension>
187         Public Function StandardDeviation(source As IEnumerable(Of Single)) As Single
188             Return CSng(source.[Select](Function(x) CDbl(x)).StandardDeviation())
189         End Function
190         '
191         ' Summary:
192         '     Computes the StandardDeviation of a sequence of nullable System.Int32 values.
193         '
194         ' Parameters:
195         '   source:
196         '     A sequence of nullable System.Int32values to calculate the StandardDeviation of.
197         '
198         Returns:
199         '     The StandardDeviation of the sequence of values, or null if the source sequence is
200         '     empty or contains only values that are null.
201         '
202         ' Exceptions:
203         '   System.ArgumentNullException:
204         '     source is null.
205         '
206         '   System.OverflowException:
207         '     The sum of the elements in the sequence is larger than System.Int64.MaxValue.
208         <Extension>
209         Public Function StandardDeviation(source As IEnumerable(Of Integer?)) As Double
210             Dim values As IEnumerable(Of Double) = source.Where(Function(d) d.HasValue).[Select](Function(x) CDbl(x))
211             If values.Any() Then
212                 Return values.StandardDeviation()
213             End If
214
215             Return Nothing
216         End Function
217         '
218         ' Summary:
219         '     Computes the StandardDeviation of a sequence of System.Int32 values.
220         '
221         ' Parameters:
222         '   source:
223         '     A sequence of System.Int32 values to calculate the StandardDeviation of.
224         '
225         Returns:
226         '     The StandardDeviation of the sequence of values.
227         '
228         ' Exceptions:
229         '   System.ArgumentNullException:
230         '     source is null.
231         '
232         '   System.InvalidOperationException:
233         '     source contains no elements.
234         '
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 Integer)) As Double
239             Return source.[Select](Function(x) CDbl(x)).StandardDeviation()
240         End Function
241         '
242         ' Summary:
243         '     Computes the StandardDeviation of a sequence of nullable System.Int64 values.
244         '
245         ' Parameters:
246         '   source:
247         '     A sequence of nullable System.Int64 values to calculate the StandardDeviation of.
248         '
249         Returns:
250         '     The StandardDeviation of the sequence of values, or null if the source sequence is
251         '     empty or contains only values that are null.
252         '
253         ' Exceptions:
254         '   System.ArgumentNullException:
255         '     source is null.
256         '
257         '   System.OverflowException:
258         '     The sum of the elements in the sequence is larger than System.Int64.MaxValue.
259         <Extension>
260         Public Function StandardDeviation(source As IEnumerable(Of Long?)) As Double
261             Dim values As IEnumerable(Of Long) = source.Coalesce()
262             If values.Any() Then
263                 Return values.StandardDeviation()
264             End If
265
266             Return Nothing
267         End Function
268         '
269         ' Summary:
270         '     Computes the StandardDeviation of a sequence of System.Int64 values.
271         '
272         ' Parameters:
273         '   source:
274         '     A sequence of System.Int64 values to calculate the StandardDeviation of.
275         '
276         Returns:
277         '     The StandardDeviation of the sequence of values.
278         '
279         ' Exceptions:
280         '   System.ArgumentNullException:
281         '     source is null.
282         '
283         '   System.InvalidOperationException:
284         '     source contains no elements.
285         '
286         '   System.OverflowException:
287         '     The sum of the elements in the sequence is larger than System.Int64.MaxValue.
288         <Extension>
289         Public Function StandardDeviation(source As IEnumerable(Of Long)) As Double
290             Return source.[Select](Function(x) CDbl(x)).StandardDeviation()
291         End Function
292         '
293         ' Summary:
294         '     Computes the StandardDeviation of a sequence of nullable System.Decimal values that
295         '     are obtained by invoking a transform function on each element of the input
296         '     sequence.
297         '
298         ' Parameters:
299         '   source:
300         '     A sequence of values to calculate the StandardDeviation of.
301         '
302         '   selector:
303         '     A transform function to apply to each element.
304         '
305         ' Type parameters:
306         '   TSource:
307         '     The type of the elements of source.
308         '
309         Returns:
310         '     The StandardDeviation of the sequence of values, or null if the source sequence is
311         '     empty or contains only values that are null.
312         '
313         ' Exceptions:
314         '   System.ArgumentNullException:
315         '     source or selector is null.
316         '
317         '   System.OverflowException:
318         '     The sum of the elements in the sequence is larger than System.Decimal.MaxValue.
319         <Extension>
320         Public Function StandardDeviation(Of TSource)(source As IEnumerable(Of TSource), selector As Func(Of TSource, Decimal?)) As Decimal
321             Return source.[Select](selector).StandardDeviation()
322         End Function
323         '
324         ' Summary:
325         '     Computes the StandardDeviation of a sequence of System.Decimal values that are obtained
326         '     by invoking a transform function on each element of the input sequence.
327         '
328         ' Parameters:
329         '   source:
330         '     A sequence of values that are used to calculate an StandardDeviation.
331         '
332         '   selector:
333         '     A transform function to apply to each element.
334         '
335         ' Type parameters:
336         '   TSource:
337         '     The type of the elements of source.
338         '
339         Returns:
340         '     The StandardDeviation of the sequence of values.
341         '
342         ' Exceptions:
343         '   System.ArgumentNullException:
344         '     source or selector is null.
345         '
346         '   System.InvalidOperationException:
347         '     source contains no elements.
348         '
349         '   System.OverflowException:
350         '     The sum of the elements in the sequence is larger than System.Decimal.MaxValue.
351         <Extension>
352         Public Function StandardDeviation(Of TSource)(source As IEnumerable(Of TSource), selector As Func(Of TSource, Decimal)) As Decimal
353             Return source.[Select](selector).StandardDeviation()
354         End Function
355         '
356         ' Summary:
357         '     Computes the StandardDeviation of a sequence of nullable System.Double values that
358         '     are obtained by invoking a transform function on each element of the input
359         '     sequence.
360         '
361         ' Parameters:
362         '   source:
363         '     A sequence of values to calculate the StandardDeviation of.
364         '
365         '   selector:
366         '     A transform function to apply to each element.
367         '
368         ' Type parameters:
369         '   TSource:
370         '     The type of the elements of source.
371         '
372         Returns:
373         '     The StandardDeviation of the sequence of values, or null if the source sequence is
374         '     empty or contains only values that are null.
375         '
376         ' Exceptions:
377         '   System.ArgumentNullException:
378         '     source or selector is null.
379         <Extension>
380         Public Function StandardDeviation(Of TSource)(source As IEnumerable(Of TSource), selector As Func(Of TSource, Double?)) As Double
381             Return source.[Select](selector).StandardDeviation()
382         End Function
383         '
384         ' Summary:
385         '     Computes the StandardDeviation of a sequence of System.Double values that are obtained
386         '     by invoking a transform function on each element of the input sequence.
387         '
388         ' Parameters:
389         '   source:
390         '     A sequence of values to calculate the StandardDeviation of.
391         '
392         '   selector:
393         '     A transform function to apply to each element.
394         '
395         ' Type parameters:
396         '   TSource:
397         '     The type of the elements of source.
398         '
399         Returns:
400         '     The StandardDeviation of the sequence of values.
401         '
402         ' Exceptions:
403         '   System.ArgumentNullException:
404         '     source or selector is null.
405         '
406         '   System.InvalidOperationException:
407         '     source contains no elements.
408         <Extension>
409         Public Function StandardDeviation(Of TSource)(source As IEnumerable(Of TSource), selector As Func(Of TSource, Double)) As Double
410             Return source.[Select](selector).StandardDeviation()
411         End Function
412         '
413         ' Summary:
414         '     Computes the StandardDeviation of a sequence of nullable System.Single values that
415         '     are obtained by invoking a transform function on each element of the input
416         '     sequence.
417         '
418         ' Parameters:
419         '   source:
420         '     A sequence of values to calculate the StandardDeviation of.
421         '
422         '   selector:
423         '     A transform function to apply to each element.
424         '
425         ' Type parameters:
426         '   TSource:
427         '     The type of the elements of source.
428         '
429         Returns:
430         '     The StandardDeviation of the sequence of values, or null if the source sequence is
431         '     empty or contains only values that are null.
432         '
433         ' Exceptions:
434         '   System.ArgumentNullException:
435         '     source or selector is null.
436         <Extension>
437         Public Function StandardDeviation(Of TSource)(source As IEnumerable(Of TSource), selector As Func(Of TSource, Single?)) As Single
438             Return source.[Select](selector).StandardDeviation()
439         End Function
440         '
441         ' Summary:
442         '     Computes the StandardDeviation of a sequence of System.Single values that are obtained
443         '     by invoking a transform function on each element of the input sequence.
444         '
445         ' Parameters:
446         '   source:
447         '     A sequence of values to calculate the StandardDeviation of.
448         '
449         '   selector:
450         '     A transform function to apply to each element.
451         '
452         ' Type parameters:
453         '   TSource:
454         '     The type of the elements of source.
455         '
456         Returns:
457         '     The StandardDeviation of the sequence of values.
458         '
459         ' Exceptions:
460         '   System.ArgumentNullException:
461         '     source or selector is null.
462         '
463         '   System.InvalidOperationException:
464         '     source contains no elements.
465         <Extension>
466         Public Function StandardDeviation(Of TSource)(source As IEnumerable(Of TSource), selector As Func(Of TSource, Single)) As Single
467             Return source.[Select](selector).StandardDeviation()
468         End Function
469         '
470         ' Summary:
471         '     Computes the StandardDeviation of a sequence of nullable System.Int32 values that are
472         '     obtained by invoking a transform function on each element of the input sequence.
473         '
474         ' Parameters:
475         '   source:
476         '     A sequence of values to calculate the StandardDeviation of.
477         '
478         '   selector:
479         '     A transform function to apply to each element.
480         '
481         ' Type parameters:
482         '   TSource:
483         '     The type of the elements of source.
484         '
485         Returns:
486         '     The StandardDeviation of the sequence of values, or null if the source sequence is
487         '     empty or contains only values that are null.
488         '
489         ' Exceptions:
490         '   System.ArgumentNullException:
491         '     source or selector is null.
492         '
493         '   System.OverflowException:
494         '     The sum of the elements in the sequence is larger than System.Int64.MaxValue.
495         <Extension>
496         Public Function StandardDeviation(Of TSource)(source As IEnumerable(Of TSource), selector As Func(Of TSource, Integer?)) As Double
497             Return source.[Select](selector).StandardDeviation()
498         End Function
499         '
500         ' Summary:
501         '     Computes the StandardDeviation of a sequence of System.Int32 values that are obtained
502         '     by invoking a transform function on each element of the input sequence.
503         '
504         ' Parameters:
505         '   source:
506         '     A sequence of values to calculate the StandardDeviation of.
507         '
508         '   selector:
509         '     A transform function to apply to each element.
510         '
511         ' Type parameters:
512         '   TSource:
513         '     The type of the elements of source.
514         '
515         Returns:
516         '     The StandardDeviation of the sequence of values.
517         '
518         ' Exceptions:
519         '   System.ArgumentNullException:
520         '     source or selector is null.
521         '
522         '   System.InvalidOperationException:
523         '     source contains no elements.
524         '
525         '   System.OverflowException:
526         '     The sum of the elements in the sequence is larger than System.Int64.MaxValue.
527         <Extension>
528         Public Function StandardDeviation(Of TSource)(source As IEnumerable(Of TSource), selector As Func(Of TSource, Integer)) As Double
529             Return source.[Select](selector).StandardDeviation()
530         End Function
531         '
532         ' Summary:
533         '     Computes the StandardDeviation of a sequence of nullable System.Int64 values that are
534         '     obtained by invoking a transform function on each element of the input sequence.
535         '
536         ' Parameters:
537         '   source:
538         '     A sequence of values to calculate the StandardDeviation of.
539         '
540         '   selector:
541         '     A transform function to apply to each element.
542         '
543         ' Type parameters:
544         '   TSource:
545         '     The type of the elements of source.
546         '
547         Returns:
548         '     The StandardDeviation of the sequence of values, or null if the source sequence is
549         '     empty or contains only values that are null.
550         <Extension>
551         Public Function StandardDeviation(Of TSource)(source As IEnumerable(Of TSource), selector As Func(Of TSource, Long?)) As Double
552             Return source.[Select](selector).StandardDeviation()
553         End Function
554         '
555         ' Summary:
556         '     Computes the StandardDeviation of a sequence of System.Int64 values that are obtained
557         '     by invoking a transform function on each element of the input sequence.
558         '
559         ' Parameters:
560         '   source:
561         '     A sequence of values to calculate the StandardDeviation of.
562         '
563         '   selector:
564         '     A transform function to apply to each element.
565         '
566         ' Type parameters:
567         '   TSource:
568         '     The type of the elements of source.
569         '
570         Returns:
571         '     The StandardDeviation of the sequence of values.
572         '
573         ' Exceptions:
574         '   System.ArgumentNullException:
575         '     source or selector is null.
576         '
577         '   System.InvalidOperationException:
578         '     source contains no elements.
579         '
580         '   System.OverflowException:
581         '     The sum of the elements in the sequence is larger than System.Int64.MaxValue.
582         <Extension>
583         Public Function StandardDeviation(Of TSource)(source As IEnumerable(Of TSource), selector As Func(Of TSource, Long)) As Double
584             Return source.[Select](selector).StandardDeviation()
585         End Function
586     End Module
587 End Namespace