`kummerM()`: `eps` argument added.

Help page: further elements in the Details section.

R/estparnormratio.R

@@ -12,19 +12,34 @@ estparnormratio <- function(z, eps = 1e-06) {
   #' @usage estparnormratio(z, eps = 1e-6)
   #' @param z numeric matrix or data frame.
   #' @param eps numeric. Precision for the estimation of the parameters.
-  #' @return A list of 5 elements:
-  #' \itemize{
-  #' \item \code{x}: the mean \eqn{\hat{\mu}_x} and standard deviation \eqn{\hat{\sigma}_x} of the first distribution.
-  #' \item \code{y}: the mean \eqn{\hat{\mu}_y} and standard deviation \eqn{\hat{\sigma}_y} of the second distribution.
-  #' \item \code{beta}, \code{rho}, \code{delta}: the parameters of the \eqn{Z} distribution:
-  #' \eqn{\displaystyle{\hat{\delta}_y = \frac{\hat{\sigma}_y}{\hat{\mu}_y}}},
-  #' \eqn{\displaystyle{\hat{\beta} = \frac{\hat{\mu}_x}{\hat{\mu}_y}}},
-  #' \eqn{\displaystyle{\hat{\rho} = \frac{\hat{\sigma}_y}{\hat{\sigma}_x}}}.
-  #' }
+  #' @return A list of 3 elements \code{beta}, \code{rho}, \code{delta}:
+  #' the parameters of the \eqn{Z} distribution:
+  #' \eqn{\hat{\beta}}, \eqn{\hat{\rho}}, \eqn{\hat{\delta}_y},
   #' with two attributes \code{attr(, "epsilon")} (precision of the result) and \code{attr(, "k")} (number of iterations).
   #'
-  #' @details The parameters \eqn{\beta}, \eqn{\rho}, \eqn{\delta_y} are estimated with the EM algorithm
-  #' as presented in El Ghaziri et al. The computation uses the \code{\link{kummerM}} function.
+  #' @details Let a random variable: \eqn{\displaystyle{Z = \frac{X}{Y}}},
+  #' 
+  #' \eqn{X} and \eqn{Y} being normally distributed:
+  #' \eqn{X \sim N(\mu_x, \sigma_x)} and \eqn{Y \sim N(\mu_y, \sigma_y)}.
+  #' 
+  #' The density probability of \eqn{Z} is:
+  #' \deqn{\displaystyle{
+  #' f_Z(z; \beta, \rho, \delta_y) = \frac{\rho}{\pi (1 + \rho^2 z^2)} \ \exp{\left(-\frac{\rho^2 \beta^2 + 1}{2\delta_y^2}\right)} \ {}_1 F_1\left( 1, \frac{1}{2}; \frac{1}{2 \delta_y} \frac{(1 + \beta \rho^2 z)^2}{1 + \rho^2 z^2} \right)
+  #' }}
+  #' 
+  #' where: \eqn{\displaystyle{\hat{\beta} = \frac{\hat{\mu}_x}{\hat{\mu}_y}}},
+  #' \eqn{\displaystyle{\hat{\rho} = \frac{\hat{\sigma}_y}{\hat{\sigma}_x}}},
+  #' \eqn{\displaystyle{\hat{\delta}_y = \frac{\hat{\sigma}_y}{\hat{\mu}_y}}}.
+  #' 
+  #' and \eqn{_1 F_1\left(a, b; x\right)} is the confluent \eqn{D}-hypergeometric function:
+  #' \deqn{\displaystyle{
+  #' _1 F_1\left(a, b; x\right) = \sum_{n = 0}^{+\infty}{ \frac{ (a)_n }{ (b)_n } \frac{x^n}{n!} }
+  #' }}
+  #' 
+  #' The parameters \eqn{\beta}, \eqn{rho}, \eqn{delta_y} of the \eqn{Z} distribution
+  #' are estimated with the EM algorithm, as presented in El Ghaziri et al.
+  #' The computation uses the \code{\link{kummerM}} function.
+  #' 
   #' This uses an iterative algorithm.
   #'
   #' The precision for the estimation of the parameters is given by the \code{eps} parameter.
@@ -67,11 +82,11 @@ estparnormratio <- function(z, eps = 1e-06) {
   #' @export
 
   kummA <- function(x) {
-    Re(kummerM(2, 1.5, x))/Re(kummerM(1, 0.5, x))
+    Re(kummerM(2, 1.5, x))/Re(kummerM(1, 0.5, x, eps = eps))
   }
 
   kummB <- function(x) {
-    Re(kummerM(2, 0.5, x))/Re(kummerM(1, 0.5, x))
+    Re(kummerM(2, 0.5, x))/Re(kummerM(1, 0.5, x, eps = eps))
   }
 
   # Number of observations