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