ParaMonte Fortran 2.0.0
Parallel Monte Carlo and Machine Learning Library
See the latest version documentation.
pm_distanceBhat::getDisBhat Interface Reference

Generate and return the Bhattacharyya distance of two univariate (discrete or continuous) distributions. More...

Detailed Description

Generate and return the Bhattacharyya distance of two univariate (discrete or continuous) distributions.

See pm_distanceBhat for the mathematical definition of the Bhattacharyya distance.

Parameters
[in]p: The vector of the same size as the non-zero size of the input argument q, of the same type and kind as the output bhat, representing the Probability Mass Function (PMF) of the first distribution in the computation of the squared Bhattacharyya distance.
Alternatively, the input p can be a non-elemental function that takes a scalar of the same type and kind as the output bhat 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 Bhattacharyya 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 bhat.
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 non-zero size of the input argument p, of the same type and kind as the output bhat, representing the Probability Mass Function (PMF) of the second distribution in the computation of the squared Bhattacharyya distance.
Alternatively, the input p can be a non-elemental function that takes a scalar of the same type and kind as the output bhat 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 Bhattacharyya 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 bhat.
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 IEEE-compliant 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 IEEE-compliant 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 Bhattacharyya 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
bhat : The output scalar of
  1. type real of kind any supported by the processor (e.g., RK, RK32, RK64, or RK128),
representing the Bhattacharyya distance of the discrete or continuous distributions represented by p and q.


Possible calling interfaces

! discrete distributions.
bhat = getDisBhat(p(:), q(:))
! continuous univariate distributions.
bhat = getDisBhat(p, q, lb = lb, ub = ub)
Generate and return the Bhattacharyya distance of two univariate (discrete or continuous) distributio...
This module contains classes and procedures for computing the Bhattacharyya statistical distance betw...
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

1program example
2
3 use pm_kind, only: SK, IK
4 use pm_arrayRange, only: getRange
9 use pm_distCov, only: getCovRand
10 use pm_io, only: display_type
11
12 implicit none
13
14 integer(IK) :: ndim, npnt, nsam, isam
15
16 type(display_type) :: disp
17 disp = display_type(file = "main.out.F90")
18
19 call disp%skip()
20 call disp%show("!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
21 call disp%show("!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
22 call disp%show("! Compute the Bhattacharyya distance squared for real-valued PMFs.")
23 call disp%show("!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
24 call disp%show("!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
25 call disp%skip()
26
27 block
28
29 use pm_kind, only: RKG => RKS ! all other real kinds are also supported.
30 real(RKG), allocatable :: p(:), q(:), stepSuccess(:)
31 integer(IK) :: period
32 real(RKG) :: bhat
33
34 call disp%skip()
35 call disp%show("period = 10;")
36 period = 10;
37 call disp%show("stepSuccess = getRange(1, period)")
38 stepSuccess = getRange(1, period)
39 call disp%show("stepSuccess")
40 call disp%show( stepSuccess )
41 call disp%show("p = exp(getGeomCyclicLogPMF(stepSuccess, probSuccess = .1_RKG, period = period))")
42 p = exp(getGeomCyclicLogPMF(stepSuccess, probSuccess = .1_RKG, period = period))
43 call disp%show("p")
44 call disp%show( p )
45 call disp%show("q = p")
46 q = p
47 call disp%show("q")
48 call disp%show( q )
49 call disp%show("bhat = getDisBhat(p, q)")
50 bhat = getDisBhat(p, q)
51 call disp%show("bhat")
52 call disp%show( bhat )
53 call disp%skip()
54
55 call disp%skip()
56 call disp%show("period = 10;")
57 period = 10;
58 call disp%show("stepSuccess = getRange(1, period)")
59 stepSuccess = getRange(1, period)
60 call disp%show("stepSuccess")
61 call disp%show( stepSuccess )
62 call disp%show("p = exp(getGeomCyclicLogPMF(stepSuccess, probSuccess = .1_RKG, period = period))")
63 p = exp(getGeomCyclicLogPMF(stepSuccess, probSuccess = .1_RKG, period = period))
64 call disp%show("p")
65 call disp%show( p )
66 call disp%show("q = exp(getGeomCyclicLogPMF(stepSuccess, probSuccess = .9_RKG, period = period))")
67 q = exp(getGeomCyclicLogPMF(stepSuccess, probSuccess = .9_RKG, period = period))
68 call disp%show("q")
69 call disp%show( q )
70 call disp%show("bhat = getDisBhat(p, q)")
71 bhat = getDisBhat(p, q)
72 call disp%show("bhat")
73 call disp%show( bhat )
74 call disp%skip()
75
76 end block
77
78 call disp%skip()
79 call disp%show("!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
80 call disp%show("!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
81 call disp%show("! Compute the Bhattacharyya distance squared for real-valued PDFs.")
82 call disp%show("!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
83 call disp%show("!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
84 call disp%skip()
85
86 block
87
88 use pm_kind, only: RKG => RKD ! all other real kinds are also supported.
89 real(RKG) :: bhat
90
91 call disp%skip()
92 call disp%show("bhat = getDisBhat(getp, getq)")
93 bhat = getDisBhat(getp, getq)
94 call disp%show("bhat")
95 call disp%show( bhat )
96 call disp%skip()
97 call disp%show("bhat = getDisBhat(getp, getq, lb = -huge(0._RKG), ub = +huge(0._RKG))")
98 bhat = getDisBhat(getp, getq, lb = -huge(0._RKG), ub = +huge(0._RKG))
99 call disp%show("bhat")
100 call disp%show( bhat )
101 call disp%skip()
102
103 end block
104
105contains
106
107 function getp(x) result(pdf)
108 use pm_kind, only: RKG => RKD ! all other real kinds are also supported.
109 real(RKG), intent(in) :: x
110 real(RKG) :: pdf
111 pdf = exp(getNormLogPDF(x))
112 end function
113
114 function getq(x) result(pdf)
115 use pm_kind, only: RKG => RKD ! all other real kinds are also supported.
116 real(RKG), intent(in) :: x
117 real(RKG) :: pdf
118 pdf = exp(getNormLogPDF(x, mu = 1._RKG))
119 end function
120
121end program example
Generate minimally-spaced 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 positive-definite (correlation or covariance) matrix using the Gram meth...
Definition: pm_distCov.F90:394
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.
Definition: pm_io.F90:11726
This is a generic method of the derived type display_type with pass attribute.
Definition: pm_io.F90:11508
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...
Definition: pm_distCov.F90:72
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...
Definition: pm_io.F90:252
type(display_type) disp
This is a scalar module variable an object of type display_type for general display.
Definition: pm_io.F90:11393
This module defines the relevant Fortran kind type-parameters frequently used in the ParaMonte librar...
Definition: pm_kind.F90:268
integer, parameter IK
The default integer kind in the ParaMonte library: int32 in Fortran, c_int32_t in C-Fortran Interoper...
Definition: pm_kind.F90:540
integer, parameter RKD
The double precision real kind in Fortran mode. On most platforms, this is an 64-bit real kind.
Definition: pm_kind.F90:568
integer, parameter SK
The default character kind in the ParaMonte library: kind("a") in Fortran, c_char in C-Fortran Intero...
Definition: pm_kind.F90:539
integer, parameter RKS
The single-precision real kind in Fortran mode. On most platforms, this is an 32-bit real kind.
Definition: pm_kind.F90:567
Generate and return an object of type display_type.
Definition: pm_io.F90:10282

Example Unix compile command via Intel ifort compiler
1#!/usr/bin/env sh
2rm main.exe
3ifort -fpp -standard-semantics -O3 -Wl,-rpath,../../../lib -I../../../inc main.F90 ../../../lib/libparamonte* -o main.exe
4./main.exe

Example Windows Batch compile command via Intel ifort compiler
1del main.exe
2set PATH=..\..\..\lib;%PATH%
3ifort /fpp /standard-semantics /O3 /I:..\..\..\include main.F90 ..\..\..\lib\libparamonte*.lib /exe:main.exe
4main.exe

Example Unix / MinGW compile command via GNU gfortran compiler
1#!/usr/bin/env sh
2rm main.exe
3gfortran -cpp -ffree-line-length-none -O3 -Wl,-rpath,../../../lib -I../../../inc main.F90 ../../../lib/libparamonte* -o main.exe
4./main.exe

Example output
1
2!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
4! Compute the Bhattacharyya distance squared for real-valued PMFs.
5!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
6!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
7
8
9period = 10;
10stepSuccess = getRange(1, period)
11stepSuccess
12+1.00000000, +2.00000000, +3.00000000, +4.00000000, +5.00000000, +6.00000000, +7.00000000, +8.00000000, +9.00000000, +10.0000000
13p = exp(getGeomCyclicLogPMF(stepSuccess, probSuccess = .1_RKG, period = period))
14p
15+0.153533965, +0.138180569, +0.124362521, +0.111926265, +0.100733615, +0.906602591E-1, +0.815942287E-1, +0.734348074E-1, +0.660913289E-1, +0.594821833E-1
16q = p
17q
18+0.153533965, +0.138180569, +0.124362521, +0.111926265, +0.100733615, +0.906602591E-1, +0.815942287E-1, +0.734348074E-1, +0.660913289E-1, +0.594821833E-1
19bhat = getDisBhat(p, q)
20bhat
21+0.178813949E-6
22
23
24period = 10;
25stepSuccess = getRange(1, period)
26stepSuccess
27+1.00000000, +2.00000000, +3.00000000, +4.00000000, +5.00000000, +6.00000000, +7.00000000, +8.00000000, +9.00000000, +10.0000000
28p = exp(getGeomCyclicLogPMF(stepSuccess, probSuccess = .1_RKG, period = period))
29p
30+0.153533965, +0.138180569, +0.124362521, +0.111926265, +0.100733615, +0.906602591E-1, +0.815942287E-1, +0.734348074E-1, +0.660913289E-1, +0.594821833E-1
31q = exp(getGeomCyclicLogPMF(stepSuccess, probSuccess = .9_RKG, period = period))
32q
33+0.899999976, +0.900000185E-1, +0.900000334E-2, +0.900000334E-3, +0.900000305E-4, +0.900000759E-5, +0.900000259E-6, +0.900002348E-7, +0.900001940E-8, +0.900001462E-9
34bhat = getDisBhat(p, q)
35bhat
36+0.632928014
37
38
39!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
40!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
41! Compute the Bhattacharyya distance squared for real-valued PDFs.
42!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
43!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
44
45
46bhat = getDisBhat(getp, getq)
47bhat
48+0.12500000000000006
49
50bhat = getDisBhat(getp, getq, lb = -huge(0._RKG), ub = +huge(0._RKG))
51bhat
52+0.12500000000000006
53
54
Test:
test_pm_distanceBhat
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.

  1. 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.
  2. 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.

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 249 of file pm_distanceBhat.F90.


The documentation for this interface was generated from the following file: