Generate and return the square of the Hellinger distance of two univariate (discrete or continuous) distributions.
More...
Generate and return the square of the Hellinger distance of two univariate (discrete or continuous) distributions.
See pm_distanceHellinger for the mathematical definition of the Hellinger distance.
 Parameters

[in]  p  : The vector of the same size as the nonzero size of the input argument q , of the same type and kind as the output hellsq , representing the Probability Mass Function (PMF) of the first distribution in the computation of the squared Hellinger distance.
Alternatively, the input p can be a nonelemental function that takes a scalar of the same type and kind as the output hellsq and returns the output pdf of the same type and kind as x , representing the Probability Density Function (PDF) of the first distribution in the computation of the squared Hellinger distance.
The following illustrates the generic interface of p , function p(x) result(pdf)
real(RKG), intent(in) :: x
real(RKG) :: pdf
end function
where RKG is the kind type parameter of the output hellsq .
The input arguments p and q must be of the same type and kind (and size if they are vectors).

[in]  q  : The vector of the same size as the nonzero size of the input argument p , of the same type and kind as the output hellsq , representing the Probability Mass Function (PMF) of the second distribution in the computation of the squared Hellinger distance.
Alternatively, the input p can be a nonelemental function that takes a scalar of the same type and kind as the output hellsq and returns the output pdf of the same type and kind as x , representing the Probability Density Function (PDF) of the second distribution in the computation of the squared Hellinger distance.
The following illustrates the generic interface of p , function p(x) result(pdf)
real(RKG), intent(in) :: x
real(RKG) :: pdf
end function
where RKG is the kind type parameter of the output hellsq .
The input arguments p and q must be of the same type and kind (and size if they are vectors).

[in]  lb  : The input scalar of type real of the same kind as integral , representing the lower limit of integration.
Set lb = huge(lb) or to the IEEEcompliant negative infinity (lb = getInfNeg(lb)) to imply \(\infty\) as the lower bound of integration.
See also the corresponding argument of isFailedQuad().
(optional, default = getInfNeg(lb). It can be present only if the input arguments p and q are procedures.) 
[in]  ub  : The input scalar of type real of the same kind as integral , representing the upper limit of integration.
Set ub = huge(ub) or to the IEEEcompliant positive infinity (ub = getInfPos(lb)) to imply \(+\infty\) as the upper bound of integration.
See also the corresponding argument of isFailedQuad().
(optional, default = getInfPos(lb). It can be present only if the input arguments p and q are procedures.) 
[out]  failed  : The output scalar of type logical of default kind LK, that is set to .true. if and only if the integration Hellinger fails to converge within the tolerances.
Otherwise, it is set .false. if the integration succeeds with no errors.
See also the corresponding output argument of isFailedQuad().
See also the description of the output argument err of getQuadErr for information on the kinds of integration failures that can happen.
(optional. If missing and the integration fails, the procedure will halt the program by calling error stop .)

[out]  msg  : The output scalar argument of type character of default kind SK of arbitrary length type parameter that is set to a diagnostic message if the integration fails to converge.
A length type parameter of 127 is sufficient to capture all error messages.
If msg has shorter length parameter, the output message will be trimmed from the end, otherwise padded with blanks as necessary.
See also the corresponding argument of isFailedQuad().
(optional. If missing, no diagnostic message will be returned.)

 Returns
hellsq
: The output scalar of

type
real
of kind any supported by the processor (e.g., RK, RK32, RK64, or RK128),
representing the square of the Hellinger distance of the discrete or continuous distributions represented by p
and q
.
Possible calling interfaces ⛓
Generate and return the square of the Hellinger distance of two univariate (discrete or continuous) d...
This module contains classes and procedures for computing the Hellinger statistical distance between ...
 Warning
 The condition
sum(p) == 1
must hold for the corresponding input arguments.
The condition sum(q) == 1
must hold for the corresponding input arguments.
The condition all(0 <= p) .and. all(p <= 1)
must hold for the corresponding input arguments.
The condition all(0 <= q) .and. all(q <= 1)
must hold for the corresponding input arguments.
The condition size(p) == size(q)
must hold for the corresponding input arguments.
This condition is 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. The procedures under this generic interface are always impure
when the input arguments p
and q
are procedures.
Example usage ⛓
14 integer(IK) :: ndim, npnt, nsam, isam
16 type(display_type) :: disp
20 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
21 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
22 call disp%show(
"! Compute the Hellinger distance squared for realvalued PMFs.")
23 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
24 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
30 real(RKG),
allocatable :: p(:), q(:), stepSuccess(:)
37 call disp%show(
"stepSuccess = getRange(1, period)")
41 call disp%show(
"p = exp(getGeomCyclicLogPMF(stepSuccess, probSuccess = .1_RKG, period = period))")
49 call disp%show(
"hellsq = getDisHellSq(p, q)")
58 call disp%show(
"stepSuccess = getRange(1, period)")
62 call disp%show(
"p = exp(getGeomCyclicLogPMF(stepSuccess, probSuccess = .1_RKG, period = period))")
66 call disp%show(
"q = exp(getGeomCyclicLogPMF(stepSuccess, probSuccess = .9_RKG, period = period))")
70 call disp%show(
"hellsq = getDisHellSq(p, q)")
79 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
80 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
81 call disp%show(
"! Compute the Hellinger distance squared for realvalued PDFs.")
82 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
83 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
92 call disp%show(
"hellsq = getDisHellSq(getp, getq)")
97 call disp%show(
"hellsq = getDisHellSq(getp, getq, lb = huge(0._RKG), ub = +huge(0._RKG))")
98 hellsq
= getDisHellSq(getp, getq, lb
= huge(
0._RKG), ub
= +huge(
0._RKG))
107 function getp(x)
result(pdf)
109 real(RKG),
intent(in) :: x
114 function getq(x)
result(pdf)
116 real(RKG),
intent(in) :: x
Generate minimallyspaced character, integer, real sequences or sequences at fixed intervals of size ...
Allocate or resize (shrink or expand) an input allocatable scalar string or array of rank 1....
Generate and return a random positivedefinite (correlation or covariance) matrix using the Gram meth...
Generate and return the natural logarithm of the Probability Mass Function (PMF) of the Cyclic Geomet...
Generate the natural logarithm of probability density function (PDF) of the univariate Normal distrib...
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.
This module contains procedures and generic interfaces for generating ranges of discrete character,...
This module contains procedures and generic interfaces for resizing allocatable arrays of various typ...
This module contains classes and procedures for generating random matrices distributed on the space o...
This module contains classes and procedures for computing various statistical quantities related to t...
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 typeparameters frequently used in the ParaMonte librar...
integer, parameter IK
The default integer kind in the ParaMonte library: int32 in Fortran, c_int32_t in CFortran Interoper...
integer, parameter RKD
The double precision real kind in Fortran mode. On most platforms, this is an 64bit real kind.
integer, parameter SK
The default character kind in the ParaMonte library: kind("a") in Fortran, c_char in CFortran Intero...
integer, parameter RKS
The singleprecision real kind in Fortran mode. On most platforms, this is an 32bit real kind.
Generate and return an object of type display_type.
Example Unix compile command via Intel ifort
compiler ⛓
3ifort fpp standardsemantics 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 /standardsemantics /O3 /I:..\..\..\include main.F90 ..\..\..\lib\libparamonte*.lib /exe:main.exe
Example Unix / MinGW compile command via GNU gfortran
compiler ⛓
3gfortran cpp ffreelinelengthnone O3 Wl,rpath,../../../lib I../../../inc main.F90 ../../../lib/libparamonte* o main.exe
Example output ⛓
12+1.00000000,
+2.00000000,
+3.00000000,
+4.00000000,
+5.00000000,
+6.00000000,
+7.00000000,
+8.00000000,
+9.00000000,
+10.0000000
15+0.153533965,
+0.138180569,
+0.124362521,
+0.111926265,
+0.100733615,
+0.906602591E1,
+0.815942287E1,
+0.734348074E1,
+0.660913289E1,
+0.594821833E1
18+0.153533965,
+0.138180569,
+0.124362521,
+0.111926265,
+0.100733615,
+0.906602591E1,
+0.815942287E1,
+0.734348074E1,
+0.660913289E1,
+0.594821833E1
27+1.00000000,
+2.00000000,
+3.00000000,
+4.00000000,
+5.00000000,
+6.00000000,
+7.00000000,
+8.00000000,
+9.00000000,
+10.0000000
30+0.153533965,
+0.138180569,
+0.124362521,
+0.111926265,
+0.100733615,
+0.906602591E1,
+0.815942287E1,
+0.734348074E1,
+0.660913289E1,
+0.594821833E1
33+0.899999976,
+0.900000185E1,
+0.900000334E2,
+0.900000334E3,
+0.900000305E4,
+0.900000759E5,
+0.900000259E6,
+0.900002348E7,
+0.900001940E8,
+0.900001462E9
50hellsq
= getDisHellSq(getp, getq, lb
= huge(
0._RKG), ub
= +huge(
0._RKG))
 Test:
 test_pm_distanceHellinger
 Todo:
 Critical Priority: The runtime checks for the complex input
invCov
must be implemented.
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:
 Amir Shahmoradi, Monday March 6, 2017, 3:22 pm, Institute for Computational Engineering and Sciences (ICES), The University of Texas at Austin.
Definition at line 274 of file pm_distanceHellinger.F90.