lmomco (version 1.7.3)

cdfkmu: Cumulative Distribution Function of the Kappa-Mu Distribution

Description

This function computes the cumulative probability or nonexceedance probability of the Kappa-Mu ($\kappa:\mu$) distribution given parameters ($\kappa$ and $\mu$) of the distribution computed by parkmu. The cumulative distribution function of the distribution is complex and numerical integration of the probability density function is used.Alternatively, the cumulative distribution function may be defined in terms of the Marcum Q function or $$F(x) = 1 - Q_\nu\biggl(\sqrt{2\kappa\mu}, x\sqrt{2(1+\kappa)\mu}\biggr)$$ where $F(x)$ is the nonexceedance probability for quantile $x$ and $Q_v(a,b)$ is the Marcum Q function defined by $$Q_\nu(a,b) = \frac{1}{\alpha^{\nu-1}}\int_b^\infty t^\nu \times \mathrm{exp}(-(t^2 + a^2)/2) \times \mathrm{I}_{\nu-1}(at)\; \mathrm{d}t$$ which can be numerically difficult to work with and particularly so with real number values for $\nu$. Following an apparent breakthrough(?) by Shi (2012), $\nu$ can be written as $\nu = n + \Delta$ where $n$ is an integer and $0 < \Delta \le 1$. The author of lmomco refers to this alternative formulation as the delta nu method. The Marcum Q function for $\nu > 0$ ($n = 1,2,3, \cdots)$ is $$Q_\nu(a,b) = Q_\Delta(a,b) + \mathrm{exp}(-(a^2 + b^2)/2) \times \sum_{i=0}^{n-1}\biggl(\frac{b}{a}\biggr)^{i+\Delta} \mathrm{I}_{i+\Delta}(ab)$$ and the function for $\nu \le 0$ ($n=-1,-2,-3,\cdots$) is $$Q_\nu(a,b) = Q_\Delta(a,b) - \mathrm{exp}(-(a^2 + b^2)/2) \times \sum_{i=n}^{-1}\biggl(\frac{b}{a}\biggr)^{i+\Delta} \mathrm{I}_{i+\Delta}(ab)$$ and the function for $\nu = 0$ is $$Q_\nu(a,b) = Q_\Delta(a,b) + \mathrm{exp}(-(a^2 + b^2)/2)$$

Shi (2012) concludes that the merit of these two expressions is that the evaulation of the Marcum Q function is reduced to the numerical evaluation of $Q_\Delta(a,b)$. This difference can result in measurably faster computation times (confirmed by limited analysis by the author of lmomco) and possibly better numerical performance.

Shi (2012) uses notation and text that implies evaluation of the far-right additive term (the summation) for $n=0$ as part of the condition $\nu > 0$. To clarify, Shi (2012) implies for $\nu > 0; n = 0$ (but $n=0$ occurs also for $-1 < \nu <= 0$)="" the="" following="" computation="" $$q_\nu(a,b)="Q_\Delta(a,b)" +="" \mathrm{exp}(-(a^2="" b^2)="" 2)="" \times="" \biggl[\biggl(\frac{b}{a}\biggr)^{\delta}="" \mathrm{i}_{\delta}(ab)="" \biggl(\frac{b}{a}\biggr)^{\delta-1}="" \mathrm{i}_{\delta-1}(ab)\biggr]$$="" this="" result="" produces="" incompatible="" cumulative="" distribution="" functions="" of="" using="" $q_\nu(a,b)$="" for="" $-1="" <="" \nu="" 1$.="" therefore,="" author="" lmomco concludes that Shi (2012) is in error (or your author misinterprets the summation notation) and that the specific condition for $\nu = 0$ shown above and lacking $\sum$ is correct; there are three individual and separate conditions to support the Marcum Q function using the delta nu method: $\nu \le -1$, $-1 < \nu < 1$, and $\nu \ge -1$.

Usage

cdfkmu(x, para, paracheck=TRUE, marcumQ=TRUE)

Arguments

x

A real value.

para

The parameters from parkmu or similar.

paracheck

A logical controlling whether the parameters and checked for validity.

marcumQ

A logical controlling whether the Marcum Q function is used instead of numerical integration of pdfkmu.

Value

• Nonexceedance probability ($F$) for $x$.

References

Shi, Q., 2012, Semi-infinite Gauss-Hermite quadrature based approximations to the generalized Marcum and Nuttall Q-functions and further applications: First IEEE International Conference on Communications in China---Communications Theory and Security (CTS), pp. 268--273, ISBN 978-1-4673-2815-9,12.

Yacoub, M.D., 2007, The kappa-mu distribution and the eta-mu distribution: IEEE Antennas and Propagation Magazine, v. 49, no. 1, pp. 68--81.

See Also

pdfkmu, quakmu, parkmu

Examples

x <- seq(0,3, by=0.5)
para <- vec2par(c(0.69, 0.625), type="kmu")
cdfkmu(x, para, marcumQ=TRUE)
cdfkmu(x, para, marcumQ=FALSE)

delx <- 0.01
x <- seq(0,3, by=delx)

plot(c(0,3), c(0,1), xlab="RHO", ylab="cdfkmu(RHO)", type="n")
para <- list(para=c(0, 0.75), type="kmu")
cdf <- cdfkmu(x, para)
lines(x, cdf, col=2, lwd=4)
para <- list(para=c(1, 0.5625), type="kmu")
cdf <- cdfkmu(x, para)
lines(x, cdf, col=3, lwd=4)

kappas <- c(0.00000001, 0.69, 1.37,  2.41, 4.45, 10.48, 28.49)
mus    <- c(0.75, 0.625,  0.5,  0.375, 0.25,  0.125, 0.05)
for(i in 1:length(kappas)) {
   kappa <- kappas[i]
   mu    <- mus[i]
   para <- list(para=c(kappa, mu), type="kmu")
   cdf <- cdfkmu(x, para)
   lines(x, cdf, col=i)
}


delx <- 0.0005
x <- seq(0,3, by=delx)
nx <- 20*log10(x)
plot(c(-30,10), 10^c(-4,0), log="y", xaxs="i", yaxs="i",
     xlab="RHO", ylab="cdfkmu(RHO)", type="n")
m <- 1.25
mus <- c(0.25, 0.50, 0.75, 1, 1.25, 0)
for(mu in mus) {
   col <- 1
   kappa <- m/mu - 1 + sqrt((m/mu)*((m/mu)-1))
   para <- vec2par(c(kappa, mu), type="kmu")
   if(! is.finite(kappa)) {
      para <- vec2par(c(Inf,m), type="kmu")
      col <- 2
   }
   lines(nx, cdfkmu(x, para), col=col)
}
mtext("Yacoub (2007, figure 4)")