Return the variance of an input (weighted) sample of type complex
or real
of shape (nsam)
or (ndim, nsam)
or (nsam, ndim)
where ndim
is the number of data dimensions (the number of data attributes) and nsam
is the number of data points.
See the documentation of the parent module pm_sampleVar for algorithmic details and variance definitions.
- Parameters
-
[out] | var | : The output object of rank rank(sample) - 1 of type real of the same kind as the input sample representing its variance:
-
If
sample is a vector, the output var must be a scalar.
-
If
sample is a matrix, the output var must be a vector of size ndim = size(sample, 3 - dim) .
|
[in] | mean | : The input scalar or contiguous vector of shape (ndim) of the same type and kind as the input sample containing the sample mean.
-
If the input
sample is a 1D array, then mean must be a scalar.
-
If the input
sample is a 2D array, then mean must be a vector of size ndim = size(sample, 3 - dim) (i.e., computed along the specified input dimension dim ).
(optional. default = 0. or getFilled(0., ndim) depending on the rank of the input sample and value of dim .) |
[in] | sample | : The input contiguous array of shape (nsam) , (ndim, nsam) , or (nsam, ndim) of,
-
type
complex of kind any supported by the processor (e.g., CK, CK32, CK64, or CK128),
-
type
real of kind any supported by the processor (e.g., RK, RK32, RK64, or RK128),
containing the sample comprised of nsam observations each with ndim attributes.
If sample is a matrix, then the direction along which variance is computed is dictated by the input argument dim .
|
[in] | dim | : The input scalar integer of default kind IK representing the dimension (1 or 2 ) of the input sample along which the mean must be computed.
-
If
dim = 1 , the input sample of rank 2 is assumed to have the shape (nsam, ndim) .
-
If
dim = 2 , the input sample of rank 2 is assumed to have the shape (ndim, nsam) .
The input dim must always be 1 or missing for an input sample of rank 1 .
(optional. If missing, the variance of the whole input sample is computed.) |
[in] | weight | : The input contiguous vector of length nsam of
-
type
integer of default kind IK, or
-
type
real of the same kind as the input sample ,
containing the corresponding weights of individual nsam observations in sample .
(optional. default = getFilled(1, size(sample, dim)) if dim is present, or getFilled(1, size(sample)) if dim is missing.) |
[in] | weisum | : The input scalar of the same type and kind as the input weight containing sum(weight) .
This quantity is also a byproduct of computing the mean of a sample and is automatically returned by setMean().
(optional. It must be present if and only if the input argument weight is also present.) |
[in] | correction | : The input scalar object that can be the following:
-
The constant fweight or an object of type fweight implying a bias correction based on the assumption of frequency weights for the sample observations, even if the
weight argument is missing.
This is the most popular type of correction, also known as the Bessel correction.
-
The constant rweight or an object of type rweight_type implying a bias correction based on the assumption of reliability weights for the sample observations.
(optional. If missing, no bias-correction will be applied to the output var .) |
Possible calling interfaces ⛓
call setVar(var, sample(
1 : nsam))
call setVar(var, mean, sample(
1 : nsam))
call setVar(var, sample(
1 : nsam), dim)
call setVar(var, mean, sample(
1 : nsam), dim)
call setVar(var, sample(
1 : nsam), weight(
1 : nsam))
call setVar(var, mean, sample(
1 : nsam), weight(
1 : nsam), weisum)
call setVar(var, sample(
1 : nsam), dim, weight(
1 : nsam))
call setVar(var, mean, sample(
1 : nsam), dim, weight(
1 : nsam), weisum)
call setVar(var(
1 :
size(sample,
3 - dim)), sample(:,:), dim)
call setVar(var(
1 :
size(sample,
3 - dim)), mean(
1 :
size(sample,
3 - dim)), sample(:,:), dim)
call setVar(var(
1 :
size(sample,
3 - dim)), sample(:,:), dim, weight(
1 :
size(sample, dim)))
call setVar(var(
1 :
size(sample,
3 - dim)), mean(
1 :
size(sample,
3 - dim)), sample(:,:), dim, weight(
1 :
size(sample, dim)), weisum)
call setVar(var, mean, sample(:,:))
call setVar(var, sample(:,:), weight(
1 :
size(sample)))
call setVar(var, mean, sample(:,:), dim, weight(
1 :
size(sample)), weisum)
Return the variance of an input (weighted) sample of type complex or real of shape (nsam) or (ndim,...
This module contains classes and procedures for computing the properties related to the covariance ma...
- Warning
- The condition
0 < sum(weight)
must hold for the corresponding input arguments.
The condition all(0. <= weight)
must hold for the corresponding input arguments.
The condition 1 < size(sample, dim)
must hold for the corresponding input arguments.
The condition 0 < size(sample, 3 - dim)
must hold for the corresponding input arguments.
The condition 1 <= dim .and. dim <= rank(sample)
must hold for the corresponding input arguments.
The condition size(sample, 3 - dim) == size(var)
must hold for the corresponding input arguments.
The condition size(sample, 3 - dim) == size(mean)
must hold for the corresponding input arguments.
The condition size(sample, dim) == size(weight)
must hold for the corresponding input arguments.
These conditions are verified only if the library is built with the preprocessor macro CHECK_ENABLED=1
.
-
The
pure
procedure(s) documented herein become impure
when the ParaMonte library is compiled with preprocessor macro CHECK_ENABLED=1
.
By default, these procedures are pure
in release
build and impure
in debug
and testing
builds.
- Note
- Note the effects of bias-correction in computing the variance become noticeable only for very sample sample sizes (i.e., when
nsam
is small).
-
For a one-dimensional
sample
, one can also use the concise Fortran syntax to achieve the same goal as with the interface var = setVar(sample(:), mean, correction)
with integer weight
:
mean = sum(sample) / size(sample)
var = sum( (sample-mean)**2 ) / (size(sample) - 1)
But the above concise version will be likely slightly slower as it potentially involves more loops.
-
For a two or higher-dimensional
sample
, if the variance is to be computed for the entire sample
(as opposed to computing it along a particular dimension), simply pass reshape(sample, shape = size(sample))
to the appropriate setVar interface.
Alternatively, a 1D pointer of the same size as the multidimensional sample can be passed to the procedure.
- See also
- getVar
setVar
getMean
setMean
setVarMean
getShifted
setShifted
Example usage ⛓
18 type(display_type) :: disp
22 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
23 call disp%show(
"!Compute the variance of a 1-D sample.")
24 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
28 real(TKG) :: var, mean
29 real(TKG),
allocatable :: sample(:)
30 call disp%show(
"sample = getLinSpace(1._TKG, 9._TKG, 5_IK)")
34 call disp%show(
"mean = getMean(sample)")
38 call disp%show(
"call setVar(var, mean, sample)")
39 call setVar(var, mean, sample)
42 call disp%show(
"call setVar(var, sample - mean)")
43 call setVar(var, sample
- mean)
46 call disp%show(
"call setVar(var, mean, sample, dim = 1_IK)")
47 call setVar(var, mean, sample,
dim = 1_IK)
50 call disp%show(
"call setVar(var, sample - mean, dim = 1_IK)")
51 call setVar(var, sample
- mean,
dim = 1_IK)
60 complex(TKG),
allocatable :: sample(:)
61 call disp%show(
"sample = cmplx(getLinSpace(1., 9., 5_IK), -getLinSpace(1., 9., 5_IK), TKG)")
65 call disp%show(
"mean = getMean(sample)")
69 call disp%show(
"call setVar(var, mean, sample)")
70 call setVar(var, mean, sample)
73 call disp%show(
"call setVar(var, sample - mean)")
74 call setVar(var, sample
- mean)
77 call disp%show(
"call setVar(var, mean, sample, dim = 1_IK)")
78 call setVar(var, mean, sample,
dim = 1_IK)
81 call disp%show(
"call setVar(var, sample - mean, dim = 1_IK)")
82 call setVar(var, sample
- mean,
dim = 1_IK)
89 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
90 call disp%show(
"!Compute the variance of a 1-D weighted sample.")
91 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
95 real(TKG) :: var, weisum
96 real(TKG),
allocatable :: weight(:)
97 real(TKG),
allocatable :: sample(:)
99 call disp%show(
"sample = getLinSpace(1._TKG, 9._TKG, 5_IK)")
103 call disp%show(
"weight = getLinSpace(1._TKG, 9._TKG, size(sample, kind = IK))")
104 weight
= getLinSpace(
1._TKG,
9._TKG,
size(sample,
kind = IK))
107 call disp%show(
"call setMean(mean, sample, weight, weisum)")
108 call setMean(mean, sample, weight, weisum)
111 call disp%show(
"call setVar(var, mean, sample, weight, weisum)")
112 call setVar(var, mean, sample, weight, weisum)
115 call disp%show(
"call setVar(var, sample - mean, weight, weisum)")
116 call setVar(var, sample
- mean, weight, weisum)
119 call disp%show(
"call setVar(var, mean, sample, 1_IK, weight, weisum)")
120 call setVar(var, mean, sample,
1_IK, weight, weisum)
123 call disp%show(
"call setVar(var, sample - mean, 1_IK, weight, weisum)")
124 call setVar(var, sample
- mean,
1_IK, weight, weisum)
131 real(TKG) :: var, weisum
132 real(TKG),
allocatable :: weight(:)
133 complex(TKG),
allocatable :: sample(:)
135 call disp%show(
"sample = cmplx(getLinSpace(1., 9., 5_IK), -getLinSpace(1., 9., 5_IK), TKG)")
139 call disp%show(
"weight = getLinSpace(1._TKG, 9._TKG, size(sample, kind = IK))")
140 weight
= getLinSpace(
1._TKG,
9._TKG,
size(sample,
kind = IK))
143 call disp%show(
"call setMean(mean, sample, weight, weisum)")
144 call setMean(mean, sample, weight, weisum)
147 call disp%show(
"call setVar(var, mean, sample, weight, weisum)")
148 call setVar(var, mean, sample, weight, weisum)
151 call disp%show(
"call setVar(var, sample - mean, weight, weisum)")
152 call setVar(var, sample
- mean, weight, weisum)
155 call disp%show(
"call setVar(var, mean, sample, 1_IK, weight, weisum)")
156 call setVar(var, mean, sample,
1_IK, weight, weisum)
159 call disp%show(
"call setVar(var, sample - mean, 1_IK, weight, weisum)")
160 call setVar(var, sample
- mean,
1_IK, weight, weisum)
167 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
168 call disp%show(
"!Compute the variance of a 2-D array.")
169 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
173 real(TKG),
allocatable :: var(:), mean(:), sample(:,:)
175 call disp%show(
"sample = getUnifRand(1._TKG, 9._TKG, 4_IK, 5_IK)")
179 call disp%show(
"mean = [getMean(sample)]")
183 call disp%show(
"call setResized(var, size(mean, 1, IK))")
185 call disp%show(
"call setVar(var(1), mean(1), sample)")
186 call setVar(var(
1), mean(
1), sample)
189 call disp%show(
"call setVar(var(1), sample - mean(1))")
190 call setVar(var(
1), sample
- mean(
1))
195 call disp%show(
"dim ! The observations axis.")
197 call disp%show(
"sample = getUnifRand(1._TKG, 9._TKG, 4_IK, 5_IK)")
201 call disp%show(
"mean = getMean(sample, dim)")
205 call disp%show(
"call setResized(var, size(mean, 1, IK))")
207 call disp%show(
"call setVar(var, mean, sample, dim)")
208 call setVar(var, mean, sample, dim)
211 call disp%show(
"call setVar(var, getShifted(sample, dim, -mean), dim)")
220 real(TKG),
allocatable :: var(:)
221 complex(TKG),
allocatable :: mean(:), sample(:,:)
223 call disp%show(
"sample = cmplx(getUnifRand(1., 9., 4_IK, 5_IK), -getUnifRand(1., 9., 4_IK, 5_IK), TKG)")
227 call disp%show(
"mean = [getMean(sample)]")
231 call disp%show(
"call setResized(var, size(mean, 1, IK))")
233 call disp%show(
"call setVar(var(1), mean(1), sample)")
234 call setVar(var(
1), mean(
1), sample)
237 call disp%show(
"call setVar(var(1), sample - mean(1))")
238 call setVar(var(
1), sample
- mean(
1))
243 call disp%show(
"dim ! The observations axis.")
245 call disp%show(
"sample = getUnifRand(1._TKG, 9._TKG, 4_IK, 5_IK)")
249 call disp%show(
"mean = getMean(sample, dim)")
253 call disp%show(
"call setResized(var, size(mean, 1, IK))")
255 call disp%show(
"call setVar(var, mean, sample, dim)")
256 call setVar(var, mean, sample, dim)
259 call disp%show(
"call setVar(var, getShifted(sample, dim, -mean), dim)")
Allocate or resize (shrink or expand) an input allocatable scalar string or array of rank 1....
Generate count evenly spaced points over the interval [x1, x2] if x1 < x2, or [x2,...
Generate and return a scalar or a contiguous array of rank 1 of length s1 of randomly uniformly distr...
This is a generic method of the derived type display_type with pass attribute.
This is a generic method of the derived type display_type with pass attribute.
Generate and return the (weighted) mean of an input sample of nsam observations with ndim = 1 or 2 at...
Return the (weighted) mean of a pair of time series or of an input sample of nsam observations with n...
Generate a sample of shape (nsam), or (ndim, nsam) or (nsam, ndim) that is shifted by the specified i...
This module contains procedures and generic interfaces for resizing allocatable arrays of various typ...
This module contains procedures and generic interfaces for generating arrays with linear or logarithm...
This module contains classes and procedures for computing various statistical quantities related to t...
This module contains classes and procedures for input/output (IO) or generic display operations on st...
type(display_type) disp
This is a scalar module variable an object of type display_type for general display.
This module defines the relevant Fortran kind type-parameters frequently used in the ParaMonte librar...
integer, parameter RK
The default real kind in the ParaMonte library: real64 in Fortran, c_double in C-Fortran Interoperati...
integer, parameter LK
The default logical kind in the ParaMonte library: kind(.true.) in Fortran, kind(....
integer, parameter IK
The default integer kind in the ParaMonte library: int32 in Fortran, c_int32_t in C-Fortran Interoper...
integer, parameter SK
The default character kind in the ParaMonte library: kind("a") in Fortran, c_char in C-Fortran Intero...
integer, parameter RKS
The single-precision real kind in Fortran mode. On most platforms, this is an 32-bit real kind.
This module contains classes and procedures for computing the properties related to the covariance ma...
This module contains classes and procedures for computing the first moment (i.e., the statistical mea...
This module contains classes and procedures for shifting univariate or multivariate samples by arbitr...
Generate and return an object of type display_type.
Example Unix compile command via Intel ifort
compiler ⛓
3ifort -fpp -standard-semantics -O3 -Wl,-rpath,../../../lib -I../../../inc main.F90 ../../../lib/libparamonte* -o main.exe
Example Windows Batch compile command via Intel ifort
compiler ⛓
2set PATH=..\..\..\lib;%PATH%
3ifort /fpp /standard-semantics /O3 /I:..\..\..\include main.F90 ..\..\..\lib\libparamonte*.lib /exe:main.exe
Example Unix / MinGW compile command via GNU gfortran
compiler ⛓
3gfortran -cpp -ffree-line-length-none -O3 -Wl,-rpath,../../../lib -I../../../inc main.F90 ../../../lib/libparamonte* -o main.exe
Example output ⛓
8+1.00000000,
+3.00000000,
+5.00000000,
+7.00000000,
+9.00000000
12call setVar(var, mean, sample)
15call setVar(var, sample
- mean)
18call setVar(var, mean, sample,
dim = 1_IK)
21call setVar(var, sample
- mean,
dim = 1_IK)
27(
+1.00000000,
-1.00000000), (
+3.00000000,
-3.00000000), (
+5.00000000,
-5.00000000), (
+7.00000000,
-7.00000000), (
+9.00000000,
-9.00000000)
30(
+5.00000000,
-5.00000000)
31call setVar(var, mean, sample)
34call setVar(var, sample
- mean)
37call setVar(var, mean, sample,
dim = 1_IK)
40call setVar(var, sample
- mean,
dim = 1_IK)
51+1.00000000,
+3.00000000,
+5.00000000,
+7.00000000,
+9.00000000
54+1.00000000,
+3.00000000,
+5.00000000,
+7.00000000,
+9.00000000
55call setMean(mean, sample, weight, weisum)
58call setVar(var, mean, sample, weight, weisum)
61call setVar(var, sample
- mean, weight, weisum)
64call setVar(var, mean, sample,
1_IK, weight, weisum)
67call setVar(var, sample
- mean,
1_IK, weight, weisum)
73(
+1.00000000,
-1.00000000), (
+3.00000000,
-3.00000000), (
+5.00000000,
-5.00000000), (
+7.00000000,
-7.00000000), (
+9.00000000,
-9.00000000)
76+1.00000000,
+3.00000000,
+5.00000000,
+7.00000000,
+9.00000000
77call setMean(mean, sample, weight, weisum)
79(
+6.59999990,
-6.59999990)
80call setVar(var, mean, sample, weight, weisum)
83call setVar(var, sample
- mean, weight, weisum)
86call setVar(var, mean, sample,
1_IK, weight, weisum)
89call setVar(var, sample
- mean,
1_IK, weight, weisum)
101+2.71703911,
+1.90368414,
+1.32883120,
+5.47990227,
+1.07558727
102+5.27761221,
+6.40013695,
+7.19426203,
+3.18509865,
+6.45640564
103+2.39769697,
+8.46323586,
+8.61032963,
+7.40628099,
+5.01460791
104+7.15812492,
+3.05176306,
+4.58940792,
+8.93941402,
+4.18581438
109call setVar(var(
1), mean(
1), sample)
112call setVar(var(
1), sample
- mean(
1))
120+3.22250748,
+6.11698389,
+4.57533836,
+3.42462349,
+4.85922766
121+6.90965748,
+7.70066786,
+5.06332016,
+8.86573410,
+4.08291674
122+8.18947506,
+2.25815773,
+3.66551542,
+8.01496506,
+5.62089586
123+2.26119757,
+6.84917879,
+2.91387892,
+8.80748081,
+4.61304379
126+5.14570951,
+5.73124695,
+4.05451345,
+7.27820110,
+4.79402065
128call setVar(var, mean, sample, dim)
130+6.09878349,
+4.33488274,
+0.685329080,
+5.06295967,
+0.306598991
133+6.09878349,
+4.33488274,
+0.685329080,
+5.06295967,
+0.306598991
139+8.51453972,
+7.88772535,
+2.62997055,
+6.84687710,
+4.23841095
140+3.65238857,
+2.49350548,
+3.06874847,
+2.79478693,
+3.33955336
141+5.44186354,
+2.67548895,
+4.18407011,
+5.39346647,
+2.33069515
142+7.89356852,
+5.03360510,
+7.06112719,
+6.44326735,
+2.65410471
145+6.02350473,
+3.06979680,
+4.00511694,
+5.81713438
147call setVar(var, mean, sample, dim)
149+5.01222992,
+0.163984999,
+1.71907556,
+3.37396312
152+5.01222992,
+0.163984999,
+1.71907556,
+3.37396312
157(
+6.14398432,
-8.39464855), (
+7.88775969,
-1.60670996), (
+2.53564548,
-7.71318436), (
+8.48316765,
-5.85247374), (
+4.47624969,
-8.86066818)
158(
+6.65974998,
-4.67615032), (
+4.58791685,
-4.83163786), (
+3.10054541,
-1.79810762), (
+3.64470673,
-4.16019058), (
+5.17429781,
-8.11873150)
159(
+1.26751041,
-4.88276339), (
+2.01259136,
-4.04997873), (
+5.23456144,
-4.15865183), (
+3.99455547,
-6.33466005), (
+2.21973753,
-4.27993345)
160(
+1.62564850,
-7.59197140), (
+5.52194118,
-5.92619562), (
+3.84767771,
-3.87349224), (
+5.21128416,
-5.32844114), (
+5.89394045,
-1.81376934)
163(
+4.47617340,
-5.21261787)
165call setVar(var(
1), mean(
1), sample)
168call setVar(var(
1), sample
- mean(
1))
176(
+1.10781956,
+0.00000000), (
+1.47066021,
+0.00000000), (
+6.96110868,
+0.00000000), (
+3.95208883,
+0.00000000), (
+4.51551914,
+0.00000000)
177(
+6.00105238,
+0.00000000), (
+5.03672600,
+0.00000000), (
+3.19750690,
+0.00000000), (
+4.92277765,
+0.00000000), (
+6.76956654,
+0.00000000)
178(
+1.80925131,
+0.00000000), (
+6.25042915,
+0.00000000), (
+7.18962479,
+0.00000000), (
+4.07477617,
+0.00000000), (
+6.73965216,
+0.00000000)
179(
+1.10488749,
+0.00000000), (
+7.03111458,
+0.00000000), (
+1.55909395,
+0.00000000), (
+8.41371250,
+0.00000000), (
+5.19112921,
+0.00000000)
182(
+2.50575256,
+0.00000000), (
+4.94723225,
+0.00000000), (
+4.72683334,
+0.00000000), (
+5.34083843,
+0.00000000), (
+5.80396700,
+0.00000000)
184call setVar(var, mean, sample, dim)
186+4.15471888,
+4.53386259,
+5.85768509,
+3.28721738,
+0.960889220
189+4.15471888,
+4.53386259,
+5.85768509,
+3.28721738,
+0.960889220
195(
+4.75300598,
+0.00000000), (
+6.26923943,
+0.00000000), (
+8.54520607,
+0.00000000), (
+7.73336887,
+0.00000000), (
+1.98672628,
+0.00000000)
196(
+2.29595804,
+0.00000000), (
+1.94308376,
+0.00000000), (
+7.00429344,
+0.00000000), (
+5.49568605,
+0.00000000), (
+8.07337093,
+0.00000000)
197(
+3.80389690,
+0.00000000), (
+1.64173841,
+0.00000000), (
+8.37919044,
+0.00000000), (
+2.52583790,
+0.00000000), (
+1.65950394,
+0.00000000)
198(
+7.88264608,
+0.00000000), (
+5.66684961,
+0.00000000), (
+4.84809113,
+0.00000000), (
+1.88392735,
+0.00000000), (
+2.13110781,
+0.00000000)
201(
+5.85750914,
+0.00000000), (
+4.96247864,
+0.00000000), (
+3.60203338,
+0.00000000), (
+4.48252439,
+0.00000000)
203call setVar(var, mean, sample, dim)
205+5.42299461,
+6.07160902,
+6.32727003,
+5.07579184
208+5.42299461,
+6.07160902,
+6.32727003,
+5.07579184
- Test:
- test_pm_sampleVar
- Todo:
- Normal Priority: The examples of this generic interface need to be extended to weighted samples.
- Todo:
- Very Low Priority: The functionality of this interface can be expanded in the future to include the computation of the variance of higher dimensional input
sample
and whole sample
input arrays of arbitrary shape.
Final Remarks ⛓
If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.
-
If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
-
If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.
This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.
- Copyright
- Computational Data Science Lab
- Author:
- Fatemeh Bagheri, Monday 02:15 AM, September 27, 2021, Dallas, TX
Definition at line 2618 of file pm_sampleVar.F90.