From 6b5abb8289e3135b3c0a6771dca3b7346fa01d4b Mon Sep 17 00:00:00 2001
From: Pierre Santagostini <pierre.santagostini@agrocampus-ouest.fr>
Date: Mon, 10 Feb 2025 18:21:11 +0100
Subject: [PATCH] Corrections in the help page
---
R/dnormratio.R | 8 ++++----
R/estparnormratio.R | 23 ++++++++++++-----------
R/lnpochhammer.R | 2 +-
R/pochhammer.R | 3 ++-
R/rnormratio.R | 14 +++++++-------
man/dnormratio.Rd | 10 ++++++----
man/estparnormratio.Rd | 23 ++++++++++++-----------
man/lnpochhammer.Rd | 2 +-
man/pochhammer.Rd | 3 ++-
man/rnormratio.Rd | 19 +++++++++++--------
10 files changed, 58 insertions(+), 49 deletions(-)
diff --git a/R/dnormratio.R b/R/dnormratio.R
index b5c5aa0..e477e21 100644
--- a/R/dnormratio.R
+++ b/R/dnormratio.R
@@ -1,7 +1,7 @@
dnormratio <- function (z, bet, rho, delta) {
#' Ratio of two Gaussian distributions
#'
- #' Density of the ratio of two Gaussian distributions with strictly positive means and variances.
+ #' Density of the ratio of two Gaussian distributions<!-- with strictly positive means and variances -->.
#'
#' @aliases dnormratio
#'
@@ -9,9 +9,9 @@ dnormratio <- function (z, bet, rho, delta) {
#' @param z length \eqn{p} numeric vector.
#' @param bet,rho,delta numeric values. The parameters \eqn{(\beta, \rho, \delta)} of the distribution, see Details.
#'
- #' @details Let two random variables
- #' \eqn{X \sim N(\mu_x, \sigma_x)} and \eqn{Y \sim N(\mu_y, \sigma_y)}
- #' with \eqn{\mu_x > 0} and \eqn{\mu_y > 0}.
+ #' @details Let two independant random variables
+ #' \eqn{X \sim N(\mu_x, \sigma_x)} and \eqn{Y \sim N(\mu_y, \sigma_y)}.
+ #' <!-- with \eqn{\mu_x > 0} and \eqn{\mu_y > 0}. -->
#'
#' If we denote \eqn{\beta = \frac{\mu_x}{\mu_y}}, \eqn{\rho = \frac{\sigma_y}{\sigma_x}} and \eqn{\delta_y = \frac{\sigma_y}{\mu_y}},
#' the probability distribution function of the ratio \eqn{Z = \frac{X}{Y}}
diff --git a/R/estparnormratio.R b/R/estparnormratio.R
index f32ea83..bc7d0f7 100644
--- a/R/estparnormratio.R
+++ b/R/estparnormratio.R
@@ -1,8 +1,8 @@
estparnormratio <- function(z, eps = 1e-06) {
- #' Estimation of the Distribution Parameters of the Ratio of two Gaussian Distributions
+ #' Estimation of the Parameters of a Normal Ratio Distribution
#'
- #' Estimation of the parameters of the distribution of a ratio of two distributions
- #' \eqn{\displaystyle{Z = \frac{X}{Y}}},
+ #' Estimation of the parameters of <!-- the distribution of a ratio of two distributions -->
+ #' a ratio \eqn{\displaystyle{Z = \frac{X}{Y}}},
#' \eqn{X} and \eqn{Y} being two independant random variables distributed
#' according to Gaussian distributions,
#' using the EM (estimation-maximization) algorithm.
@@ -13,7 +13,7 @@ estparnormratio <- function(z, eps = 1e-06) {
#' @param z numeric matrix or data frame.
#' @param eps numeric. Precision for the estimation of the parameters.
#' @return A list of 3 elements \code{beta}, \code{rho}, \code{delta}:
- #' the parameters of the \eqn{Z} distribution:
+ #' the estimated 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).
#'
@@ -24,19 +24,20 @@ estparnormratio <- function(z, eps = 1e-06) {
#'
#' 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)
+ #' 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^2} \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}}}.
+ #' with: \eqn{\displaystyle{\beta = \frac{\mu_x}{\mu}_y}},
+ #' \eqn{\displaystyle{\rho = \frac{\sigma_y}{\sigma_x}}},
+ #' \eqn{\displaystyle{\delta_y = \frac{\sigma_y}{\mu_y}}}.
#'
- #' and \eqn{_1 F_1\left(a, b; x\right)} is the confluent \eqn{D}-hypergeometric function:
+ #' and \eqn{_1 F_1\left(a, b; x\right)} is the confluent hypergeometric function
+ #' (Kummer's 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
+ #' 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.
#'
@@ -51,7 +52,7 @@ estparnormratio <- function(z, eps = 1e-06) {
#' Remote Sensing 15(2), 528 (2023).
#' \doi{10.3390/rs15020528}
#'
- #' @seealso [dnormratio()]: probability density of a Gaussian ratio.
+ #' @seealso [dnormratio()]: probability density of a normal ratio.
#'
#' [rnormratio()]: sample simulation.
#'
diff --git a/R/lnpochhammer.R b/R/lnpochhammer.R
index 4311020..5ad07e5 100644
--- a/R/lnpochhammer.R
+++ b/R/lnpochhammer.R
@@ -16,7 +16,7 @@ lnpochhammer <- function(x, n) {
#'
#' If \eqn{n = 0}, \eqn{\displaystyle{ log\left((x)_n\right) = log(1) = 0}}
#' @seealso \code{\link{pochhammer}},
- #' \code{\link{lauricella}}
+ #' \code{\link{kummerM}}
#' @author Pierre Santagostini, Nizar Bouhlel
#'
#' @examples
diff --git a/R/pochhammer.R b/R/pochhammer.R
index 3b00178..5954a80 100644
--- a/R/pochhammer.R
+++ b/R/pochhammer.R
@@ -11,7 +11,8 @@ pochhammer <- function(x, n) {
#' @return Numeric value. The value of the Pochhammer symbol.
#' @details The Pochhammer symbol is given by:
#' \deqn{ \displaystyle{ (x)_n = \frac{\Gamma(x+n)}{\Gamma(x)} = x (x+1) ... (x+n-1) } }
- #' @seealso \code{\link{lauricella}}
+ #' @seealso \code{\link{lnpochhammer}},
+ #' \code{\link{kummerM}}
#' @author Pierre Santagostini, Nizar Bouhlel
#'
#' @examples
diff --git a/R/rnormratio.R b/R/rnormratio.R
index 76cd792..ae6de71 100644
--- a/R/rnormratio.R
+++ b/R/rnormratio.R
@@ -1,7 +1,7 @@
rnormratio <- function (n, bet, rho, delta) {
#' Ratio of two Gaussian distributions
#'
- #' Simulate data from a ratio of two Gaussian distributions with strictly positive means and variances.
+ #' Simulate data from a ratio of two Gaussian distributions<!-- with strictly positive means and variances -->.
#'
#' @aliases rnormratio
#'
@@ -11,13 +11,13 @@ rnormratio <- function (n, bet, rho, delta) {
#'
#' @details Let two random variables
#' \eqn{X \sim N(\mu_x, \sigma_x)} and \eqn{Y \sim N(\mu_y, \sigma_y)}
- #' (\eqn{\mu_x > 0}, \eqn{\mu_y > 0})
- #' with probability densities \eqn{f_X(\dot)} and \eqn{f_Y(\dot)}
+ #' <!-- (\eqn{\mu_x > 0}, \eqn{\mu_y > 0}) -->
+ #' with probability densities \eqn{f_X} and \eqn{f_Y}.
#'
#' The parameters of the distribution of the ratio \eqn{Z = \frac{X}{Y}} are:
- #' \deqn{\displaystyle{\beta = \frac{\mu_x}{\mu_y}}}
- #' \deqn{\displaystyle{\rho = \frac{\sigma_y}{\sigma_x}}}
- #' \deqn{\displaystyle{\delta_y = \frac{\sigma_y}{\mu_y}}}
+ #' \eqn{\displaystyle{\beta = \frac{\mu_x}{\mu_y}}},
+ #' \eqn{\displaystyle{\rho = \frac{\sigma_y}{\sigma_x}}},
+ #' \eqn{\displaystyle{\delta_y = \frac{\sigma_y}{\mu_y}}}.
#'
#' \eqn{\mu_x}, \eqn{\sigma_x}, \eqn{\mu_y} and \eqn{\sigma_y} are computed from
#' \eqn{\beta}, \eqn{\rho} and \eqn{\delta_y} (by fixing arbitrarily \eqn{\mu_x = 1})
@@ -26,7 +26,7 @@ rnormratio <- function (n, bet, rho, delta) {
#'
#' Then \eqn{\displaystyle{\left( \frac{x_1}{y_1}, \dots, \frac{x_n}{y_n} \right)}} is returned.
#'
- #' @seealso [dnormratio()]: probability density of a Gaussian ratio.
+ #' @seealso [dnormratio()]: probability density of a normal ratio.
#'
#' [estparnormratio()]: parameter estimation.
#'
diff --git a/man/dnormratio.Rd b/man/dnormratio.Rd
index c11f5f1..80ff1ad 100644
--- a/man/dnormratio.Rd
+++ b/man/dnormratio.Rd
@@ -12,12 +12,14 @@ dnormratio(z, bet, rho, delta)
\item{bet, rho, delta}{numeric values. The parameters \eqn{(\beta, \rho, \delta)} of the distribution, see Details.}
}
\description{
-Density of the ratio of two Gaussian distributions with strictly positive means and variances.
+Density of the ratio of two Gaussian distributions\if{html}{\out{<!-- with strictly positive means and variances -->}}.
}
\details{
-Let two random variables
-\eqn{X \sim N(\mu_x, \sigma_x)} and \eqn{Y \sim N(\mu_y, \sigma_y)}
-with \eqn{\mu_x > 0} and \eqn{\mu_y > 0}.
+Let two independant random variables
+\eqn{X \sim N(\mu_x, \sigma_x)} and \eqn{Y \sim N(\mu_y, \sigma_y)}.\if{html}{\out{
+<!-- with \eqn{\mu_x > 0} and \eqn{\mu_y > 0}. -->
+}}
+
If we denote \eqn{\beta = \frac{\mu_x}{\mu_y}}, \eqn{\rho = \frac{\sigma_y}{\sigma_x}} and \eqn{\delta_y = \frac{\sigma_y}{\mu_y}},
the probability distribution function of the ratio \eqn{Z = \frac{X}{Y}}
diff --git a/man/estparnormratio.Rd b/man/estparnormratio.Rd
index 55df272..1c8046a 100644
--- a/man/estparnormratio.Rd
+++ b/man/estparnormratio.Rd
@@ -2,7 +2,7 @@
% Please edit documentation in R/estparnormratio.R
\name{estparnormratio}
\alias{estparnormratio}
-\title{Estimation of the Distribution Parameters of the Ratio of two Gaussian Distributions}
+\title{Estimation of the Parameters of a Normal Ratio Distribution}
\usage{
estparnormratio(z, eps = 1e-6)
}
@@ -13,13 +13,13 @@ estparnormratio(z, eps = 1e-6)
}
\value{
A list of 3 elements \code{beta}, \code{rho}, \code{delta}:
-the parameters of the \eqn{Z} distribution:
+the estimated 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).
}
\description{
-Estimation of the parameters of the distribution of a ratio of two distributions
-\eqn{\displaystyle{Z = \frac{X}{Y}}},
+Estimation of the parameters of \if{html}{\out{<!-- the distribution of a ratio of two distributions -->}}
+a ratio \eqn{\displaystyle{Z = \frac{X}{Y}}},
\eqn{X} and \eqn{Y} being two independant random variables distributed
according to Gaussian distributions,
using the EM (estimation-maximization) algorithm.
@@ -32,19 +32,20 @@ Let a random variable: \eqn{\displaystyle{Z = \frac{X}{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)
+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^2} \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}}}.
+with: \eqn{\displaystyle{\beta = \frac{\mu_x}{\mu}_y}},
+\eqn{\displaystyle{\rho = \frac{\sigma_y}{\sigma_x}}},
+\eqn{\displaystyle{\delta_y = \frac{\sigma_y}{\mu_y}}}.
-and \eqn{_1 F_1\left(a, b; x\right)} is the confluent \eqn{D}-hypergeometric function:
+and \eqn{_1 F_1\left(a, b; x\right)} is the confluent hypergeometric function
+(Kummer's 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
+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.
@@ -83,7 +84,7 @@ Remote Sensing 15(2), 528 (2023).
\doi{10.3390/rs15020528}
}
\seealso{
-\code{\link[=dnormratio]{dnormratio()}}: probability density of a Gaussian ratio.
+\code{\link[=dnormratio]{dnormratio()}}: probability density of a normal ratio.
\code{\link[=rnormratio]{rnormratio()}}: sample simulation.
}
diff --git a/man/lnpochhammer.Rd b/man/lnpochhammer.Rd
index 7ca9d21..ed337ce 100644
--- a/man/lnpochhammer.Rd
+++ b/man/lnpochhammer.Rd
@@ -33,7 +33,7 @@ lnpochhammer(2, 3)
}
\seealso{
\code{\link{pochhammer}},
-\code{\link{lauricella}}
+\code{\link{kummerM}}
}
\author{
Pierre Santagostini, Nizar Bouhlel
diff --git a/man/pochhammer.Rd b/man/pochhammer.Rd
index 1054b4f..5cfa5e6 100644
--- a/man/pochhammer.Rd
+++ b/man/pochhammer.Rd
@@ -28,7 +28,8 @@ pochhammer(2, 3)
}
\seealso{
-\code{\link{lauricella}}
+\code{\link{lnpochhammer}},
+\code{\link{kummerM}}
}
\author{
Pierre Santagostini, Nizar Bouhlel
diff --git a/man/rnormratio.Rd b/man/rnormratio.Rd
index e9ca2cc..56a80f5 100644
--- a/man/rnormratio.Rd
+++ b/man/rnormratio.Rd
@@ -12,18 +12,21 @@ rnormratio(n, bet, rho, delta)
\item{bet, rho, delta}{numeric values. The parameters \eqn{(\beta, \rho, \delta)} of the distribution, see Details.}
}
\description{
-Simulate data from a ratio of two Gaussian distributions with strictly positive means and variances.
+Simulate data from a ratio of two Gaussian distributions\if{html}{\out{<!-- with strictly positive means and variances -->}}.
}
\details{
Let two random variables
-\eqn{X \sim N(\mu_x, \sigma_x)} and \eqn{Y \sim N(\mu_y, \sigma_y)}
-(\eqn{\mu_x > 0}, \eqn{\mu_y > 0})
-with probability densities \eqn{f_X(\dot)} and \eqn{f_Y(\dot)}
+\eqn{X \sim N(\mu_x, \sigma_x)} and \eqn{Y \sim N(\mu_y, \sigma_y)}\if{html}{\out{
+<!-- (\eqn{\mu_x > 0}, \eqn{\mu_y > 0}) -->
+}}
+
+
+with probability densities \eqn{f_X} and \eqn{f_Y}.
The parameters of the distribution of the ratio \eqn{Z = \frac{X}{Y}} are:
-\deqn{\displaystyle{\beta = \frac{\mu_x}{\mu_y}}}
-\deqn{\displaystyle{\rho = \frac{\sigma_y}{\sigma_x}}}
-\deqn{\displaystyle{\delta_y = \frac{\sigma_y}{\mu_y}}}
+\eqn{\displaystyle{\beta = \frac{\mu_x}{\mu_y}}},
+\eqn{\displaystyle{\rho = \frac{\sigma_y}{\sigma_x}}},
+\eqn{\displaystyle{\delta_y = \frac{\sigma_y}{\mu_y}}}.
\eqn{\mu_x}, \eqn{\sigma_x}, \eqn{\mu_y} and \eqn{\sigma_y} are computed from
\eqn{\beta}, \eqn{\rho} and \eqn{\delta_y} (by fixing arbitrarily \eqn{\mu_x = 1})
@@ -53,7 +56,7 @@ Remote Sensing 15(2), 528 (2023).
\doi{10.3390/rs15020528}
}
\seealso{
-\code{\link[=dnormratio]{dnormratio()}}: probability density of a Gaussian ratio.
+\code{\link[=dnormratio]{dnormratio()}}: probability density of a normal ratio.
\code{\link[=estparnormratio]{estparnormratio()}}: parameter estimation.
}
--
GitLab