More doc

Author: andrjohns

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: boostmath
 Title: 'R' Bindings for the 'Boost' Math Functions
-Version: 1.4.0
+Version: 1.4.0.9000
 Authors@R:
     person(c("Andrew", "R."), "Johnson", , "andrew.johnson@arjohnsonau.com", role = c("aut", "cre"),
            comment = c(ORCID = "0000-0001-7000-8065"))

R/basic_functions.R

@@ -36,9 +36,9 @@
 #' @return A single numeric value with the computed result of the function.
 #' @seealso [Boost Documentation](https://www.boost.org/doc/libs/latest/libs/math/doc/html/math_toolkit/powers.html) for more details on the mathematical background.
 #' @examples
-#' # sin(π/2) = 1 (exact)
+#' # sin(pi/2) = 1 (exact)
 #' sin_pi(0.5)
-#' # cos(π/2) = 0 (exact)
+#' # cos(pi/2) = 0 (exact)
 #' cos_pi(0.5)
 #' # log(1 + x) for small x
 #' log1p_boost(0.001)

R/bernoulli_distribution.R

@@ -11,8 +11,8 @@
 #' \deqn{F(0)=1-p, \quad F(1)=1}
 #'
 #' @param x Quantile value (must be 0 or 1).
-#' @param p_success Probability of success (0 ≤ p_success ≤ 1).
-#' @param p Probability (0 ≤ p ≤ 1).
+#' @param p_success Probability of success (0 <= p_success <= 1).
+#' @param p Probability (0 <= p <= 1).
 #' @return A single numeric value with the computed probability density, log-probability density, cumulative distribution, log-cumulative distribution, or quantile depending on the function called.
 #' @seealso [Boost Documentation](https://www.boost.org/doc/libs/latest/libs/math/doc/html/math_toolkit/dist_ref/dists/bernoulli_dist.html) for more details on the mathematical background.
 #' @examples

R/bessel_functions.R

@@ -14,7 +14,7 @@
 #'
 #' \deqn{J_v(x) = \left(\frac{1}{2}x\right)^v\sum_{k=0}^\infty{\frac{\left(-\frac{1}{4}x^2\right)^k}{k!\Gamma(v+k+1)}}}
 #'
-#' * `cyl_neumann(v, x)`: Computes the Bessel function of the second kind \eqn{Y_v(x) = N_V(x)}:
+#' * `cyl_neumann(v, x)`: Computes the Bessel function of the second kind \eqn{Y_v(x) = N_v(x)}:
 #'
 #' \deqn{Y_v(x) = \frac{J_v(x)\cos(v\pi) - J_{-v}(x)}{\sin(v\pi)}}
 #'

R/beta_distribution.R

@@ -25,10 +25,10 @@
 #'
 #' Where \eqn{I_{p}^{-1}} is the inverse of the regularized incomplete beta function.
 #'
-#' @param x Quantile value (0 ≤ x ≤ 1).
+#' @param x Quantile value (0 <= x <= 1).
 #' @param alpha Shape parameter (alpha > 0).
 #' @param beta Shape parameter (beta > 0).
-#' @param p Probability (0 ≤ p ≤ 1).
+#' @param p Probability (0 <= p <= 1).
 #' @param mean Mean of the Beta distribution.
 #' @param variance Variance of the Beta distribution.
 #' @return A single numeric value with the computed probability density, log-probability density, cumulative distribution, log-cumulative distribution, or quantile depending on the function called.

R/beta_functions.R

@@ -1,36 +1,82 @@
 #' @title Beta Functions
 #' @name beta_functions
-#' @description Functions to compute the Euler beta function, normalised incomplete beta function, and their complements, as well as their inverses and derivatives.
-#' @param a First parameter of the beta function
-#' @param b Second parameter of the beta function
+#' @description
+#' Functions to compute the Beta function, normalized incomplete beta function,
+#' and their complements, as well as their inverses and derivatives.
+#'
+#' **Beta Function \eqn{B(a, b)}:**
+#'
+#' * `beta_boost(a, b)`
+#'
+#' \deqn{B(a, b) = \frac{\Gamma(a)\Gamma(b)}{\Gamma(a+b)}}
+#'
+#'
+#' **Incomplete Beta Functions:**
+#'
+#' * **Normalized (Regularized) Functions:**
+#'   - `ibeta(a, b, x)`: Normalized incomplete beta function \eqn{I_x(a, b)}
+#'
+#' \deqn{I_x(a,b) = \frac{1}{B(a, b)}\int_{0}^{x}t^{a-1}(1-t)^{b-1}dt}
+#'
+#'   - `ibetac(a, b, x)`: Normalized complement, \eqn{1 - I_x(a, b) = I_{1-x}(b, a)}
+#'
+#' * **Non-normalized Functions:**
+#'   - `beta_boost(a, b, x)`: Full incomplete beta function \eqn{B_x(a, b)}
+#'
+#' \deqn{\int_{0}^{x}t^{a-1}(1-t)^{b-1}dt}
+#'
+#'   - `betac(a, b, x)`: Full complement , \eqn{1 - B_x(a, b) = B_{1-x}(b, a)}
+#'
+#'
+#' **Inverse Functions:**
+#'
+#' * **Primary inverses (solving for x):**
+#'   - `ibeta_inv(a, b, p)`: Returns \eqn{x} such that \eqn{p = I_x(a, b)}
+#'   - `ibetac_inv(a, b, q)`: Returns \eqn{x} such that \eqn{q = 1 - I_x(a, b)}
+#'
+#' * **Parameter inverses (solving for a or b):**
+#'   - `ibeta_inva(b, x, p)`: Returns a such that \eqn{p} = I_x(a, b)
+#'   - `ibetac_inva(b, x, q)`: Returns a such that \eqn{q} = 1 - I_x(a, b)
+#'   - `ibeta_invb(a, x, p)`: Returns b such that \eqn{p} = I_x(a, b)
+#'   - `ibetac_invb(a, x, q)`: Returns b such that \eqn{q} = 1 - I_x(a, b)
+#'
+#' **Derivatives:**
+#'
+#' `ibeta_derivative(a, b, x)`: Computes the partial derivative with respect to x
+#' of the incomplete beta function
+#'
+#' \deqn{\frac{\partial}{\partial x}I_x(a,b) = \frac{(1-x)^{b-1}x^{a-1}}{B(a,b)}}
+#'
+#' @param a First parameter of the beta function (must be positive)
+#' @param b Second parameter of the beta function (must be positive)
 #' @param x Upper limit of integration (0 <= x <= 1)
 #' @param p Probability value (0 <= p <= 1)
-#' @param q Probability value (0 <= q <= 1)
-#' @return A single numeric value with the computed beta function, normalised incomplete beta function, or their complements, depending on the function called.
+#' @param q Probability value (0 <= q <= 1), where q = 1 - p
+#' @return A single numeric value with the computed beta function, normalized incomplete beta function, or their complements, depending on the function called.
 #' @seealso [Boost Documentation](https://www.boost.org/doc/libs/latest/libs/math/doc/html/math_toolkit/sf_beta.html) for more details on the mathematical background.
 #' @examples
 #' \dontrun{
 #' # Euler beta function B(2, 3)
 #' beta_boost(2, 3)
-#' # Normalised incomplete beta function I_x(2, 3) for x = 0.5
+#' # Normalized incomplete beta function I_x(2, 3) for x = 0.5
 #' ibeta(2, 3, 0.5)
-#' # Normalised complement of the incomplete beta function 1 - I_x(2, 3) for x = 0.5
+#' # Normalized complement of the incomplete beta function 1 - I_x(2, 3) for x = 0.5
 #' ibetac(2, 3, 0.5)
 #' # Full incomplete beta function B_x(2, 3) for x = 0.5
 #' beta_boost(2, 3, 0.5)
 #' # Full complement of the incomplete beta function 1 - B_x(2, 3) for x = 0.5
 #' betac(2, 3, 0.5)
-#' # Inverse of the normalised incomplete beta function I_x(2, 3) = 0.5
+#' # Inverse of the normalized incomplete beta function I_x(2, 3) = 0.5
 #' ibeta_inv(2, 3, 0.5)
-#' # Inverse of the normalised complement of the incomplete beta function I_x(2, 3) = 0.5
+#' # Inverse of the normalized complement of the incomplete beta function I_x(2, 3) = 0.5
 #' ibetac_inv(2, 3, 0.5)
-#' # Inverse of the normalised complement of the incomplete beta function I_x(a, b)
+#' # Inverse of the normalized complement of the incomplete beta function I_x(a, b)
 #' # with respect to a for x = 0.5 and q = 0.5
 #' ibetac_inva(3, 0.5, 0.5)
-#' # Inverse of the normalised incomplete beta function I_x(a, b)
+#' # Inverse of the normalized incomplete beta function I_x(a, b)
 #' # with respect to b for x = 0.5 and p = 0.5
 #' ibeta_invb(0.8, 0.5, 0.5)
-#' # Inverse of the normalised complement of the incomplete beta function I_x(a, b)
+#' # Inverse of the normalized complement of the incomplete beta function I_x(a, b)
 #' # with respect to b for x = 0.5 and q = 0.5
 #' ibetac_invb(2, 0.5, 0.5)
 #' # Derivative of the incomplete beta function with respect to x for a = 2, b = 3, x = 0.5

R/binomial_distribution.R

@@ -1,6 +1,16 @@
 #' @title Binomial Distribution Functions
 #' @name binomial_distribution
-#' @description Functions to compute the probability density function, cumulative distribution function, and quantile function for the Binomial distribution.
+#' @description Functions to compute the probability density function, cumulative distribution function,
+#' and quantile function for the Binomial distribution.
+#'
+#' The PDF is:
+#'
+#' \deqn{f(k; n, p) = \frac{n!}{k!(n-k)!}p^k(1-p)^{n-k}}
+#'
+#' The CDF is:
+#'
+#' \deqn{1 - I_p(k + 1, n - k)}
+#'
 #' @param k number of successes (0 <= k <= n)
 #' @param n number of trials (n >= 0)
 #' @param prob probability of success on each trial (0 <= prob <= 1)

R/bivariate_statistics.R

@@ -1,6 +1,14 @@
 #' @title Bivariate Statistics Functions
 #' @name bivariate_statistics
 #' @description Functions to compute various bivariate statistics.
+#'
+#' * `covariance(x, y)`: Compute population covariance of `x` & `y`
+#' * `means_and_covariance(x, y)`: Boost estimates the means as part of the covariance estimation,
+#' return them in a single pass
+#' * `correlation_coefficient(x, y)`: Perason correlation coefficient of `x` & `y`
+#'
+#'
+#'
 #' @seealso [Boost Documentation](https://www.boost.org/doc/libs/latest/libs/math/doc/html/math_toolkit/bivariate_statistics.html) for more details on the mathematical background.
 #' @param x A numeric vector.
 #' @param y A numeric vector.

R/cauchy_distribution.R

@@ -1,6 +1,16 @@
 #' @title Cauchy Distribution Functions
 #' @name cauchy_distribution
-#' @description Functions to compute the probability density function, cumulative distribution function, and quantile function for the Cauchy distribution.
+#' @description Functions to compute the probability density function, cumulative distribution function,
+#' and quantile function for the Cauchy distribution.
+#'
+#' The PDF is:
+#'
+#' \deqn{f(x; x_0, \gamma) = \frac{1}{\pi}\left(\frac{\gamma}{(x-x_0)^2 + \gamma^2}\right)}
+#'
+#' The CDF:
+#'
+#' \deqn{F(x; x_0, \gamma) = \frac{1}{\pi}\text{arctan}\left(\frac{x-x_0}{\gamma}\right)+\frac{1}{2}}
+#'
 #' @param x quantile
 #' @param location location parameter (default is 0)
 #' @param scale scale parameter (default is 1)

R/chatterjee_correlation.R

@@ -1,6 +1,9 @@
 #' @title Chatterjee Correlation Function
 #' @name chatterjee_correlation
-#' @description Functions to compute the Chatterjee correlation.
+#' @description Compute the Chatterjee correlation coefficient, a rank-based coefficient:
+#'
+#' \deqn{\xi_n(X,Y) = 1 - \frac{3\sum_{i=1}^{n-1}|r_{i+1} - r_i|}{n^2 - 1}}
+#'
 #' @seealso [Boost Documentation](https://www.boost.org/doc/libs/latest/libs/math/doc/html/math_toolkit/chatterjee_correlation.html) for more details on the mathematical background.
 #' @param x A numeric vector.
 #' @param y A numeric vector.