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